OS_SetVAlarm


C Specification

#include <nitro/os.h>

void OS_SetVAlarm(
            OSVAlarm*           alarm , 
            s16                 count , 
            s16                 delay , 
            OSVAlarmHandler     handler , 
            void*               arg );

Description

Sets up a one-time V-count alarm

handler is called when the V-Count reaches the value specified by count. However, You can specify how long the function can wait to permit when you cannot call the exact specified V-count with other count alarms or interrupts by using the delay argument. For example, at count=100 and delay=5, V-Count is called if it is possible to call it by 105, even if it was not possible to call it by 100. When you specify 0, it is only called by the specified V-count. If OS_VALARM_DELAY_MAX, it is always called when a call is possible for the specified V-count and subsequent V-counts. VAlarms that weren't called are not called until the specified V-count of the next frame. For details, see the explanation of VAlarm in the Overview.

handler is an OSVAlarmHandler function type defined by the following:

typedef void (*OSVAlarmHandler)( void*);

When handler is called, it takes arg as an argument.

If alarm is specified for the pointer to the OSAlarm structure which the V count alarm has been set, it stops with OS_Panic.

The following example sets the V-Count alarm, calls handle when the next V-Count = 100, and displays "handler called. arg=0x12345678".

(Example)


#define COUNT   100
#define DELAY   1100
#define ARG     0x12345678

OSVAlarm        alarm;

main()
{
        :
    OS_InitVAlarm();
        :
    OS_CreateVAlarm( &alarm );
    OS_SetVAlarm( 
            &alarm , 
            COUNT , 
            handler , 
            (void*)ARG );
        :
}

void handler( void* arg )
{
        OS_Printf( "handler called. arg=0x%x\n", arg );
}

Note: Prior to NITRO-SDK 2.0 RC1, this function took only four arguments and you could not specify the delay. Internally, it was treated as delay=10. But the OS_SetOneTimeVAlarm() function was added for your use if you prefer the old format over this new one.

Arguments

alarm Pointer to the V-Count alarm structure that sets up a V-Count alarm
count The V-Count value at which the V-Count alarm is actuated (the handler is called)
delay The maximum permissible number of V-Counts for delay
handler The V-Count alarm handler
arg The argument when the V-Count alarm is called

Return Values

None

See Also

OS_InitVAlarm, OS_CancelVAlarm, OS_SetPeriodicVAlarm, OS_SetVAlarmTag , OS_SetOneTimeVAlarm

Revision History

10/22/2004 Added delay to the Arguments list and made a note referring to OS_InitVAlarm() for details
08/30/2004 Added description that the V alarm structure that has been set is not usable
02/24/2004 Initial version