rcl
master
C API providing common ROS client library functionality.
|
#include "rcl/allocator.h"
#include "rcl/macros.h"
#include "rcl/types.h"
#include "rcl/visibility_control.h"
#include "rcutils/time.h"
Go to the source code of this file.
Classes | |
struct | rcl_duration_t |
A duration of time, measured in nanoseconds and its source. More... | |
struct | rcl_time_jump_t |
Struct to describe a jump in time. More... | |
struct | rcl_jump_threshold_t |
Describe the prerequisites for calling a time jump callback. More... | |
struct | rcl_jump_callback_info_t |
Struct to describe an added callback. More... | |
struct | rcl_clock_t |
Encapsulation of a time source. More... | |
struct | rcl_time_point_t |
A single point in time, measured in nanoseconds, the reference point is based on the source. More... | |
Macros | |
#define | RCL_S_TO_NS RCUTILS_S_TO_NS |
Convenience macro to convert seconds to nanoseconds. | |
#define | RCL_MS_TO_NS RCUTILS_MS_TO_NS |
Convenience macro to convert milliseconds to nanoseconds. | |
#define | RCL_US_TO_NS RCUTILS_US_TO_NS |
Convenience macro to convert microseconds to nanoseconds. | |
#define | RCL_NS_TO_S RCUTILS_NS_TO_S |
Convenience macro to convert nanoseconds to seconds. | |
#define | RCL_NS_TO_MS RCUTILS_NS_TO_MS |
Convenience macro to convert nanoseconds to milliseconds. | |
#define | RCL_NS_TO_US RCUTILS_NS_TO_US |
Convenience macro to convert nanoseconds to microseconds. | |
Typedefs | |
typedef rcutils_time_point_value_t | rcl_time_point_value_t |
A single point in time, measured in nanoseconds since the Unix epoch. | |
typedef rcutils_duration_value_t | rcl_duration_value_t |
A duration of time, measured in nanoseconds. | |
typedef enum rcl_clock_type_t | rcl_clock_type_t |
Time source type, used to indicate the source of a time measurement. More... | |
typedef struct rcl_duration_t | rcl_duration_t |
A duration of time, measured in nanoseconds and its source. | |
typedef enum rcl_clock_change_t | rcl_clock_change_t |
Enumeration to describe the type of time jump. | |
typedef struct rcl_time_jump_t | rcl_time_jump_t |
Struct to describe a jump in time. | |
typedef void(* | rcl_jump_callback_t) (const struct rcl_time_jump_t *time_jump, bool before_jump, void *user_data) |
typedef struct rcl_jump_threshold_t | rcl_jump_threshold_t |
Describe the prerequisites for calling a time jump callback. | |
typedef struct rcl_jump_callback_info_t | rcl_jump_callback_info_t |
Struct to describe an added callback. | |
typedef struct rcl_clock_t | rcl_clock_t |
Encapsulation of a time source. | |
typedef struct rcl_time_point_t | rcl_time_point_t |
A single point in time, measured in nanoseconds, the reference point is based on the source. | |
Enumerations | |
enum | rcl_clock_type_t { RCL_CLOCK_UNINITIALIZED = 0, RCL_ROS_TIME, RCL_SYSTEM_TIME, RCL_STEADY_TIME } |
Time source type, used to indicate the source of a time measurement. More... | |
enum | rcl_clock_change_t { RCL_ROS_TIME_NO_CHANGE = 1, RCL_ROS_TIME_ACTIVATED = 2, RCL_ROS_TIME_DEACTIVATED = 3, RCL_SYSTEM_TIME_NO_CHANGE = 4 } |
Enumeration to describe the type of time jump. More... | |
Functions | |
bool | rcl_clock_valid (rcl_clock_t *clock) |
Check if the clock has valid values. More... | |
rcl_ret_t | rcl_clock_init (enum rcl_clock_type_t clock_type, rcl_clock_t *clock, rcl_allocator_t *allocator) |
Initialize a clock based on the passed type. More... | |
rcl_ret_t | rcl_clock_fini (rcl_clock_t *clock) |
Finalize a clock. More... | |
rcl_ret_t | rcl_ros_clock_init (rcl_clock_t *clock, rcl_allocator_t *allocator) |
Initialize a clock as a RCL_ROS_TIME time source. More... | |
rcl_ret_t | rcl_ros_clock_fini (rcl_clock_t *clock) |
Finalize a clock as a RCL_ROS_TIME time source. More... | |
rcl_ret_t | rcl_steady_clock_init (rcl_clock_t *clock, rcl_allocator_t *allocator) |
Initialize a clock as a RCL_STEADY_TIME time source. More... | |
rcl_ret_t | rcl_steady_clock_fini (rcl_clock_t *clock) |
Finalize a clock as a RCL_STEADY_TIME time source. More... | |
rcl_ret_t | rcl_system_clock_init (rcl_clock_t *clock, rcl_allocator_t *allocator) |
Initialize a clock as a RCL_SYSTEM_TIME time source. More... | |
rcl_ret_t | rcl_system_clock_fini (rcl_clock_t *clock) |
Finalize a clock as a RCL_SYSTEM_TIME time source. More... | |
rcl_ret_t | rcl_difference_times (rcl_time_point_t *start, rcl_time_point_t *finish, rcl_duration_t *delta) |
Compute the difference between two time points. More... | |
rcl_ret_t | rcl_clock_get_now (rcl_clock_t *clock, rcl_time_point_value_t *time_point_value) |
Fill the time point value with the current value of the associated clock. More... | |
rcl_ret_t | rcl_enable_ros_time_override (rcl_clock_t *clock) |
Enable the ROS time abstraction override. More... | |
rcl_ret_t | rcl_disable_ros_time_override (rcl_clock_t *clock) |
Disable the ROS time abstraction override. More... | |
rcl_ret_t | rcl_is_enabled_ros_time_override (rcl_clock_t *clock, bool *is_enabled) |
Check if the RCL_ROS_TIME time source has the override enabled. More... | |
rcl_ret_t | rcl_set_ros_time_override (rcl_clock_t *clock, rcl_time_point_value_t time_value) |
Set the current time for this RCL_ROS_TIME time source. More... | |
rcl_ret_t | rcl_clock_add_jump_callback (rcl_clock_t *clock, rcl_jump_threshold_t threshold, rcl_jump_callback_t callback, void *user_data) |
Add a callback to be called when a time jump exceeds a threshold. More... | |
rcl_ret_t | rcl_clock_remove_jump_callback (rcl_clock_t *clock, rcl_jump_callback_t callback, void *user_data) |
Remove a previously added time jump callback. More... | |
typedef enum rcl_clock_type_t rcl_clock_type_t |
Time source type, used to indicate the source of a time measurement.
RCL_ROS_TIME will report the latest value reported by a ROS time source, or if a ROS time source is not active it reports the same as RCL_SYSTEM_TIME. For more information about ROS time sources, refer to the design document: http://design.ros2.org/articles/clock_and_time.html
RCL_SYSTEM_TIME reports the same value as the system clock.
RCL_STEADY_TIME reports a value from a monotonically increasing clock.
typedef void(* rcl_jump_callback_t) (const struct rcl_time_jump_t *time_jump, bool before_jump, void *user_data) |
Signature of a time jump callback.
[in] | time_jump | A description of the jump in time. |
[in] | before_jump | Every jump callback is called twice: once before the clock changes and once after. This is true the first call and false the second. |
[in] | user_data | A pointer given at callback registration which is passed to the callback. |
enum rcl_clock_type_t |
Time source type, used to indicate the source of a time measurement.
RCL_ROS_TIME will report the latest value reported by a ROS time source, or if a ROS time source is not active it reports the same as RCL_SYSTEM_TIME. For more information about ROS time sources, refer to the design document: http://design.ros2.org/articles/clock_and_time.html
RCL_SYSTEM_TIME reports the same value as the system clock.
RCL_STEADY_TIME reports a value from a monotonically increasing clock.
Enumerator | |
---|---|
RCL_CLOCK_UNINITIALIZED | Clock uninitialized. |
RCL_ROS_TIME | Use ROS time. |
RCL_SYSTEM_TIME | Use system time. |
RCL_STEADY_TIME | Use a steady clock time. |
enum rcl_clock_change_t |
Enumeration to describe the type of time jump.
bool rcl_clock_valid | ( | rcl_clock_t * | clock | ) |
Check if the clock has valid values.
This function returns true if the time source appears to be valid. It will check that the type is not uninitialized, and that pointers are not invalid. Note that if data is uninitialized it may give a false positive.
Attribute | Adherence |
---|---|
Allocates Memory | No |
Thread-Safe | Yes |
Uses Atomics | No |
Lock-Free | Yes |
[in] | clock | the handle to the clock which is being queried |
rcl_ret_t rcl_clock_init | ( | enum rcl_clock_type_t | clock_type, |
rcl_clock_t * | clock, | ||
rcl_allocator_t * | allocator | ||
) |
Initialize a clock based on the passed type.
This will allocate all necessary internal structures, and initialize variables.
Attribute | Adherence |
---|---|
Allocates Memory | Yes [1] |
Thread-Safe | No [2] |
Uses Atomics | No |
Lock-Free | Yes |
[1] If clock_type
is RCL_ROS_TIME [2] Function is reentrant, but concurrent calls on the same clock
object are not safe. Thread-safety is also affected by that of the allocator
object.
[in] | clock_type | the type identifying the time source to provide |
[in] | clock | the handle to the clock which is being initialized |
[in] | allocator | The allocator to use for allocations |
rcl_ret_t rcl_clock_fini | ( | rcl_clock_t * | clock | ) |
Finalize a clock.
This will deallocate all necessary internal structures, and clean up any variables. It can be combined with any of the init functions.
Passing a clock with type RCL_CLOCK_UNINITIALIZED will result in RCL_RET_INVALID_ARGUMENT being returned.
This function is not thread-safe with any other function operating on the same clock object.
Attribute | Adherence |
---|---|
Allocates Memory | No |
Thread-Safe | No [1] |
Uses Atomics | No |
Lock-Free | Yes |
[1] Function is reentrant, but concurrent calls on the same clock
object are not safe. Thread-safety is also affected by that of the allocator
object associated with the clock
object.
[in] | clock | the handle to the clock which is being finalized |
rcl_ret_t rcl_ros_clock_init | ( | rcl_clock_t * | clock, |
rcl_allocator_t * | allocator | ||
) |
Initialize a clock as a RCL_ROS_TIME time source.
This will allocate all necessary internal structures, and initialize variables. It is specifically setting up a RCL_ROS_TIME time source.
Attribute | Adherence |
---|---|
Allocates Memory | Yes |
Thread-Safe | No [1] |
Uses Atomics | No |
Lock-Free | Yes |
[2] Function is reentrant, but concurrent calls on the same clock
object are not safe. Thread-safety is also affected by that of the allocator
object.
[in] | clock | the handle to the clock which is being initialized |
[in] | allocator | The allocator to use for allocations |
rcl_ret_t rcl_ros_clock_fini | ( | rcl_clock_t * | clock | ) |
Finalize a clock as a RCL_ROS_TIME time source.
This will deallocate all necessary internal structures, and clean up any variables. It is specifically setting up a RCL_ROS_TIME time source. It is expected to be paired with the init fuction.
This function is not thread-safe with any other function operating on the same clock object.
Attribute | Adherence |
---|---|
Allocates Memory | No |
Thread-Safe | No [1] |
Uses Atomics | No |
Lock-Free | Yes |
[1] Function is reentrant, but concurrent calls on the same clock
object are not safe. Thread-safety is also affected by that of the allocator
object associated with the clock
object.
[in] | clock | the handle to the clock which is being initialized |
rcl_ret_t rcl_steady_clock_init | ( | rcl_clock_t * | clock, |
rcl_allocator_t * | allocator | ||
) |
Initialize a clock as a RCL_STEADY_TIME time source.
This will allocate all necessary internal structures, and initialize variables. It is specifically setting up a RCL_STEADY_TIME time source.
Attribute | Adherence |
---|---|
Allocates Memory | No |
Thread-Safe | No [1] |
Uses Atomics | No |
Lock-Free | Yes |
[1] Function is reentrant, but concurrent calls on the same clock
object are not safe. Thread-safety is also affected by that of the allocator
object.
[in] | clock | the handle to the clock which is being initialized |
[in] | allocator | The allocator to use for allocations |
rcl_ret_t rcl_steady_clock_fini | ( | rcl_clock_t * | clock | ) |
Finalize a clock as a RCL_STEADY_TIME time source.
Finalize the clock as a RCL_STEADY_TIME time source.
This will deallocate all necessary internal structures, and clean up any variables. It is specifically setting up a steady time source. It is expected to be paired with the init fuction.
This function is not thread-safe with any other function operating on the same clock object.
Attribute | Adherence |
---|---|
Allocates Memory | No |
Thread-Safe | No [1] |
Uses Atomics | No |
Lock-Free | Yes |
[1] Function is reentrant, but concurrent calls on the same clock
object are not safe. Thread-safety is also affected by that of the allocator
object associated with the clock
object.
[in] | clock | the handle to the clock which is being initialized |
rcl_ret_t rcl_system_clock_init | ( | rcl_clock_t * | clock, |
rcl_allocator_t * | allocator | ||
) |
Initialize a clock as a RCL_SYSTEM_TIME time source.
Initialize the clock as a RCL_SYSTEM_TIME time source.
This will allocate all necessary internal structures, and initialize variables. It is specifically setting up a system time source.
Attribute | Adherence |
---|---|
Allocates Memory | No |
Thread-Safe | No [1] |
Uses Atomics | No |
Lock-Free | Yes |
[1] Function is reentrant, but concurrent calls on the same clock
object are not safe. Thread-safety is also affected by that of the allocator
object associated with the clock
object.
[in] | clock | the handle to the clock which is being initialized |
[in] | allocator | The allocator to use for allocations |
rcl_ret_t rcl_system_clock_fini | ( | rcl_clock_t * | clock | ) |
Finalize a clock as a RCL_SYSTEM_TIME time source.
Finalize the clock as a RCL_SYSTEM_TIME time source.
This will deallocate all necessary internal structures, and clean up any variables. It is specifically setting up a system time source. It is expected to be paired with the init fuction.
This function is not thread-safe with any function operating on the same clock object.
Attribute | Adherence |
---|---|
Allocates Memory | No |
Thread-Safe | No [1] |
Uses Atomics | No |
Lock-Free | Yes |
[1] Function is reentrant, but concurrent calls on the same clock
object are not safe. Thread-safety is also affected by that of the allocator
object associated with the clock
object.
[in] | clock | the handle to the clock which is being initialized. |
rcl_ret_t rcl_difference_times | ( | rcl_time_point_t * | start, |
rcl_time_point_t * | finish, | ||
rcl_duration_t * | delta | ||
) |
Compute the difference between two time points.
This function takes two time points and computes the duration between them. The two time points must be using the same time abstraction, and the resultant duration will also be of the same abstraction.
The value will be computed as duration = finish - start. If start is after finish the duration will be negative.
Attribute | Adherence |
---|---|
Allocates Memory | No |
Thread-Safe | Yes |
Uses Atomics | No |
Lock-Free | Yes |
[in] | start | The time point for the start of the duration. |
[in] | finish | The time point for the end of the duration. |
[out] | delta | The duration between the start and finish. |
rcl_ret_t rcl_clock_get_now | ( | rcl_clock_t * | clock, |
rcl_time_point_value_t * | time_point_value | ||
) |
Fill the time point value with the current value of the associated clock.
This function will populate the data of the time_point_value object with the current value from it's associated time abstraction.
Attribute | Adherence |
---|---|
Allocates Memory | No |
Thread-Safe | Yes |
Uses Atomics | Yes [1] |
Lock-Free | Yes |
[1] If clock
is of RCL_ROS_TIME type.
[in] | clock | The time source from which to set the value. |
[out] | time_point_value | The time_point value to populate. |
rcl_ret_t rcl_enable_ros_time_override | ( | rcl_clock_t * | clock | ) |
Enable the ROS time abstraction override.
This method will enable the ROS time abstraction override values, such that the time source will report the set value instead of falling back to system time.
This function is not thread-safe with rcl_clock_add_jump_callback(), nor rcl_clock_remove_jump_callback() functions when used on the same clock object.
Attribute | Adherence [1] |
---|---|
Allocates Memory | No |
Thread-Safe | No [2] |
Uses Atomics | No |
Lock-Free | Yes |
[1] Only applies to the function itself, as jump callbacks may not abide to it. [2] Function is reentrant, but concurrent calls on the same clock
object are not safe.
[in] | clock | The clock to enable. |
rcl_ret_t rcl_disable_ros_time_override | ( | rcl_clock_t * | clock | ) |
Disable the ROS time abstraction override.
This method will disable the RCL_ROS_TIME time abstraction override values, such that the time source will report the system time even if a custom value has been set.
This function is not thread-safe with rcl_clock_add_jump_callback(), nor rcl_clock_remove_jump_callback() functions when used on the same clock object.
Attribute | Adherence [1] |
---|---|
Allocates Memory | No |
Thread-Safe | No [2] |
Uses Atomics | No |
Lock-Free | Yes |
[1] Only applies to the function itself, as jump callbacks may not abide to it. [2] Function is reentrant, but concurrent calls on the same clock
object are not safe.
[in] | clock | The clock to disable. |
rcl_ret_t rcl_is_enabled_ros_time_override | ( | rcl_clock_t * | clock, |
bool * | is_enabled | ||
) |
Check if the RCL_ROS_TIME time source has the override enabled.
This will populate the is_enabled object to indicate if the time overide is enabled. If it is enabled, the set value will be returned. Otherwise this time source will return the equivalent to system time abstraction.
This function is not thread-safe with rcl_enable_ros_time_override() nor rcl_disable_ros_time_override() functions when used on the same clock object.
Attribute | Adherence |
---|---|
Allocates Memory | No |
Thread-Safe | No [1] |
Uses Atomics | No |
Lock-Free | Yes |
[1] Function is reentrant, but concurrent calls on the same clock
object are not safe.
[in] | clock | The clock to query. |
[out] | is_enabled | Whether the override is enabled.. |
rcl_ret_t rcl_set_ros_time_override | ( | rcl_clock_t * | clock, |
rcl_time_point_value_t | time_value | ||
) |
Set the current time for this RCL_ROS_TIME time source.
This function will update the internal storage for the RCL_ROS_TIME time source. If queried and override enabled the time source will return this value, otherwise it will return the system time.
This function is not thread-safe with rcl_clock_add_jump_callback(), nor rcl_clock_remove_jump_callback() functions when used on the same clock object.
Attribute | Adherence [1] |
---|---|
Allocates Memory | No |
Thread-Safe | No [2] |
Uses Atomics | Yes |
Lock-Free | Yes |
[1] Only applies to the function itself, as jump callbacks may not abide to it. [2] Function is reentrant, but concurrent calls on the same clock
object are not safe.
[in] | clock | The clock to update. |
[in] | time_value | The new current time. |
rcl_ret_t rcl_clock_add_jump_callback | ( | rcl_clock_t * | clock, |
rcl_jump_threshold_t | threshold, | ||
rcl_jump_callback_t | callback, | ||
void * | user_data | ||
) |
Add a callback to be called when a time jump exceeds a threshold.
The callback is called twice when the threshold is exceeded: once before the clock is updated, and once after. The user_data pointer is passed to the callback as the last argument. A callback and user_data pair must be unique among the callbacks added to a clock.
This function is not thread-safe with rcl_clock_remove_jump_callback(), rcl_enable_ros_time_override(), rcl_disable_ros_time_override() nor rcl_set_ros_time_override() functions when used on the same clock object.
Attribute | Adherence |
---|---|
Allocates Memory | Yes |
Thread-Safe | No [1] |
Uses Atomics | No |
Lock-Free | Yes |
[1] Function is reentrant, but concurrent calls on the same clock
object are not safe. Thread-safety is also affected by that of the allocator
object associated with the clock
object.
[in] | clock | A clock to add a jump callback to. |
[in] | threshold | Criteria indicating when to call the callback. |
[in] | callback | A callback to call. |
[in] | user_data | A pointer to be passed to the callback. |
rcl_ret_t rcl_clock_remove_jump_callback | ( | rcl_clock_t * | clock, |
rcl_jump_callback_t | callback, | ||
void * | user_data | ||
) |
Remove a previously added time jump callback.
This function is not thread-safe with rcl_clock_add_jump_callback() rcl_enable_ros_time_override(), rcl_disable_ros_time_override() nor rcl_set_ros_time_override() functions when used on the same clock object.
Attribute | Adherence |
---|---|
Allocates Memory | Yes |
Thread-Safe | No [1] |
Uses Atomics | No |
Lock-Free | Yes |
[1] Function is reentrant, but concurrent calls on the same clock
object are not safe. Thread-safety is also affected by that of the allocator
object associated with the clock
object.
[in] | clock | The clock to remove a jump callback from. |
[in] | callback | The callback to call. |
[in] | user_data | A pointer to be passed to the callback. |