Timed callback system

The timed callback system is an RDR-discoverable interface used to set up periodic callbacks. More...

Files
file	timer.h
	Defines functions to start and end the Timed callback system.
file	timerapi.h
	Header file defining the Timed callback system.

Data Structures
struct	SW_TIMER_20110324
	Timed callback function pointer API version 20110324. More...

Macros
#define	hqn_timer_create   timer_api->hqn_timer_create
	Create a timer to call a function on a timed schedule. More...
#define	hqn_timer_reset   timer_api->hqn_timer_reset
	Set new delay and period for calling a timed callback. More...
#define	hqn_timer_destroy   timer_api->hqn_timer_destroy
	Destroy a timer event. More...

Typedefs
typedef struct TIMER_HANDLE	hqn_timer_t
	Handle for a timed callback.
typedef void()	hqn_timer_callback_fn(hqn_timer_t *timer, void *data)
	Callback function for timers. More...
typedef struct SW_TIMER_20110324	sw_timer_api_20110324
	Timed callback function pointer API version 20110324.

Detailed Description

The timed callback system is an RDR-discoverable interface used to set up periodic callbacks.

This API is small, there are calls to create timers, reset timers, and destroy timers.

Timer API discovery

The timer library API is made available via the RDR system. A timer API pointer must be discovered using RDR using class RDR_CLASS_API and type RDR_API_TIMER and assigned to a suitably-named API pointer variable before the API macros are used:

#include "apis.h"
#include "timerapi.h"
sw_timer_api_20110324 *timer_api;
// ...
{
  void *vpapi;
  SwFindRDR(RDR_CLASS_API, RDR_API_TIMER, 20110324, &vpapi, NULL);
  timer_api = vpapi;
}
// ...

The timer system is automatically started when the Harlequin RIP SDK is started. It remains active until the Harlequin RIP SDK is shutdown.

Setting up a timed callback

A timed callback is created by calling the function hqn_timer_create(). An opaque data pointer may be passed to the callback function. Any data object referred to by this pointer must have a lifetime at least as long as the timer.

This example shows how to set up a timer callback function to prevent a communications channel connection from timing out:

#include "timerapi.h"
// Data identifying a communications channel connection to keep active.
struct COMMS_CHANNEL {
 // ...
};
 
// Timer callback to use a comms channel connection to keep it alive
static void HQNCALL keep_alive_ping(hqn_time_t *timer, void* data)
{
  struct COMMS_CHANNEL *p_comms_channel = data;
  // ...send a ping to the channel...
}
 
static struct COMMS_CHANNEL comms_channel;
static hqn_timer_t *keep_alive_timer;
 
static void setup_keep_alive_ping(void)
{
  unsigned int ping_delay = 60*1000; // 60 second repeat
  // ...initialize comms_channel...
  keep_alive_timer = hqn_create_timer(0, ping_delay, keep_alive_ping,
                                      &comms_channel);
  //...
}

Once the timer has been created the callback function is called at the requested period. The callback function should take no longer than the repeat time to complete, or it should be tolerant of time delays longer than its requested repeat period. If the callback function has not returned by the end of the repeat period, the library will not call the function again but will wait until the end of the next repeat period: missed calls are not queued up to be called when the function finally returns.

Timer callback functions are always called in a separate thread. Timers with non-zero repeat times are not guaranteed to call the function in the same separate thread each time. Callback functions that use data shared with other threads will need to use the usual thread synchronization methods.

Changing the timer period

It is possible to alter the period of a repeating callback timer after it has been created by calling hqn_timer_reset(). This takes a handle of an existing timer and new first and repeat time values (still in milliseconds). For example, to reduce the keep alive time from the previous example:

{
  unsigned int new_ping_delay = 30*1000; // 30 seconds
  // ...
  hqn_timer_reset(keep_alive_timer, new_ping_delay, new_ping_delay);
  // ...
}

As with hqn_timer_create(), the first-time value is a delay until the first call and the second value is the repeating time period, with the same zero value semantics. The new timer period takes effect after any currently running timer callback.

Note

In version 20110324 of the timer API library the hqn_timer_reset() function is not implemented and has no effect when called. Users of this version of the library who want to change the period of a timed callback should first delete the timer and then create a new one with the required timer period.

Terminating a timed callback

When a timed callback is no longer needed, or the application is closing down, a timed callback can be cancelled by calling hqn_timer_destroy() using the timer's handle as returned from hqn_timer_create(). The following example shows how to remove the timer set up in the previous example code:

static void remove_keep_alive_ping(void)
{
  hqn_timer_destroy(keep_alive_timer);
}

The call to hqn_timer_destroy() allows any currently running timer callback to run to completion. This allows any resources allocated for the timer callback to be released without synchronization concerns with the callback which may have been running when the timer is removed.

hqn_timer_destroy() should not be called from the callback function.

Macro Definition Documentation

hqn_timer_create

#define hqn_timer_create   timer_api->hqn_timer_create

Create a timer to call a function on a timed schedule.

Parameters

[in]	first	Time before the first call, in milliseconds. If the time before the first call is zero then the callback will be called immediately.
[in]	repeat	Time between subsequent calls, in milliseconds. If the time between subsequent calls is zero then the callback will be called just once.
[in]	callback	Function to be called when the timer expires, with data passed to the function.
[in]	data	Pointer passed to the callback function.

Returns

Timer handle for use in hqn_timer_destroy() or hqn_timer_reset(), or NULL if the timer could not be created.

Note

A repeat time of less than 20ms is not recommended. At these short periods the operating system's scheduler time quanta becomes significant and the time between calls could vary considerably compared to that requested.

hqn_timer_destroy

#define hqn_timer_destroy   timer_api->hqn_timer_destroy

Destroy a timer event.

After a call to this function a timed callback will not happen, even if it has not yet been called.

Parameters

[in]

timer

Handle of the timer to destroy.

Note

The timer subsystem does not enforce any interpretation of the data pointer passed to the hqn_timer_create() function. If the data is allocated, its lifetime must be at least as long as the timer handle.

hqn_timer_reset

#define hqn_timer_reset   timer_api->hqn_timer_reset

Set new delay and period for calling a timed callback.

Parameters

[in]	timer	Handle of the timer to reset.
[in]	next	Time delay to the next call, in milliseconds.
[in]	repeat	Time delay between subsequent calls, in milliseconds.

Note

This function has not yet been implemented.

Typedef Documentation

hqn_timer_callback_fn

typedef void() hqn_timer_callback_fn(hqn_timer_t *timer, void *data)

Callback function for timers.

Parameters

[in]	timer	The timer handle returned for this instance of the timer.
[in,out]	data	The data pointer passed to hqn_timer_create() when the timer was created.

The timer callback function is called when the initial period specified by the hqn_timer_create() call expires, and then each time the subsequent period expires. Only one call to the callback function will be active at a time for a particular timer. If the callback function takes longer than the subsequent timeout period to run, then another callback will be called immediately after the previous callback exits.

The callback function may not reset or destroy the timer using its handle _(this functionality is intended by design, but is not yet implemented)_. If the timer is destroyed before the initial timeout period expires, then there will be no calls to the callback function.

The timer sub-system does not enforce any interpretation of the data pointer. If the data is allocated, its lifetime must be at least as long as the timer handle. It is good practice for the callback function to take responsibility for destroying the timer handle and freeing allocated data if it will not be called again.