OSAPI Timer

Data Structures
struct	OSAPI_TimeoutUserData
	User-data passed to timer-handler. More...
struct	OSAPI_TimerProperty
	Timer properies. More...

Macros
#define	OSAPI_TIMER_PERIODIC   (0x1)
	Create a periodic timer. More...
#define	OSAPI_TIMER_ONE_SHOT   (0x0)
	Create a one-shot timer. More...

Enumerations
enum	OSAPI_TimeoutOp_t
	Action taken by timer module when a timer callback returns. More...

Functions
OSAPI_Timer_T	OSAPI_Timer_new (struct OSAPI_TimerProperty *property, struct OSAPI_Mutex *mutex)
	Create a Timer. More...
RTI_BOOL	OSAPI_Timer_delete (OSAPI_Timer_T timer)
	Delete a Timer. More...
RTI_BOOL	OSAPI_Timer_create_timeout (OSAPI_Timer_T timer, OSAPI_TimeoutHandle_T *out_handle, RTI_INT32 timeout_sec, RTI_INT32 timeout_nsec, RTI_INT32 flags, OSAPI_TimeoutFunction_T timeout_handler, struct OSAPI_TimeoutUserData *user_data)
	Schedule a timeout. More...
RTI_BOOL	OSAPI_Timer_update_timeout (OSAPI_Timer_T timer, OSAPI_TimeoutHandle_T *out_handle, RTI_INT32 timeout_sec, RTI_INT32 timeout_nsec)
	Reschedule a timeout. More...
RTI_BOOL	OSAPI_Timer_delete_timeout (OSAPI_Timer_T timer, OSAPI_TimeoutHandle_T *handle)
	Stop a previously scheduled timeout. More...
RTI_BOOL	OSAPI_TimeoutHandle_get_user_data (struct OSAPI_TimeoutUserData *user_data, OSAPI_TimeoutHandle_T *handle)
	Get the user_data from a handle. More...

Detailed Description

Macro Definition Documentation

#define OSAPI_TIMER_PERIODIC   (0x1)

Create a periodic timer.

#define OSAPI_TIMER_ONE_SHOT   (0x0)

Create a one-shot timer.

Enumeration Type Documentation

enum OSAPI_TimeoutOp_t

Action taken by timer module when a timer callback returns.

Function Documentation

OSAPI_Timer_T OSAPI_Timer_new	(	struct OSAPI_TimerProperty *	property,
		struct OSAPI_Mutex *	mutex
	)

Create a Timer.

Create a new Timer. A Timer can manage multiple timeouts.

Example:

OSAPI_Timer_t my_timer;
struct OSAPI_TimerProperty timer_property = OSAPI_TimerProperty_INITIALIZER;
timer = OSAPI_Timer_new(&timer_property);
if (timer == NULL) {
    return error;
}

The created Timer should be deleted with OSAPI_Timer_delete.

Parameters

[in]	property	Timer property.
[in]	mutex	Shared mutex.

Returns

New timer on success, NULL on failure

RTI_BOOL OSAPI_Timer_delete

(

OSAPI_Timer_T

timer

)

Delete a Timer.

Delete a previously created Timer. All timeouts are cancelled.

Example:

OSAPI_Timer_t my_timer;

......

OSAPI_Timer_delete(my_timer);
if (timer == NULL) {
    return error;
}

The created Timer should be deleted with OSAPI_Timer_delete.

Parameters

[in]

timer

Timer.

Returns

RTI_TRUE on success, RTI_FALSE on failure

MT Safety:

SAFE

RTI_BOOL OSAPI_Timer_create_timeout	(	OSAPI_Timer_T	timer,
		OSAPI_TimeoutHandle_T *	out_handle,
		RTI_INT32	timeout_sec,
		RTI_INT32	timeout_nsec,
		RTI_INT32	flags,
		OSAPI_TimeoutFunction_T	timeout_handler,
		struct OSAPI_TimeoutUserData *	user_data
	)

Schedule a timeout.

This function schedules a timeout with the specified period. The timeout can either be rescheduled automatically or a new timeout must be created.

Example:

OSAPI_Timer_t my_timer;
OSAPITimeoutHandle_t my_handle = OSAPITimeoutHandle_t_INITIALIZER;
RTI_BOOL result;
struct OSAPI_TimerEntryUserData user_data;

result = OSAPI_Timer_create_timeout(my_timer,
                                &my_handle,
                                1000,0,
                                OSAPI_TIMER_PERIODIC,
                                &user_data);

if (!result) {
    report error;
}

......

A timeout can cancelled with OSAPI_Timer_delete_timeout or the timeout can be modified with OSAPI_Timer_update_timeout.

Parameters

[in]	timer	Timer object. Cannot be NULL.
[out]	out_handle	Reference to the timeout. Cannot be NULL.
[in]	timeout_sec	The number of seconds before timeout
[in]	timeout_nsec	Additional number of nanoseconds before timeout
[in]	flags	Flags OSAPI_TIMER_PERIODIC or OSAPI_TIMER_ONE_SHOT
[in]	timeout_handler	Function to call at timeout. Cannot be NULL.
[in]	user_data	User data associated with the timeout. Can be NULL.

Returns

RTI_TRUE on success, RTI_FALSE on failure

MT Safety:

SAFE

RTI_BOOL OSAPI_Timer_update_timeout	(	OSAPI_Timer_T	timer,
		OSAPI_TimeoutHandle_T *	out_handle,
		RTI_INT32	timeout_sec,
		RTI_INT32	timeout_nsec
	)

Reschedule a timeout.

This function reschedules a previously scheduled timeout with the specified period.

Example:

OSAPI_Timer_t my_timer;
OSAPITimeoutHandle_t my_handle = OSAPITimeoutHandle_t_INITIALIZER;
RTI_BOOL result;
struct OSAPI_TimerEntryUserData user_data;

result = OSAPI_Timer_update_timeout(my_timer,
                                    &my_handle,
                                    2000,0);

if (!result) {
    report error;
}

......

Parameters

[in]	timer	Timer object. Cannot be NULL.
[out]	out_handle	Reference to the timeout. Cannot be NULL.
[in]	timeout_sec	The number of seconds before timeout
[in]	timeout_nsec	Additional number of nanoseconds before timeout

Returns

RTI_TRUE on success, RTI_FALSE on failure

RTI_BOOL OSAPI_Timer_delete_timeout	(	OSAPI_Timer_T	timer,
		OSAPI_TimeoutHandle_T *	handle
	)

Stop a previously scheduled timeout.

This function stops a previously scheduled timeout.

Example:

OSAPI_Timer_t my_timer;
OSAPITimeoutHandle_t my_handle = OSAPITimeoutHandle_t_INITIALIZER;
RTI_BOOL result;

....

result = OSAPI_Timer_stop_timer(my_timer,&my_handle);

if (!result) {
    report error;
}

......

Parameters

[in]	timer	Timer object. Cannot be NULL.
[in]	handle	Reference to the timeout. Cannot be NULL.

Returns

RTI_TRUE on success, RTI_FALSE on failure

MT Safety:

SAFE

RTI_BOOL OSAPI_TimeoutHandle_get_user_data	(	struct OSAPI_TimeoutUserData *	user_data,
		OSAPI_TimeoutHandle_T *	handle
	)

Get the user_data from a handle.

Example:

OSAPI_Timer_t my_timer;
OSAPITimeoutHandle_t my_handle = OSAPITimeoutHandle_t_INITIALIZER;
RTI_BOOL result;
struct OSAPI_TimerEntryUserData user_data;

....

result = OSAPITimeoutHandle_get_user_data(&user_data,&my_handle);

if (!result) {
    report error;
}

......

Parameters

[out]	user_data	User-data associated with handle. Cannot be NULL.
[in]	handle	Timer handle.

Returns

RTI_TRUE on success, RTI_FALSE on failure