rcl  master
C API providing common ROS client library functionality.
Classes | Typedefs | Functions
context.h File Reference
#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_trcl_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_trcl_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]contextobject 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]contextobject 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]contextobject 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]contextfrom which the domain id should be retrieved.
[out]domain_idoutput 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]contextobject 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]contextobject from which the rmw context should be retrieved.
Returns
pointer to rmw context if valid, otherwise NULL
rcl_get_zero_initialized_context
rcl_context_t rcl_get_zero_initialized_context(void)
Return a zero initialization context object.
rcl_context_fini
rcl_ret_t rcl_context_fini(rcl_context_t *context)
Finalize a context.
rcl_init
rcl_ret_t rcl_init(int argc, char const *const *argv, const rcl_init_options_t *options, rcl_context_t *context)
Initialization of rcl.
rcl_shutdown
rcl_ret_t rcl_shutdown(rcl_context_t *context)
Shutdown a given rcl context.