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]	argc	number of strings in argv
[in]	argv	command line arguments; rcl specific arguments are removed
[in]	allocator	rcl_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