rcl  master
C API providing common ROS client library functionality.
Functions
rcl.h File Reference
#include "rcl/macros.h"
#include "rcl/node.h"
#include "rcl/publisher.h"
#include "rcl/subscription.h"
#include "rcl/types.h"
#include "rcl/wait.h"
#include "rcl/visibility_control.h"

Go to the source code of this file.

Functions

rcl_ret_t rcl_init (int argc, char **argv, rcl_allocator_t allocator)
 Global initialization of rcl. More...
 
rcl_ret_t rcl_shutdown (void)
 Signal global shutdown of rcl. More...
 
uint64_t rcl_get_instance_id (void)
 Returns an uint64_t number that is unique for the latest rcl_init call. More...
 
bool rcl_ok (void)
 Return true if rcl is currently initialized, otherwise false. More...
 

Function Documentation

◆ rcl_init()

rcl_ret_t rcl_init ( int  argc,
char **  argv,
rcl_allocator_t  allocator 
)

Global initialization of rcl.

Unless otherwise noted, this must be called before using any rcl functions.

This function can only be run once after starting the program, and once after each call to rcl_shutdown(). Repeated calls will fail with RCL_RET_ALREADY_INIT.

This function can be called any time after rcl_shutdown() is called, but it cannot be called from within a callback being executed by an rcl executor. For example, you can call rcl_shutdown() from within a timer callback, but you have to return from the callback, and therefore exit any in-progress call to a spin function, before calling rcl_init() again.

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


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]allocatorrcl_allocator_t used in rcl_init() and rcl_shutdown()
Returns
RCL_RET_OK if initialization is successful, or
RCL_RET_ALREADY_INIT if rcl_init has already been called, 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 ( void  )

Signal global shutdown of rcl.

This function does not have to be called on exit, but does have to be called making a repeat call to rcl_init().

This function can only be called once after each call to rcl_init(). Repeated calls will fail with RCL_RET_NOT_INIT. This function is not thread safe.

When this function is called:

  • Any rcl objects created since the last call to rcl_init() are invalidated.
  • Calls to rcl_ok() will return false.
  • Any executors waiting for work (within a call to spin) are interrupted.
  • No new work (executing callbacks) will be done in executors.
  • Currently running work in executors will be finished.

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

[1] not thread-safe with rcl_init() [2] 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_NOT_INIT if rcl is not currently initialized, or
RCL_RET_ERROR if an unspecified error occur.

◆ rcl_get_instance_id()

uint64_t rcl_get_instance_id ( void  )

Returns an uint64_t number that is unique for the latest rcl_init call.

If called before rcl_init or after rcl_shutdown then 0 will be returned.


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

Returns
a unique id specific to this rcl instance, or 0 if not initialized.

◆ rcl_ok()

bool rcl_ok ( void  )

Return true if rcl is currently initialized, otherwise false.

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