Skip to content

Commit

Permalink
Refine rcl_clock_t API thread-safety documentation.
Browse files Browse the repository at this point in the history 
Signed-off-by: Michel Hidalgo <[email protected]>
  • Loading branch information
@hidmic
hidmic committed Mar 12, 2020
1 parent 03d4a76 commit ca78af8
Showing 1 changed file with 59 additions and 18 deletions.
77 changes: 59 additions & 18 deletions rcl/include/rcl/time.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -173,11 +173,13 @@ rcl_clock_valid(rcl_clock_t * clock);
* Attribute | Adherence
* ------------------ | -------------
* Allocates Memory | Yes [1]
* Thread-Safe | No
* Thread-Safe | No [2]
* Uses Atomics | No
* Lock-Free | Yes
*
* <i>[1] If `clock_type` is `RCL_ROS_TIME`</i>
* <i>[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.</i>
*
* \param[in] clock_type the type identifying the time source to provide
* \param[in] clock the handle to the clock which is being initialized
Expand Down Expand Up @@ -208,10 +210,14 @@ rcl_clock_init(
* Attribute | Adherence
* ------------------ | -------------
* Allocates Memory | No
* Thread-Safe | No
* Thread-Safe | No [1]
* Uses Atomics | No
* Lock-Free | Yes
*
* <i>[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.</i>
*
* \param[in] clock the handle to the clock which is being finalized
* \return `RCL_RET_OK` if the time source was successfully finalized, or
* \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or
Expand All @@ -232,10 +238,13 @@ rcl_clock_fini(
* Attribute | Adherence
* ------------------ | -------------
* Allocates Memory | Yes
* Thread-Safe | No
* Thread-Safe | No [1]
* Uses Atomics | No
* Lock-Free | Yes
*
* <i>[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.</i>
*
* \param[in] clock the handle to the clock which is being initialized
* \param[in] allocator The allocator to use for allocations
* \return `RCL_RET_OK` if the time source was successfully initialized, or
Expand All @@ -262,10 +271,14 @@ rcl_ros_clock_init(
* Attribute | Adherence
* ------------------ | -------------
* Allocates Memory | No
* Thread-Safe | No
* Thread-Safe | No [1]
* Uses Atomics | No
* Lock-Free | Yes
*
* <i>[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.</i>
*
* \param[in] clock the handle to the clock which is being initialized
* \return `RCL_RET_OK` if the time source was successfully finalized, or
* \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or
Expand All @@ -286,10 +299,13 @@ rcl_ros_clock_fini(
* Attribute | Adherence
* ------------------ | -------------
* Allocates Memory | No
* Thread-Safe | No
* Thread-Safe | No [1]
* Uses Atomics | No
* Lock-Free | Yes
*
* <i>[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.</i>
*
* \param[in] clock the handle to the clock which is being initialized
* \param[in] allocator The allocator to use for allocations
* \return `RCL_RET_OK` if the time source was successfully initialized, or
Expand Down Expand Up @@ -318,10 +334,14 @@ rcl_steady_clock_init(
* Attribute | Adherence
* ------------------ | -------------
* Allocates Memory | No
* Thread-Safe | No
* Thread-Safe | No [1]
* Uses Atomics | No
* Lock-Free | Yes
*
* <i>[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.</i>
*
* \param[in] clock the handle to the clock which is being initialized
* \return `RCL_RET_OK` if the time source was successfully finalized, or
* \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or
Expand All @@ -344,10 +364,14 @@ rcl_steady_clock_fini(
* Attribute | Adherence
* ------------------ | -------------
* Allocates Memory | No
* Thread-Safe | No
* Thread-Safe | No [1]
* Uses Atomics | No
* Lock-Free | Yes
*
* <i>[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.</i>
*
* \param[in] clock the handle to the clock which is being initialized
* \param[in] allocator The allocator to use for allocations
* \return `RCL_RET_OK` if the time source was successfully initialized, or
Expand Down Expand Up @@ -375,10 +399,14 @@ rcl_system_clock_init(
* Attribute | Adherence
* ------------------ | -------------
* Allocates Memory | No
* Thread-Safe | No
* Thread-Safe | No [1]
* Uses Atomics | No
* Lock-Free | Yes
*
* <i>[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.</i>
*
* \param[in] clock the handle to the clock which is being initialized.
* \return `RCL_RET_OK` if the time source was successfully finalized, or
* \return `RCL_RET_INVALID_ARGUMENT` if any arguments are invalid, or
Expand Down Expand Up @@ -433,7 +461,7 @@ rcl_difference_times(
* Uses Atomics | Yes [1]
* Lock-Free | Yes
*
* <i>[1] If `clock` is of `RCL_ROS_TIME` type</i>
* <i>[1] If `clock` is of `RCL_ROS_TIME` type.</i>
*
* \param[in] clock The time source from which to set the value.
* \param[out] time_point_value The time_point value to populate.
Expand Down Expand Up @@ -461,11 +489,12 @@ rcl_clock_get_now(rcl_clock_t * clock, rcl_time_point_value_t * time_point_value
* Attribute | Adherence [1]
* ------------------ | -------------
* Allocates Memory | No
* Thread-Safe | No
* Thread-Safe | No [2]
* Uses Atomics | No
* Lock-Free | Yes
*
* <i>[1] Only applies to the function itself, as jump callbacks may not abide to it</i>
* <i>[1] Only applies to the function itself, as jump callbacks may not abide to it.</i>
* <i>[2] Function is reentrant, but concurrent calls on the same `clock` object are not safe.</i>
*
* \param[in] clock The clock to enable.
* \return `RCL_RET_OK` if the time source was enabled successfully, or
Expand All @@ -491,11 +520,12 @@ rcl_enable_ros_time_override(rcl_clock_t * clock);
* Attribute | Adherence [1]
* ------------------ | -------------
* Allocates Memory | No
* Thread-Safe | No
* Thread-Safe | No [2]
* Uses Atomics | No
* Lock-Free | Yes
*
* <i>[1] Only applies to the function itself, as jump callbacks may not abide to it</i>
* <i>[1] Only applies to the function itself, as jump callbacks may not abide to it.</i>
* <i>[2] Function is reentrant, but concurrent calls on the same `clock` object are not safe.</i>
*
* \param[in] clock The clock to disable.
* \return `RCL_RET_OK` if the time source was disabled successfully, or
Expand All @@ -521,10 +551,12 @@ rcl_disable_ros_time_override(rcl_clock_t * clock);
* Attribute | Adherence
* ------------------ | -------------
* Allocates Memory | No
* Thread-Safe | No
* Thread-Safe | No [1]
* Uses Atomics | No
* Lock-Free | Yes
*
* <i>[1] Function is reentrant, but concurrent calls on the same `clock` object are not safe.</i>
*
* \param[in] clock The clock to query.
* \param[out] is_enabled Whether the override is enabled..
* \return `RCL_RET_OK` if the time source was queried successfully, or
Expand Down Expand Up @@ -552,11 +584,12 @@ rcl_is_enabled_ros_time_override(
* Attribute | Adherence [1]
* ------------------ | -------------
* Allocates Memory | No
* Thread-Safe | No
* Thread-Safe | No [2]
* Uses Atomics | Yes
* Lock-Free | Yes
*
* <i>[1] Only applies to the function itself, as jump callbacks may not abide to it</i>
* <i>[1] Only applies to the function itself, as jump callbacks may not abide to it.</i>
* <i>[2] Function is reentrant, but concurrent calls on the same `clock` object are not safe.</i>
*
* \param[in] clock The clock to update.
* \param[in] time_value The new current time.
Expand Down Expand Up @@ -585,10 +618,14 @@ rcl_set_ros_time_override(
* Attribute | Adherence
* ------------------ | -------------
* Allocates Memory | Yes
* Thread-Safe | No
* Thread-Safe | No [1]
* Uses Atomics | No
* Lock-Free | Yes
*
* <i>[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.</i>
*
* \param[in] clock A clock to add a jump callback to.
* \param[in] threshold Criteria indicating when to call the callback.
* \param[in] callback A callback to call.
Expand All @@ -615,10 +652,14 @@ rcl_clock_add_jump_callback(
* Attribute | Adherence
* ------------------ | -------------
* Allocates Memory | Yes
* Thread-Safe | No
* Thread-Safe | No [1]
* Uses Atomics | No
* Lock-Free | Yes
*
* <i>[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.</i>
*
* \param[in] clock The clock to remove a jump callback from.
* \param[in] threshold Criteria indicating when to call callback.
* \param[in] callback The callback to call.
Expand Down

0 comments on commit ca78af8

Please sign in to comment.