rcl
master
C API providing common ROS client library functionality.
|
#include "rcl/allocator.h"
#include "rcl/context.h"
#include "rcl/macros.h"
#include "rcl/types.h"
#include "rcl/visibility_control.h"
Go to the source code of this file.
Classes | |
struct | rcl_guard_condition_t |
Handle for a rcl guard condition. More... | |
struct | rcl_guard_condition_options_t |
Options available for a rcl guard condition. More... | |
Typedefs | |
typedef struct rcl_guard_condition_t | rcl_guard_condition_t |
Handle for a rcl guard condition. More... | |
typedef struct rcl_guard_condition_options_t | rcl_guard_condition_options_t |
Options available for a rcl guard condition. More... | |
typedef struct rcl_guard_condition_t rcl_guard_condition_t |
Handle for a rcl guard condition.
typedef struct rcl_guard_condition_options_t rcl_guard_condition_options_t |
Options available for a rcl guard condition.
rcl_guard_condition_t rcl_get_zero_initialized_guard_condition | ( | void | ) |
Return a rcl_guard_condition_t struct with members set to NULL
.
rcl_ret_t rcl_guard_condition_init | ( | rcl_guard_condition_t * | guard_condition, |
rcl_context_t * | context, | ||
const rcl_guard_condition_options_t | options | ||
) |
Initialize a rcl guard_condition.
After calling this function on a rcl_guard_condition_t, it can be passed to rcl_wait() and then concurrently it can be triggered to wake-up rcl_wait().
Expected usage:
Attribute | Adherence |
---|---|
Allocates Memory | Yes |
Thread-Safe | No |
Uses Atomics | No |
Lock-Free | Yes |
[in,out] | guard_condition | preallocated guard_condition structure |
[in] | context | the context instance with which the guard condition should be associated |
[in] | options | the guard_condition's options |
RCL_RET_OK
if guard_condition was initialized successfully, or RCL_RET_ALREADY_INIT
if the guard condition is already initialized, or RCL_RET_NOT_INIT
if the given context is invalid, or RCL_RET_INVALID_ARGUMENT
if any arguments are invalid, or RCL_RET_BAD_ALLOC
if allocating memory failed, or RCL_RET_ERROR
if an unspecified error occurs. rcl_ret_t rcl_guard_condition_init_from_rmw | ( | rcl_guard_condition_t * | guard_condition, |
const rmw_guard_condition_t * | rmw_guard_condition, | ||
rcl_context_t * | context, | ||
const rcl_guard_condition_options_t | options | ||
) |
Same as rcl_guard_condition_init(), but reusing an existing rmw handle.
In addition to the documentation for rcl_guard_condition_init(), the rmw_guard_condition
parameter must not be NULL
and must point to a valid rmw guard condition.
Also the life time of the rcl guard condition is tied to the life time of the rmw guard condition. So if the rmw guard condition is destroyed before the rcl guard condition, the rcl guard condition becomes invalid.
Similarly if the resulting rcl guard condition is fini'ed before the rmw guard condition, then the rmw guard condition is no longer valid.
Attribute | Adherence |
---|---|
Allocates Memory | Yes |
Thread-Safe | No |
Uses Atomics | No |
Lock-Free | Yes |
[in,out] | guard_condition | preallocated guard_condition structure |
[in] | rmw_guard_condition | existing rmw guard condition to reuse |
[in] | context | the context instance with which the rmw guard condition was initialized with, i.e. the rmw context inside rcl context needs to match rmw context in rmw guard condition |
[in] | options | the guard_condition's options |
RCL_RET_OK
if guard_condition was initialized successfully, or RCL_RET_ALREADY_INIT
if the guard condition is already initialized, or RCL_RET_INVALID_ARGUMENT
if any arguments are invalid, or RCL_RET_BAD_ALLOC
if allocating memory failed, or RCL_RET_ERROR
if an unspecified error occurs. rcl_ret_t rcl_guard_condition_fini | ( | rcl_guard_condition_t * | guard_condition | ) |
Finalize a rcl_guard_condition_t.
After calling, calls to rcl_trigger_guard_condition() will fail when using this guard condition.
Attribute | Adherence |
---|---|
Allocates Memory | Yes |
Thread-Safe | No [1] |
Uses Atomics | No |
Lock-Free | Yes |
[1] specifically not thread-safe with rcl_trigger_guard_condition()
[in,out] | guard_condition | handle to the guard_condition to be finalized |
[in] | context | the context originally used to init the guard condition |
RCL_RET_OK
if guard_condition was finalized successfully, or RCL_RET_INVALID_ARGUMENT
if any arguments are invalid, or RCL_RET_ERROR
if an unspecified error occurs. rcl_guard_condition_options_t rcl_guard_condition_get_default_options | ( | void | ) |
Return the default options in a rcl_guard_condition_options_t struct.
The defaults are:
rcl_ret_t rcl_trigger_guard_condition | ( | rcl_guard_condition_t * | guard_condition | ) |
Trigger a rcl guard condition.
This function can fail, and return RCL_RET_INVALID_ARGUMENT, if the:
NULL
A guard condition can be triggered from any thread.
Attribute | Adherence |
---|---|
Allocates Memory | Yes |
Thread-Safe | No [1] |
Uses Atomics | No |
Lock-Free | Yes |
[1] it can be called concurrently with itself, even on the same guard condition
[in] | guard_condition | handle to the guard_condition to be triggered |
RCL_RET_OK
if the guard condition was triggered, or RCL_RET_INVALID_ARGUMENT
if any arguments are invalid, or RCL_RET_ERROR
if an unspecified error occurs. const rcl_guard_condition_options_t* rcl_guard_condition_get_options | ( | const rcl_guard_condition_t * | guard_condition | ) |
Return the guard condition options.
Returned is a pointer to the internally held rcl_guard_condition_options_t. This function can fail, and therefore return NULL
, if the:
NULL
The returned pointer is made invalid if the guard condition is finalized.
Attribute | Adherence |
---|---|
Allocates Memory | No |
Thread-Safe | No |
Uses Atomics | No |
Lock-Free | Yes |
[in] | guard_condition | pointer to the rcl guard_condition |
NULL
rmw_guard_condition_t* rcl_guard_condition_get_rmw_handle | ( | const rcl_guard_condition_t * | guard_condition | ) |
Return the rmw guard condition handle.
The handle returned is a pointer to the internally held rmw handle. This function can fail, and therefore return NULL
, if the:
NULL
The returned handle is made invalid if the guard condition is finalized or if rcl_shutdown() is called. The returned handle is not guaranteed to be valid for the life time of the guard condition as it may be finalized and recreated itself. Therefore it is recommended to get the handle from the guard condition using this function each time it is needed and avoid use of the handle concurrently with functions that might change it.
Attribute | Adherence |
---|---|
Allocates Memory | No |
Thread-Safe | No |
Uses Atomics | No |
Lock-Free | Yes |
[in] | guard_condition | pointer to the rcl guard_condition |
NULL