OS_SetVAlarm

Syntax

#include <nitro/os.h>

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

Arguments

alarm	Pointer to the V-Count alarm structure for setting 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 calling the V-Count alarm handler

Return Values

None.

Description

Sets up a one-time V-Count alarm

handler is called when the V-Count reaches the value specified by count. The V-Count alarm handler handler is an OSVAlarmHandler function defined by the following:

typedef void (*OSVAlarmHandler)( void*);

handler is called from the OS V-Count interrupt handler. Therefore, interrupts are prohibited. When the handler is called, it takes arg as an argument.

It is possible to specify the amount of permissible delay with delay when the handler cannot be called on the specified V-Count because of another count alarm or interrupt. For example, at count=100 and delay=5, V-Count is called if it is possible to call it by count 105, even if it was not possible to call it by count 100. When you specify 0, the alarm is called only at 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. The V alarm that was not called will be postponed until the specified V-Count in the next frame. For details, see the description in VAlarm Overview.

If alarm is specified for the pointer to the OSAlarm structure in which the V-Count 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.

Revision History

2005/03/08 Standardized the Japanese word for "interrupt"
2004/10/22 Added delay to the arguments. 2004/08/30 Added description that the V alarm structure that has been set is not usable
2004/02/24 Initial version