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

Macros
#define	OSAPI_TIMER_NEW_ENTRY (0x2)
	This is a new timer entry.
#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.
RTI_BOOL	OSAPI_Timer_handle_is_valid (OSAPI_TimeoutHandle_T *h)
	Check if a handle references a valid timer entry.

Detailed Description

Macro Definition Documentation

#define OSAPI_TIMER_NEW_ENTRY (0x2)

This is a new timer entry.

#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

RTI_BOOL OSAPI_Timer_handle_is_valid ( OSAPI_TimeoutHandle_T * h )

Check if a handle references a valid timer entry.

This function can be helpful for code which must ensure a timer has been finalized.

Since OSAPI_Timer_delete_timeout() will fail if the specified handle does not match an existing timeout entry, this function can be used to detect a handle is invalid (and thus if has been likely already finalized).

This function does not perform an exhaustive search of existing timeouts to find an exact match. It only evaluates whether the handle is explicitly marked as invalid or not (which occurs during finalization).

There is no guarantee that a timeout handle actually exists for this specific handle.

Returns:: RTI_TRUE if the specified is not explicitly marked as invalid, RTI_FALSE otherwise.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation