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.
#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_sec, RTI_INT32 timeout_nsec, 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_sec, RTI_INT32 timeout_nsec)
	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.

@return 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:
@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.

\return RTI_TRUE on success, RTI_FALSE on failure

\par 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:
@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.

\return RTI_TRUE on success, RTI_FALSE on failure

\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:

    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