rcl  master
C API providing common ROS client library functionality.
Classes | Typedefs | Functions
guard_condition.h File Reference
#include "rcl/allocator.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...
 

Functions

rcl_guard_condition_t rcl_get_zero_initialized_guard_condition (void)
 Return a rcl_guard_condition_t struct with members set to NULL. More...
 
rcl_ret_t rcl_guard_condition_init (rcl_guard_condition_t *guard_condition, const rcl_guard_condition_options_t options)
 Initialize a rcl guard_condition. More...
 
rcl_ret_t rcl_guard_condition_init_from_rmw (rcl_guard_condition_t *guard_condition, const rmw_guard_condition_t *rmw_guard_condition, const rcl_guard_condition_options_t options)
 Same as rcl_guard_condition_init(), but reusing an existing rmw handle. More...
 
rcl_ret_t rcl_guard_condition_fini (rcl_guard_condition_t *guard_condition)
 Finalize a rcl_guard_condition_t. More...
 
rcl_guard_condition_options_t rcl_guard_condition_get_default_options (void)
 Return the default options in a rcl_guard_condition_options_t struct. More...
 
rcl_ret_t rcl_trigger_guard_condition (rcl_guard_condition_t *guard_condition)
 Trigger a rcl guard condition. More...
 
const rcl_guard_condition_options_t * rcl_guard_condition_get_options (const rcl_guard_condition_t *guard_condition)
 Return the guard condition options. More...
 
rmw_guard_condition_t * rcl_guard_condition_get_rmw_handle (const rcl_guard_condition_t *guard_condition)
 Return the rmw guard condition handle. More...
 

Typedef Documentation

◆ rcl_guard_condition_t

typedef struct rcl_guard_condition_t rcl_guard_condition_t

Handle for a rcl guard condition.

◆ rcl_guard_condition_options_t

typedef struct rcl_guard_condition_options_t rcl_guard_condition_options_t

Options available for a rcl guard condition.

Function Documentation

◆ rcl_get_zero_initialized_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_guard_condition_init()

rcl_ret_t rcl_guard_condition_init ( rcl_guard_condition_t *  guard_condition,
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:

#include <rcl/rcl.h>
// ... error handling
rcl_guard_condition_t guard_condition = rcl_get_zero_initialized_guard_condition();
// ... customize guard condition options
rcl_ret_t ret = rcl_guard_condition_init(
&guard_condition, rcl_guard_condition_get_default_options());
// ... error handling, and on shutdown do deinitialization:
ret = rcl_guard_condition_fini(&guard_condition);
// ... error handling for rcl_guard_condition_fini()
Attribute Adherence
Allocates Memory Yes
Thread-Safe No
Uses Atomics No
Lock-Free Yes
Parameters
[in,out]guard_conditionpreallocated guard_condition structure
[in]optionsthe guard_condition's options
Returns
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_guard_condition_init_from_rmw()

rcl_ret_t rcl_guard_condition_init_from_rmw ( rcl_guard_condition_t *  guard_condition,
const rmw_guard_condition_t *  rmw_guard_condition,
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
Parameters
[in,out]guard_conditionpreallocated guard_condition structure
[in]rmw_guard_conditionexisting rmw guard condition to reuse
[in]optionsthe guard_condition's options
Returns
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_guard_condition_fini()

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()

Parameters
[in,out]guard_conditionhandle to the guard_condition to be finalized
Returns
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_get_default_options()

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_trigger_guard_condition()

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:

  • guard condition is NULL
  • guard condition is invalid (never called init or called fini)

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

Parameters
[in]guard_conditionhandle to the guard_condition to be triggered
Returns
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.

◆ rcl_guard_condition_get_options()

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:

  • guard_condition is NULL
  • guard_condition is invalid (never called init, called fini, or invalid node)

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
Parameters
[in]guard_conditionpointer to the rcl guard_condition
Returns
rcl guard condition options if successful, otherwise NULL

◆ rcl_guard_condition_get_rmw_handle()

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:

  • guard_condition is NULL
  • guard_condition is invalid (never called init, called fini, or invalid node)

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
Parameters
[in]guard_conditionpointer to the rcl guard_condition
Returns
rmw guard condition handle if successful, otherwise NULL
Generated by   doxygen 1.8.13