Function rcl_timer_init

Function Documentation

rcl_ret_t rcl_timer_init(rcl_timer_t *timer, rcl_clock_t *clock, rcl_context_t *context, int64_t period, const rcl_timer_callback_t callback, rcl_allocator_t allocator)

Initialize a timer.

A timer consists of a clock, a callback function and a period. A timer can be added to a wait set and waited on, such that the wait set will wake up when a timer is ready to be executed.

A timer simply holds state and does not automatically call callbacks. It does not create any threads, register interrupts, or consume signals. For blocking behavior it can be used in conjunction with a wait set and rcl_wait(). When rcl_timer_is_ready() returns true, the timer must still be called explicitly using rcl_timer_call().

The timer handle must be a pointer to an allocated and zero initialized rcl_timer_t struct. Calling this function on an already initialized timer will fail. Calling this function on a timer struct which has been allocated but not zero initialized is undefined behavior.

The clock handle must be a pointer to an initialized rcl_clock_t struct. The life time of the clock must exceed the life time of the timer.

The period is a non-negative duration (rather an absolute time in the future). If the period is 0 then it will always be ready.

The callback is an optional argument. Valid inputs are either a pointer to the function callback, or NULL to indicate that no callback will be stored in rcl. If the callback is NULL, the caller client library is responsible for firing the timer callback. Else, it must be a function which returns void and takes two arguments, the first being a pointer to the associated timer, and the second a int64_t which is the time since the previous call, or since the timer was created if it is the first call to the callback.

Expected usage:

#include <rcl/rcl.h>

void my_timer_callback(rcl_timer_t * timer, int64_t last_call_time)
{
  // Do timer work...
  // Optionally reconfigure, cancel, or reset the timer...
}

rcl_context_t * context;  // initialized previously by rcl_init()...
rcl_clock_t clock;
rcl_allocator_t allocator = rcl_get_default_allocator();
rcl_ret_t ret = rcl_clock_init(RCL_STEADY_TIME, &clock, &allocator);
// ... error handling

rcl_timer_t timer = rcl_get_zero_initialized_timer();
ret = rcl_timer_init(
  &timer, &clock, context, RCL_MS_TO_NS(100), my_timer_callback, allocator);
// ... error handling, use the timer with a wait set, or poll it manually, then cleanup
ret = rcl_timer_fini(&timer);
// ... error handling

Attribute

Adherence

Allocates Memory

Yes

Thread-Safe

No

Uses Atomics

Yes

Lock-Free

Yes [1][2][3]

[1] if returns true for

[2] if returns true for

[3] if returns true for

Parameters:

  • timer – [inout] the timer handle to be initialized

  • clock – [in] the clock providing the current time

  • context – [in] the context that this timer is to be associated with

  • period – [in] the duration between calls to the callback in nanoseconds

  • callback – [in] the user defined function to be called every period

  • allocator – [in] the allocator to use for allocations

Returns:

RCL_RET_OK if the timer was initialized successfully, or

Returns:

RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or

Returns:

RCL_RET_ALREADY_INIT if the timer was already initialized, or

Returns:

RCL_RET_BAD_ALLOC if allocating memory failed, or

Returns:

RCL_RET_ERROR an unspecified error occur.