RTI Connext DDS Micro C API  Version 3.0.1
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
OSAPI Timer

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

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,
&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]timerTimer object. Cannot be NULL.
[out]out_handleReference to the timeout. Cannot be NULL.
[in]timeout_secThe number of seconds before timeout
[in]timeout_nsecAdditional number of nanoseconds before timeout
[in]flagsFlags OSAPI_TIMER_PERIODIC or OSAPI_TIMER_ONE_SHOT
[in]timeout_handlerFunction to call at timeout. Cannot be NULL.
[in]user_dataUser 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]timerTimer object. Cannot be NULL.
[out]out_handleReference to the timeout. Cannot be NULL.
[in]timeout_secThe number of seconds before timeout
[in]timeout_nsecAdditional 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_dataUser-data associated with handle. Cannot be NULL.
[in]handleTimer 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.

RTI Connext DDS Micro C API Version 3.0.1 Copyright © Thu Oct 24 2019 Real-Time Innovations, Inc