OSAPI Timer

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

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

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.
RTI_BOOL	OSAPI_Timer_delete (OSAPI_Timer_T timer)
	Delete a Timer.
RTI_BOOL	OSAPI_Timer_create_timeout (OSAPI_Timer_T timer, OSAPI_TimeoutHandle_T *out_handle, RTI_INT32 timeout, RTI_INT32 flags, OSAPI_TimeoutFunction_T timeout_handler, struct OSAPI_TimeoutUserData *user_data)
	Schedule a timeout.
RTI_BOOL	OSAPI_Timer_update_timeout (OSAPI_Timer_T timer, OSAPI_TimeoutHandle_T *out_handle, RTI_INT32 timeout)
	Reschedule a timeout.
RTI_BOOL	OSAPI_Timer_delete_timeout (OSAPI_Timer_T timer, OSAPI_TimeoutHandle_T *handle)
	Stop a previously scheduled timeout.
RTI_BOOL	OSAPI_TimeoutHandle_get_user_data (struct OSAPI_TimeoutUserData *user_data, OSAPI_TimeoutHandle_T *handle)
	Get the user_data from a handle.

---

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:
@code 
OSAPI_Timer_t my_timer;
struct OSAPI_TimerProperty timer_property = OSAPI_TimerProperty_INITIALIZER;
timer = OSAPI_Timer_new(&timer_property);
if (timer == NULL) {
    return error;
}
\endcode

The created Timer should be deleted with \ref OSAPI_Timer_delete.

@param[in] property Timer property.

@param[in] mutex Shared mutex.

\par MT Safety:

SAFE

RTI_BOOL OSAPI_Timer_delete

(

OSAPI_Timer_T

timer

)

Delete a Timer.

Delete a previously created Timer. All timeouts are cancelled.

Example:
@code 
OSAPI_Timer_t my_timer;

......

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

The created Timer should be deleted with \ref OSAPI_Timer_delete.

@param [in] timer Timer.

\par MT Safety:

SAFE

RTI_BOOL OSAPI_Timer_create_timeout	(	OSAPI_Timer_T	timer,
		OSAPI_TimeoutHandle_T *	out_handle,
		RTI_INT32	timeout,
		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,
                                    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	Timeout in ms.
[in]	flags	Flags.
[in]	timeout_handler	Function to call at timeout. Cannot be NULL.
[in]	user_data	User data associated with the timeout. Can be NULL.

MT Safety:

SAFE

RTI_BOOL OSAPI_Timer_update_timeout	(	OSAPI_Timer_T	timer,
		OSAPI_TimeoutHandle_T *	out_handle,
		RTI_INT32	timeout
	)

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);

    if (!result) {
        report error;
    }

    ......

Parameters:

[in]	timer	Timer object. Cannot be NULL.
[out]	out_handle	Reference to the timeout. Cannot be NULL.
[in]	timeout	Timeout in ms.

MT Safety:

SAFE

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:
@code 
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;
}

......

\endcode

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

\par 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:
@code 
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;
}

......

\endcode

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

\par MT Safety:

SAFE