#include "rmw/init.h"
#include "rcl/allocator.h"
#include "rcl/arguments.h"
#include "rcl/init_options.h"
#include "rcl/macros.h"
#include "rcl/types.h"
#include "rcl/visibility_control.h"

Include dependency graph for context.h:

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

Go to the source code of this file.

Classes
struct	rcl_context_t
	Encapsulates the non-global state of an init/shutdown cycle. More...

Typedefs
typedef uint64_t	rcl_context_instance_id_t
	A unique ID per context instance.

typedef struct rcl_context_t	rcl_context_t
	Encapsulates the non-global state of an init/shutdown cycle. More...

Functions
rcl_context_t	rcl_get_zero_initialized_context (void)
	Return a zero initialization context object.

rcl_ret_t	rcl_context_fini (rcl_context_t *context)
	Finalize a context. More...

const rcl_init_options_t *	rcl_context_get_init_options (const rcl_context_t *context)
	Return the init options used during initialization for this context. More...

rcl_context_instance_id_t	rcl_context_get_instance_id (const rcl_context_t *context)
	Returns an unsigned integer that is unique to the given context, or `0` if invalid. More...

rcl_ret_t	rcl_context_get_domain_id (rcl_context_t context, size_t domain_id)
	Returns the context domain id. More...

bool	rcl_context_is_valid (const rcl_context_t *context)
	Return `true` if the given context is currently valid, otherwise `false`. More...

rmw_context_t *	rcl_context_get_rmw_context (rcl_context_t *context)
	Return pointer to the rmw context if the given context is currently valid, otherwise `NULL`. More...

Typedef Documentation

◆ rcl_context_t

typedef struct rcl_context_t rcl_context_t

Encapsulates the non-global state of an init/shutdown cycle.

The context is used in the creation of top level entities like nodes and guard conditions, as well as to shutdown a specific instance of init.

Here is a diagram of a typical context's lifecycle:

   +---------------+
   |               |
+--> uninitialized +---> rcl_get_zero_initialized_context() +
|  |               |                                        |
|  +---------------+                                        |
|                                                           |
|           +-----------------------------------------------+
|           |
|  +--------v---------+                +-----------------------+
|  |                  |                |                       |
|  | zero-initialized +-> rcl_init() +-> initialized and valid +-> rcl_shutdown() +
|  |                  |                |                       |                  |
|  +------------------+                +-----------------------+                  |
|                                                                                 |
|               +-----------------------------------------------------------------+
|               |
|  +------------v------------+
|  |                         |
|  | initialized but invalid +---> finalize all entities, then rcl_context_fini() +
|  |                         |                                                    |
|  +-------------------------+                                                    |
|                                                                                 |
+---------------------------------------------------------------------------------+

A declared but not defined rcl_context_t instance is considered to be "uninitialized", and passing an uninitialized context to any functions will result in undefined behavior. Some functions, like rcl_init() require the context instance to be zero initialized (all members set to "zero" state) before use.

Zero initialization of an rcl_context_t should be done with rcl_get_zero_initialized_context(), which ensures the context is in a safe state for initialization with rcl_init().

Initialization of an rcl_context_t should be done with rcl_init(), after which the context is considered both initialized and valid. After initialization it can be used in the creation of other entities like nodes and guard conditions.

At any time the context can be invalidated by calling rcl_shutdown() on the rcl_context_t, after which the context is still initialized but now invalid.

Invalidation indicates to other entities that the context was shutdown, but is still accessible for use during cleanup of themselves.

After being invalidated, and after all of the entities which used it have been finalized, the context should be finalized with rcl_context_fini().

Finalizing the context while entities which have copies of it have not yet been finalized is undefined behavior. Therefore, the context's lifetime (between calls to rcl_init() and rcl_context_fini()) should exceed the lifetime of all entities which use it directly (e.g. nodes and guard conditions) or indirectly (e.g. subscriptions and topics).

Function Documentation

◆ rcl_context_fini()

rcl_ret_t rcl_context_fini ( rcl_context_t * context )

Finalize a context.

The context to be finalized must have been previously initialized with rcl_init(), and then later invalidated with rcl_shutdown(). A zero-initialized context that has not been initialized can be finalized. If context is NULL, then RCL_RET_INVALID_ARGUMENT is returned. If context is zero-initialized, then RCL_RET_OK is returned. If context is initialized and valid (rcl_shutdown() was not called on it), then RCL_RET_INVALID_ARGUMENT is returned.

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

[1] if atomic_is_lock_free() returns true for atomic_uint_least64_t

Parameters

[in,out] context object to be finalized.

Returns: RCL_RET_OK if the shutdown was completed successfully, or; RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or; RCL_RET_ERROR if an unspecified error occur.

◆ rcl_context_get_init_options()

const rcl_init_options_t* rcl_context_get_init_options ( const rcl_context_t * context )

Return the init options used during initialization for this context.

This function can fail and return NULL if:

context is NULL
context is zero-initialized, e.g. context->impl is NULL

If context is uninitialized then that is undefined behavior.

If NULL is returned an error message will have been set.

The options are for reference only, and therefore the returned pointer is const. Changing the values in the options is undefined behavior but will likely have no effect.

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

Parameters

[in] context object from which the init options should be retrieved

Returns: pointer to the the init options, or; NULL if there was an error

◆ rcl_context_get_instance_id()

rcl_context_instance_id_t rcl_context_get_instance_id ( const rcl_context_t * context )

Returns an unsigned integer that is unique to the given context, or 0 if invalid.

The given context must be non-NULL, but does not need to be initialized or valid. If context is NULL, then 0 will be returned. If context is uninitialized, then it is undefined behavior.

The instance ID may be 0 if the context is zero-initialized or if the context has been invalidated by rcl_shutdown().

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

[1] if atomic_is_lock_free() returns true for atomic_uint_least64_t

Parameters

[in] context object from which the instance id should be retrieved

Returns: a unique id specific to this context instance, or; 0 if invalid, or; 0 if context is NULL

◆ rcl_context_get_domain_id()

rcl_ret_t rcl_context_get_domain_id	(	rcl_context_t *	context,
		size_t *	domain_id
	)

Returns the context domain id.

Precondition: If context is uninitialized, then it is undefined behavior.

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

[1] Calling the function asynchronously with rcl_init() or rcl_shutdown() can result in the function sometimes succeeding and sometimes returning RCL_RET_INVALID_ARGUMENT.

Parameters

[in]	context	from which the domain id should be retrieved.
[out]	domain_id	output variable where the domain id will be returned.

Returns: RCL_RET_INVALID_ARGUMENT if context is invalid (see rcl_context_is_valid()), or; RCL_RET_INVALID_ARGUMENT if domain_id is NULL, or; RCL_RET_OK if the domain id was correctly retrieved.

◆ rcl_context_is_valid()

bool rcl_context_is_valid ( const rcl_context_t * context )

Return true if the given context is currently valid, otherwise false.

If context is NULL, then false is returned. If context is zero-initialized, then false is returned. If context is uninitialized, then it is undefined behavior.

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

[1] if atomic_is_lock_free() returns true for atomic_uint_least64_t

Parameters

[in] context object which should be checked for validity

Returns: true if valid, otherwise false

◆ rcl_context_get_rmw_context()

rmw_context_t* rcl_context_get_rmw_context ( rcl_context_t * context )

Return pointer to the rmw context if the given context is currently valid, otherwise NULL.

If context is NULL, then NULL is returned. If context is zero-initialized, then NULL is returned. If context is uninitialized, then it is undefined behavior.

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

[1] if atomic_is_lock_free() returns true for atomic_uint_least64_t

Parameters

[in] context object from which the rmw context should be retrieved.

Returns: pointer to rmw context if valid, otherwise NULL

Classes

Typedefs

Functions

Typedef Documentation

◆ rcl_context_t

Function Documentation

◆ rcl_context_fini()

◆ rcl_context_get_init_options()

◆ rcl_context_get_instance_id()

◆ rcl_context_get_domain_id()

◆ rcl_context_is_valid()

◆ rcl_context_get_rmw_context()