Class Context

• Defined in File context.hpp

Inheritance Relationships

Base Type

• public std::enable_shared_from_this< Context >

Derived Type

• public rclcpp::contexts::DefaultContext (Class DefaultContext)

Class Documentation

class Context : public std::enable_shared_from_this<Context>

Context which encapsulates shared state between nodes and other similar entities.

A context also represents the lifecycle between init and shutdown of rclcpp. It is often used in conjunction with rclcpp::init, or rclcpp::init_local, and rclcpp::shutdown.

Subclassed by rclcpp::contexts::DefaultContext

Public Types

using OnShutdownCallback = OnShutdownCallbackHandle::ShutdownCallbackType

using PreShutdownCallback = PreShutdownCallbackHandle::ShutdownCallbackType

Public Functions

Context()

Default constructor, after which the Context is still not “initialized”.

Every context which is constructed is added to a global vector of contexts, which is used by the signal handler to conditionally shutdown each context on SIGINT. See the shutdown_on_signal option in the InitOptions class.

virtual ~Context()

virtual void init(int argc, char const *const *argv, const rclcpp::InitOptions &init_options = rclcpp::InitOptions())

Initialize the context, and the underlying elements like the rcl context.

This method must be called before passing this context to things like the constructor of Node. It must also be called before trying to shutdown the context.

Note that this function does not setup any signal handlers, so if you want it to be shutdown by the signal handler, then you need to either install them manually with rclcpp::install_signal_handlers() or use rclcpp::init(). In addition to installing the signal handlers, the shutdown_on_signal of the InitOptions needs to be true for this context to be shutdown by the signal handler, otherwise it will be passed over.

After calling this method, shutdown() can be called to invalidate the context for derived entities, e.g. nodes, guard conditions, etc. However, the underlying rcl context is not finalized until this Context’s destructor is called or this function is called again. Allowing this class to go out of scope and get destructed or calling this function a second time while derived entities are still using the context is undefined behavior and should be avoided. It’s a good idea to not reuse context objects and instead create a new one each time you need to shutdown and init again. This allows derived entities to hold on to shard pointers to the first context object until they are done.

This function is thread-safe.

Parameters:

• argc – [in] number of arguments

• argv – [in] argument array which may contain arguments intended for ROS

• init_options – [in] initialization options for rclcpp and underlying layers

Throws:

• ContextAlreadyInitialized – if called if init is called more than once

• anything – rclcpp::exceptions::throw_from_rcl_error can throw.

• std::runtime_error – if the global logging configure mutex is NULL

• exceptions::UnknownROSArgsError – if there are unknown ROS arguments

bool is_valid() const

Return true if the context is valid, otherwise false.

The context is valid if it has been initialized but not shutdown.

This function is thread-safe. This function is lock free so long as pointers and uint64_t atomics are lock free.

Returns:

true if valid, otherwise false

const rclcpp::InitOptions &get_init_options() const

Return the init options used during init.

rclcpp::InitOptions get_init_options()

Return a copy of the init options used during init.

size_t get_domain_id() const

Return actual domain id.

std::string shutdown_reason() const

Return the shutdown reason, or empty string if not shutdown.

This function is thread-safe.

virtual bool shutdown(const std::string &reason)

Shutdown the context, making it uninitialized and therefore invalid for derived entities.

Several things happen when the context is shutdown, in this order:

• acquires a lock to prevent race conditions with init, on_shutdown, etc.

• if the context is not initialized, return false

• rcl_shutdown() is called on the internal rcl_context_t instance

• the shutdown reason is set

• each on_shutdown callback is called, in the order that they were added

• interrupt blocking sleep_for() calls, so they return early due to shutdown

• interrupt blocking executors and wait sets

The underlying rcl context is not finalized by this function.

This function is thread-safe.

Parameters:

reason – [in] the description of why shutdown happened

Throws:

various – exceptions derived from rclcpp::exceptions::RCLError, if rcl_shutdown fails

Returns:

true if shutdown was successful, false if context was already shutdown

virtual OnShutdownCallback on_shutdown(OnShutdownCallback callback)

Add a on_shutdown callback to be called when shutdown is called for this context.

These callbacks will be called in the order they are added as the second to last step in shutdown().

When shutdown occurs due to the signal handler, these callbacks are run asynchronously in the dedicated singal handling thread.

Also, shutdown() may be called from the destructor of this function. Therefore, it is not safe to throw exceptions from these callbacks. Instead, log errors or use some other mechanism to indicate an error has occurred.

On shutdown callbacks may be registered before init and after shutdown, and persist on repeated init’s.

Parameters:

callback – [in] the on shutdown callback to be registered

Returns:

the callback passed, for convenience when storing a passed lambda

virtual OnShutdownCallbackHandle add_on_shutdown_callback(OnShutdownCallback callback)

Add a on_shutdown callback to be called when shutdown is called for this context.

These callbacks will be called in the order they are added as the second to last step in shutdown().

When shutdown occurs due to the signal handler, these callbacks are run asynchronously in the dedicated signal handling thread.

Also, shutdown() may be called from the destructor of this function. Therefore, it is not safe to throw exceptions from these callbacks. Instead, log errors or use some other mechanism to indicate an error has occurred.

On shutdown callbacks may be registered before init and after shutdown, and persist on repeated init’s.

Parameters:

callback – [in] the on_shutdown callback to be registered

Returns:

the created callback handle

virtual bool remove_on_shutdown_callback(const OnShutdownCallbackHandle &callback_handle)

Remove an registered on_shutdown callbacks.

Parameters:

callback_handle – [in] the on_shutdown callback handle to be removed.

Returns:

true if the callback is found and removed, otherwise false.

virtual PreShutdownCallbackHandle add_pre_shutdown_callback(PreShutdownCallback callback)

Add a pre_shutdown callback to be called before shutdown is called for this context.

These callbacks will be called in the order they are added.

When shutdown occurs due to the signal handler, these callbacks are run asynchronously in the dedicated signal handling thread.

Parameters:

callback – [in] the pre_shutdown callback to be registered

Returns:

the created callback handle

virtual bool remove_pre_shutdown_callback(const PreShutdownCallbackHandle &callback_handle)

Remove an registered pre_shutdown callback.

Parameters:

callback_handle – [in] the pre_shutdown callback handle to be removed.

Returns:

true if the callback is found and removed, otherwise false.

std::vector<OnShutdownCallback> get_on_shutdown_callbacks() const

Return the shutdown callbacks.

Returned callbacks are a copy of the registered callbacks.

std::vector<PreShutdownCallback> get_pre_shutdown_callbacks() const

Return the pre-shutdown callbacks.

Returned callbacks are a copy of the registered callbacks.

std::shared_ptr<rcl_context_t> get_rcl_context()

Return the internal rcl context.

bool sleep_for(const std::chrono::nanoseconds &nanoseconds)

Sleep for a given period of time or until shutdown() is called.

This function can be interrupted early if:

• this context is shutdown()

• this context is destructed (resulting in shutdown)

• this context has shutdown_on_signal=true and SIGINT/SIGTERM occurs (resulting in shutdown)

• interrupt_all_sleep_for() is called

Parameters:

nanoseconds – [in] A std::chrono::duration representing how long to sleep for.

Returns:

true if the condition variable did not timeout, i.e. you were interrupted.

virtual void interrupt_all_sleep_for()

Interrupt any blocking sleep_for calls, causing them to return immediately and return true.

template<typename SubContext, typename ...Args>
inline std::shared_ptr<SubContext> get_sub_context(Args&&... args)

Return a singleton instance for the SubContext type, constructing one if necessary.

Protected Functions

virtual void clean_up()