rcl  master
C API providing common ROS client library functionality.
Functions
init.h File Reference
#include "rcl/allocator.h"
#include "rcl/context.h"
#include "rcl/init_options.h"
#include "rcl/macros.h"
#include "rcl/types.h"
#include "rcl/visibility_control.h"
Include dependency graph for init.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions

rcl_ret_t rcl_init (int argc, char const *const *argv, const rcl_init_options_t *options, rcl_context_t *context)
 Initialization of rcl. More...
 
rcl_ret_t rcl_shutdown (rcl_context_t *context)
 Shutdown a given rcl context. More...
 

Function Documentation

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

This function can be run any number of times, so long as the given context has been properly prepared.

The given rcl_context_t must be zero initialized with the function rcl_get_zero_initialized_context() and must not be already initialized by this function. If the context is already initialized this function will fail and return the RCL_RET_ALREADY_INIT error code. A context may be initialized again after it has been finalized with the rcl_shutdown() function and zero initialized again with rcl_get_zero_initialized_context().

The argc and argv parameters may contain command line arguments for the program. rcl specific arguments will be parsed, but not removed. If argc is 0 and argv is NULL no parameters will be parsed.

The options argument must be non-NULL and must have been initialized with rcl_init_options_init(). It is unmodified by this function, and the ownership is not transfered to the context, but instead a copy is made into the context for later reference. Therefore, the given options need to be cleaned up with rcl_init_options_fini() after this function returns.


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]argcnumber of strings in argv
[in]argvcommand line arguments; rcl specific arguments are removed
[in]optionsoptions used during initialization
[out]contextresulting context object that represents this init
Returns
RCL_RET_OK if initialization is successful, or
RCL_RET_ALREADY_INIT if rcl_init has already been called, 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_shutdown()

rcl_ret_t rcl_shutdown ( rcl_context_t context)

Shutdown a given rcl context.

The given context must have been initialized with rcl_init(). If not, this function will fail with RCL_RET_ALREADY_SHUTDOWN.

When this function is called:

  • Any rcl objects created using this context are invalidated.
  • Functions called on invalid objects may or may not fail.
  • Calls to rcl_context_is_initialized() will return false.

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

[1] if atomic_is_lock_free() returns true for atomic_uint_least64_t

Returns
RCL_RET_OK if the shutdown was completed successfully, or
RCL_RET_INVALID_ARGUMENT if any arguments are invalid, or
RCL_RET_ALREADY_SHUTDOWN if the context is not currently valid, or
RCL_RET_ERROR if an unspecified error occur.