#include "rcl/allocator.h"
#include "rcl/context.h"
#include "rcl/macros.h"
#include "rcl/types.h"
#include "rcl/visibility_control.h"

Include dependency graph for guard_condition.h:

This graph shows which files directly or indirectly include this file:

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.

typedef struct rcl_guard_condition_options_t	rcl_guard_condition_options_t
	Options available for a rcl guard condition.

Functions
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. More...

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. 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...

Function Documentation

◆ rcl_guard_condition_init()

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:

#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, context, 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_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

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_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_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,
		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

Parameters

[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

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_condition handle 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:

allocator = rcl_get_default_allocator()

Returns: the default options in an rcl_guard_condition_options_t struct.

◆ 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_condition handle 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_condition pointer 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_condition pointer to the rcl guard_condition

Returns: rmw guard condition handle if successful, otherwise NULL

Classes

Typedefs

Functions

Function Documentation

◆ rcl_guard_condition_init()

◆ rcl_guard_condition_init_from_rmw()

◆ rcl_guard_condition_fini()

◆ rcl_guard_condition_get_default_options()

◆ rcl_trigger_guard_condition()

◆ rcl_guard_condition_get_options()

◆ rcl_guard_condition_get_rmw_handle()