rcl  beta1
C API providing common ROS client library functionality.
Classes | Macros | Typedefs | Enumerations | Functions
time.h File Reference
#include "rcl/macros.h"
#include "rcl/types.h"
#include "rcl/visibility_control.h"

Go to the source code of this file.

Classes

struct  rcl_time_source_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...
 
struct  rcl_duration_t
 A duration of time, measured in nanoseconds and its source. More...
 

Macros

#define RCL_S_TO_NS(seconds)   (seconds * (1000 * 1000 * 1000))
 Convenience macro to convert seconds to nanoseconds. More...
 
#define RCL_MS_TO_NS(milliseconds)   (milliseconds * (1000 * 1000))
 Convenience macro to convert milliseconds to nanoseconds. More...
 
#define RCL_US_TO_NS(microseconds)   (microseconds * 1000)
 Convenience macro to convert microseconds to nanoseconds. More...
 
#define RCL_NS_TO_S(nanoseconds)   (nanoseconds / (1000 * 1000 * 1000))
 Convenience macro to convert nanoseconds to seconds. More...
 
#define RCL_NS_TO_MS(nanoseconds)   (nanoseconds / (1000 * 1000))
 Convenience macro to convert nanoseconds to milliseconds. More...
 
#define RCL_NS_TO_US(nanoseconds)   (nanoseconds / 1000)
 Convenience macro to convert nanoseconds to microseconds. More...
 

Typedefs

typedef uint64_t rcl_time_point_value_t
 A single point in time, measured in nanoseconds since the Unix epoch. More...
 
typedef int64_t rcl_duration_value_t
 A duration of time, measured in nanoseconds. More...
 
typedef struct rcl_time_source_t rcl_time_source_t
 Encapsulation of a time source. More...
 
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. More...
 
typedef struct rcl_duration_t rcl_duration_t
 A duration of time, measured in nanoseconds and its source. More...
 

Enumerations

enum  rcl_time_source_type_t { RCL_TIME_SOURCE_UNINITIALIZED = 0, RCL_ROS_TIME, RCL_SYSTEM_TIME, RCL_STEADY_TIME }
 Time source type, used to indicate the source of a time measurement. More...
 

Functions

bool rcl_time_source_valid (rcl_time_source_t *time_source)
 Check if the time_source has valid values. More...
 
rcl_ret_t rcl_init_ros_time_source (rcl_time_source_t *time_source)
 Initialize a time_source as a RCL_ROS_TIME time source. More...
 
rcl_ret_t rcl_fini_ros_time_source (rcl_time_source_t *time_source)
 Finalize a time_source as a RCL_ROS_TIME time source. More...
 
rcl_ret_t rcl_init_steady_time_source (rcl_time_source_t *time_source)
 Initialize a time_source as a RCL_STEADY_TIME time source. More...
 
rcl_ret_t rcl_fini_steady_time_source (rcl_time_source_t *time_source)
 Finalize a time_source as a RCL_STEADY_TIME time source. More...
 
rcl_ret_t rcl_init_system_time_source (rcl_time_source_t *time_source)
 Initialize a time_source as a RCL_SYSTEM_TIME time source. More...
 
rcl_ret_t rcl_fini_system_time_source (rcl_time_source_t *time_source)
 Finalize a time_source as a RCL_SYSTEM_TIME time source. More...
 
rcl_ret_t rcl_init_time_point (rcl_time_point_t *time_point, rcl_time_source_t *time_source)
 Initialize a time point using the time_source. More...
 
rcl_ret_t rcl_fini_time_point (rcl_time_point_t *time_point)
 Finalize a time_point. More...
 
rcl_ret_t rcl_init_duration (rcl_duration_t *duration, rcl_time_source_t *time_source)
 Initialize a duration using the time_source. More...
 
rcl_ret_t rcl_fini_duration (rcl_duration_t *duration)
 Finalize a duration. More...
 
rcl_time_source_trcl_get_default_ros_time_source (void)
 Get the default RCL_ROS_TIME time source. More...
 
rcl_time_source_trcl_get_default_steady_time_source (void)
 Get the default RCL_STEADY_TIME time source. More...
 
rcl_time_source_trcl_get_default_system_time_source (void)
 Get the default RCL_SYSTEM_TIME time source. More...
 
rcl_ret_t rcl_set_default_ros_time_source (rcl_time_source_t *process_time_source)
 Set the current time on the RCL_ROS_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_get_time_point_now (rcl_time_point_t *time_point)
 Fill the time point with the current value of the associated clock. More...
 
rcl_ret_t rcl_enable_ros_time_override (rcl_time_source_t *time_source)
 Enable the ROS time abstraction override. More...
 
rcl_ret_t rcl_disable_ros_time_override (rcl_time_source_t *time_source)
 Disable the ROS time abstraction override. More...
 
rcl_ret_t rcl_is_enabled_ros_time_override (rcl_time_source_t *time_source, 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_time_source_t *time_source, rcl_time_point_value_t time_value)
 Set the current time for this RCL_ROS_TIME time source. More...
 
rcl_ret_t rcl_system_time_now (rcl_time_point_value_t *now)
 Retrieve the current time as a rcl_time_point_value_t. More...
 
rcl_ret_t rcl_steady_time_now (rcl_time_point_value_t *now)
 Retrieve the current time as a rcl_time_point_value_t object. More...
 

Macro Definition Documentation

§ RCL_S_TO_NS

#define RCL_S_TO_NS (   seconds)    (seconds * (1000 * 1000 * 1000))

Convenience macro to convert seconds to nanoseconds.

§ RCL_MS_TO_NS

#define RCL_MS_TO_NS (   milliseconds)    (milliseconds * (1000 * 1000))

Convenience macro to convert milliseconds to nanoseconds.

§ RCL_US_TO_NS

#define RCL_US_TO_NS (   microseconds)    (microseconds * 1000)

Convenience macro to convert microseconds to nanoseconds.

§ RCL_NS_TO_S

#define RCL_NS_TO_S (   nanoseconds)    (nanoseconds / (1000 * 1000 * 1000))

Convenience macro to convert nanoseconds to seconds.

§ RCL_NS_TO_MS

#define RCL_NS_TO_MS (   nanoseconds)    (nanoseconds / (1000 * 1000))

Convenience macro to convert nanoseconds to milliseconds.

§ RCL_NS_TO_US

#define RCL_NS_TO_US (   nanoseconds)    (nanoseconds / 1000)

Convenience macro to convert nanoseconds to microseconds.

Typedef Documentation

§ rcl_time_point_value_t

typedef uint64_t rcl_time_point_value_t

A single point in time, measured in nanoseconds since the Unix epoch.

§ rcl_duration_value_t

typedef int64_t rcl_duration_value_t

A duration of time, measured in nanoseconds.

§ rcl_time_source_t

Encapsulation of a time source.

§ rcl_time_point_t

A single point in time, measured in nanoseconds, the reference point is based on the source.

§ rcl_duration_t

A duration of time, measured in nanoseconds and its source.

Enumeration Type Documentation

§ rcl_time_source_type_t

Time source type, used to indicate the source of a time measurement.

Enumerator
RCL_TIME_SOURCE_UNINITIALIZED 
RCL_ROS_TIME 
RCL_SYSTEM_TIME 
RCL_STEADY_TIME 

Function Documentation

§ rcl_time_source_valid()

bool rcl_time_source_valid ( rcl_time_source_t time_source)

Check if the time_source 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.

Parameters
[in]time_sourcethe handle to the time_source which is being queried
Returns
true if the source is believed to be valid, otherwise return false.

§ rcl_init_ros_time_source()

rcl_ret_t rcl_init_ros_time_source ( rcl_time_source_t time_source)

Initialize a time_source 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.

Parameters
[in]time_sourcethe handle to the time_source which is being initialized
Returns
RCL_RET_OK if the time source was successfully initialized, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_ERROR an unspecified error occur.

§ rcl_fini_ros_time_source()

rcl_ret_t rcl_fini_ros_time_source ( rcl_time_source_t time_source)

Finalize a time_source 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.

Parameters
[in]time_sourcethe handle to the time_source which is being initialized
Returns
RCL_RET_OK if the time source was successfully finalized, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_ERROR an unspecified error occur.

§ rcl_init_steady_time_source()

rcl_ret_t rcl_init_steady_time_source ( rcl_time_source_t time_source)

Initialize a time_source 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.

Parameters
[in]time_sourcethe handle to the time_source which is being initialized
Returns
RCL_RET_OK if the time source was successfully initialized, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_ERROR an unspecified error occur.

§ rcl_fini_steady_time_source()

rcl_ret_t rcl_fini_steady_time_source ( rcl_time_source_t time_source)

Finalize a time_source as a RCL_STEADY_TIME time source.

Finalize the time_source 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.

Parameters
[in]time_sourcethe handle to the time_source which is being initialized
Returns
RCL_RET_OK if the time source was successfully finalized, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_ERROR an unspecified error occur.

§ rcl_init_system_time_source()

rcl_ret_t rcl_init_system_time_source ( rcl_time_source_t time_source)

Initialize a time_source as a RCL_SYSTEM_TIME time source.

Initialize the time_source 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.

Parameters
[in]time_sourcethe handle to the time_source which is being initialized
Returns
RCL_RET_OK if the time source was successfully initialized, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_ERROR an unspecified error occur.

§ rcl_fini_system_time_source()

rcl_ret_t rcl_fini_system_time_source ( rcl_time_source_t time_source)

Finalize a time_source as a RCL_SYSTEM_TIME time source.

Finalize the time_source 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.

Parameters
[in]time_sourcethe handle to the time_source which is being initialized.
Returns
RCL_RET_OK if the time source was successfully finalized, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_ERROR an unspecified error occur.

§ rcl_init_time_point()

rcl_ret_t rcl_init_time_point ( rcl_time_point_t time_point,
rcl_time_source_t time_source 
)

Initialize a time point using the time_source.

This function will initialize the time_point using the time_source as a reference. If the time_source is null it will use the system default time_source.

This will allocate all necessary internal structures, and initialize variables. The time_source may be of types RCL_ROS_TIME, RCL_STEADY_TIME, or RCL_SYSTEM_TIME.

Parameters
[in]time_pointthe handle to the time_source which is being initialized.
[in]time_sourcethe handle to the time_source will be used for reference.
Returns
RCL_RET_OK if the last call time was retrieved successfully, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_ERROR an unspecified error occur.

§ rcl_fini_time_point()

rcl_ret_t rcl_fini_time_point ( rcl_time_point_t time_point)

Finalize a time_point.

Finalize the time_point such that it is ready for deallocation.

This will deallocate all necessary internal structures, and clean up any variables.

Parameters
[in]time_pointthe handle to the time_source which is being finalized.
Returns
RCL_RET_OK if the last call time was retrieved successfully, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_ERROR an unspecified error occur.

§ rcl_init_duration()

rcl_ret_t rcl_init_duration ( rcl_duration_t duration,
rcl_time_source_t time_source 
)

Initialize a duration using the time_source.

This function will initialize the duration using the time_source as a reference. If the time_source is null it will use the system default time_source.

This will allocate all necessary internal structures, and initialize variables. The time_source may be of types ros, steady, or system.

Parameters
[in]durationthe handle to the duration which is being initialized.
[in]time_sourcethe handle to the time_source will be used for reference.
Returns
RCL_RET_OK if the last call time was retrieved successfully, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_ERROR an unspecified error occur.

§ rcl_fini_duration()

rcl_ret_t rcl_fini_duration ( rcl_duration_t duration)

Finalize a duration.

Finalize the duration such that it is ready for deallocation.

This will deallocate all necessary internal structures, and clean up any variables.

Parameters
[in]durationthe handle to the duration which is being finalized.
Returns
RCL_RET_OK if the last call time was retrieved successfully, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_ERROR an unspecified error occur.

§ rcl_get_default_ros_time_source()

rcl_time_source_t* rcl_get_default_ros_time_source ( void  )

Get the default RCL_ROS_TIME time source.

This function will get the process default time source. This time source is specifically of the ROS time abstraction, and may be overridden by updates.

If the default has not yet been used it will allocate and initialize the time source.

Returns
rcl_time_source_t if it successfully found or allocated a time source. If an error occurred it will return NULL.

§ rcl_get_default_steady_time_source()

rcl_time_source_t* rcl_get_default_steady_time_source ( void  )

Get the default RCL_STEADY_TIME time source.

This function will get the process default time source. This time source is specifically of the steady time abstraction, it should not be able to be overridden..

If the default has not yet been used it will allocate and initialize the time source.

Returns
rcl_time_source_t if it successfully found or allocated a time source. If an error occurred it will return NULL.

§ rcl_get_default_system_time_source()

rcl_time_source_t* rcl_get_default_system_time_source ( void  )

Get the default RCL_SYSTEM_TIME time source.

This function will get the process default time source. This time source is specifically of the system time abstraction, and may be overridden by updates to the system clock.

If the default has not yet been used it will allocate and initialize the time source.

Returns
rcl_time_source_t if it successfully found or allocated a time source. If an error occurred it will return NULL.

§ rcl_set_default_ros_time_source()

rcl_ret_t rcl_set_default_ros_time_source ( rcl_time_source_t process_time_source)

Set the current time on the RCL_ROS_TIME time source.

This function is used to set the time on a ROS time source. It will error if passed a different time source.

This should not block, except on Windows. One caveat is that if the ROS time abstraction is active, it will invoke the user defined callbacks, for pre and post update notifications. The callbacks are supposed to be short running and non-blocking.

Parameters
[in]process_time_sourceThe time source on which to set the value.
Returns
RCL_RET_OK if the value was set successfully, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_ERROR an unspecified error occur.

§ rcl_difference_times()

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.

Parameters
[in]startThe time point for the start of the duration.
[in]finishThe time point for the end of the duration.
[out]deltaThe duration between the start and finish.
Returns
RCL_RET_OK if the difference was computed successfully, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_ERROR an unspecified error occur.

§ rcl_get_time_point_now()

rcl_ret_t rcl_get_time_point_now ( rcl_time_point_t time_point)

Fill the time point with the current value of the associated clock.

This function will populate the data of the time_point object with the current value from it's associated time abstraction.

Parameters
[out]time_pointThe time_point to populate.
Returns
RCL_RET_OK if the last call time was retrieved successfully, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_ERROR an unspecified error occur.

§ rcl_enable_ros_time_override()

rcl_ret_t rcl_enable_ros_time_override ( rcl_time_source_t time_source)

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.

Parameters
[in]time_sourceThe time_source to enable.
Returns
RCL_RET_OK if the time source was enabled successfully, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_ERROR an unspecified error occur.

§ rcl_disable_ros_time_override()

rcl_ret_t rcl_disable_ros_time_override ( rcl_time_source_t time_source)

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.

Parameters
[in]time_sourceThe time_source to disable.
Returns
RCL_RET_OK if the time source was disabled successfully, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_ERROR an unspecified error occur.

§ rcl_is_enabled_ros_time_override()

rcl_ret_t rcl_is_enabled_ros_time_override ( rcl_time_source_t time_source,
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.

Parameters
[in]time_sourceThe time_source to query.
[out]is_enabledWhether the override is enabled..
Returns
RCL_RET_OK if the time source was queried successfully, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_ERROR an unspecified error occur.

§ rcl_set_ros_time_override()

rcl_ret_t rcl_set_ros_time_override ( rcl_time_source_t time_source,
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.

Parameters
[in]time_sourceThe time_source to update.
[in]time_valueThe new current time.
Returns
RCL_RET_OK if the time source was set successfully, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_ERROR an unspecified error occur.

§ rcl_system_time_now()

rcl_ret_t rcl_system_time_now ( rcl_time_point_value_t now)

Retrieve the current time as a rcl_time_point_value_t.

This function returns the time from a system clock. The closest equivalent would be to std::chrono::system_clock::now();

The resolution (e.g. nanoseconds vs microseconds) is not guaranteed.

The now argument must point to an allocated rcl_system_time_point_t struct, as the result is copied into this variable.


Attribute Adherence
Allocates Memory No
Thread-Safe Yes
Uses Atomics No
Lock-Free Yes [1]

[1] if atomic_is_lock_free() returns true for atomic_int_least64_t

Todo:
TODO(tfoote): consider moving this to rmw for more reuse
Parameters
[out]nowa datafield in which the current time is stored
Returns
RCL_RET_OK if the current time was successfully obtained, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_ERROR an unspecified error occur.

§ rcl_steady_time_now()

rcl_ret_t rcl_steady_time_now ( rcl_time_point_value_t now)

Retrieve the current time as a rcl_time_point_value_t object.

This function returns the time from a monotonically increasing clock. The closest equivalent would be to std::chrono::steady_clock::now();

The resolution (e.g. nanoseconds vs microseconds) is not guaranteed.

The now argument must point to an allocated rcl_time_point_value_t object, as the result is copied into this variable.


Attribute Adherence
Allocates Memory No
Thread-Safe Yes
Uses Atomics No
Lock-Free Yes [1]

[1] if atomic_is_lock_free() returns true for atomic_int_least64_t

Todo:
TODO(tfoote): consider moving this to rmw for more reuse
Parameters
[out]nowa struct in which the current time is stored
Returns
RCL_RET_OK if the current time was successfully obtained, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_ERROR an unspecified error occur.