Function rcl_timer_get_time_until_next_call

Function Documentation

rcl_ret_t rcl_timer_get_time_until_next_call(const rcl_timer_t *timer, int64_t *time_until_next_call)

Calculate and retrieve the time until the next call in nanoseconds.

This function calculates the time until the next call by adding the timer’s period to the last call time and subtracting that sum from the current time. The calculated time until the next call can be positive, indicating that it is not ready to be called as the period has not elapsed since the last call. The calculated time until the next call can also be 0 or negative, indicating that the period has elapsed since the last call and the timer should be called. A negative value indicates the timer call is overdue by that amount.

The time_until_next_call argument must point to an allocated int64_t, as the time until is copied into that instance.

Attribute

Adherence

Allocates Memory

No

Thread-Safe

Yes

Uses Atomics

Yes

Lock-Free

Yes [1]

[1] if returns true for

Parameters:

  • timer – [in] the handle to the timer that is being queried

  • time_until_next_call – [out] the output variable for the result

Returns:

RCL_RET_OK if the timer until next call was successfully calculated, or

Returns:

RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or

Returns:

RCL_RET_TIMER_INVALID if the timer->impl is invalid, or

Returns:

RCL_RET_TIMER_CANCELED if the timer is canceled, or

Returns:

RCL_RET_ERROR an unspecified error occur.