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

#include <rclcpp/context.hpp>

Inheritance diagram for rclcpp::Context:

Collaboration diagram for rclcpp::Context:

Public Types
using	OnShutdownCallback = OnShutdownCallbackHandle::ShutdownCallbackType

using	PreShutdownCallback = PreShutdownCallbackHandle::ShutdownCallbackType

Public Member Functions
RCLCPP_PUBLIC	Context ()
	Default constructor, after which the Context is still not "initialized". More...

virtual RCLCPP_PUBLIC 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. More...

RCLCPP_PUBLIC bool	is_valid () const
	Return true if the context is valid, otherwise false. More...

RCLCPP_PUBLIC const rclcpp::InitOptions &	get_init_options () const
	Return the init options used during init.

RCLCPP_PUBLIC rclcpp::InitOptions	get_init_options ()
	Return a copy of the init options used during init.

RCLCPP_PUBLIC size_t	get_domain_id () const
	Return actual domain id.

RCLCPP_PUBLIC std::string	shutdown_reason () const
	Return the shutdown reason, or empty string if not shutdown. More...

virtual RCLCPP_PUBLIC bool	shutdown (const std::string &reason)
	Shutdown the context, making it uninitialized and therefore invalid for derived entities. More...

virtual RCLCPP_PUBLIC OnShutdownCallback	on_shutdown (OnShutdownCallback callback)
	Add a on_shutdown callback to be called when shutdown is called for this context. More...

virtual RCLCPP_PUBLIC OnShutdownCallbackHandle	add_on_shutdown_callback (OnShutdownCallback callback)
	Add a on_shutdown callback to be called when shutdown is called for this context. More...

virtual RCLCPP_PUBLIC bool	remove_on_shutdown_callback (const OnShutdownCallbackHandle &callback_handle)
	Remove an registered on_shutdown callbacks. More...

virtual RCLCPP_PUBLIC PreShutdownCallbackHandle	add_pre_shutdown_callback (PreShutdownCallback callback)
	Add a pre_shutdown callback to be called before shutdown is called for this context. More...

virtual RCLCPP_PUBLIC bool	remove_pre_shutdown_callback (const PreShutdownCallbackHandle &callback_handle)
	Remove an registered pre_shutdown callback. More...

RCLCPP_PUBLIC std::vector< OnShutdownCallback >	get_on_shutdown_callbacks () const
	Return the shutdown callbacks. More...

RCLCPP_PUBLIC std::vector< PreShutdownCallback >	get_pre_shutdown_callbacks () const
	Return the pre-shutdown callbacks. More...

RCLCPP_PUBLIC std::shared_ptr< rcl_context_t >	get_rcl_context ()
	Return the internal rcl context.

RCLCPP_PUBLIC bool	sleep_for (const std::chrono::nanoseconds &nanoseconds)
	Sleep for a given period of time or until shutdown() is called. More...

RCLCPP_PUBLIC void	interrupt_all_sleep_for ()
	Interrupt any blocking sleep_for calls, causing them to return immediately and return true.

template<typename SubContext , typename ... Args>
std::shared_ptr< SubContext >	get_sub_context (Args &&... args)
	Return a singleton instance for the SubContext type, constructing one if necessary.

template<Context::ShutdownType shutdown_type>
rclcpp::ShutdownCallbackHandle	add_shutdown_callback (ShutdownCallback callback)

template<Context::ShutdownType shutdown_type>
bool	remove_shutdown_callback (const ShutdownCallbackHandle &callback_handle)

template<Context::ShutdownType shutdown_type>
std::vector< rclcpp::Context::ShutdownCallback >	get_shutdown_callback () const

Protected Member Functions
RCLCPP_PUBLIC void	clean_up ()

Detailed Description

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

A context also represents the lifecycle between init and shutdown of rclcpp. Nodes may be attached to a particular context by passing to the rclcpp::Node constructor a rclcpp::NodeOptions instance in which the Context is set via rclcpp::NodeOptions::context. Nodes will be automatically removed from the context when destructed. Contexts may be shutdown by calling rclcpp::shutdown.

Definition at line 75 of file context.hpp.

Constructor & Destructor Documentation

◆ Context()

Context::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.

Definition at line 145 of file context.cpp.

Member Function Documentation

◆ add_on_shutdown_callback()

rclcpp::OnShutdownCallbackHandle Context::add_on_shutdown_callback ( OnShutdownCallback callback )

virtual

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

[in] callback the on_shutdown callback to be registered

Returns: the created callback handle

Definition at line 379 of file context.cpp.

Referenced by on_shutdown().

Here is the caller graph for this function:

◆ add_pre_shutdown_callback()

rclcpp::PreShutdownCallbackHandle Context::add_pre_shutdown_callback ( PreShutdownCallback callback )

virtual

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

[in] callback the pre_shutdown callback to be registered

Returns: the created callback handle

Definition at line 391 of file context.cpp.

◆ get_on_shutdown_callbacks()

std::vector< rclcpp::Context::OnShutdownCallback > Context::get_on_shutdown_callbacks ( ) const

Return the shutdown callbacks.

Returned callbacks are a copy of the registered callbacks.

Definition at line 463 of file context.cpp.

◆ get_pre_shutdown_callbacks()

std::vector< rclcpp::Context::PreShutdownCallback > Context::get_pre_shutdown_callbacks ( ) const

Return the pre-shutdown callbacks.

Returned callbacks are a copy of the registered callbacks.

Definition at line 469 of file context.cpp.

◆ init()

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

virtual

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

[in]	argc	number of arguments
[in]	argv	argument array which may contain arguments intended for ROS
[in]	init_options	initialization options for rclcpp and underlying layers

Exceptions

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

Definition at line 193 of file context.cpp.

References rclcpp::InitOptions::auto_initialize_logging(), rclcpp::get_logger(), rclcpp::InitOptions::get_rcl_init_options(), is_valid(), rcl_get_default_allocator, rcl_get_zero_initialized_context(), rcl_init(), rcl_init_options_get_allocator(), rcl_logging_configure_with_output_handler(), RCL_RET_OK, and rcl_shutdown().

Here is the call graph for this function:

◆ is_valid()

bool Context::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

Definition at line 260 of file context.cpp.

References rcl_context_is_valid().

Referenced by init(), shutdown(), and sleep_for().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ on_shutdown()

rclcpp::Context::OnShutdownCallback Context::on_shutdown ( OnShutdownCallback callback )

virtual

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

[in] callback the on shutdown callback to be registered

Returns: the callback passed, for convenience when storing a passed lambda

Definition at line 372 of file context.cpp.

References add_on_shutdown_callback().

Here is the call graph for this function:

◆ remove_on_shutdown_callback()

bool Context::remove_on_shutdown_callback ( const OnShutdownCallbackHandle & callback_handle )

virtual

Remove an registered on_shutdown callbacks.

Parameters

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

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

Definition at line 385 of file context.cpp.

◆ remove_pre_shutdown_callback()

bool Context::remove_pre_shutdown_callback ( const PreShutdownCallbackHandle & callback_handle )

virtual

Remove an registered pre_shutdown callback.

Parameters

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

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

Definition at line 397 of file context.cpp.

◆ shutdown()

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

virtual

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.

Note that if you override this method, but leave shutdown to be called in the destruction of this base class, it will not call the overridden version from your base class. So you need to ensure you call your class's shutdown() in its destructor.

Parameters

[in] reason the description of why shutdown happened

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

Exceptions

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

Definition at line 301 of file context.cpp.

References interrupt_all_sleep_for(), is_valid(), rcl_logging_fini(), RCL_RET_OK, and rcl_shutdown().

Here is the call graph for this function:

◆ shutdown_reason()

std::string Context::shutdown_reason ( ) const

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

This function is thread-safe.

Definition at line 294 of file context.cpp.

◆ sleep_for()

bool Context::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

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

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

Definition at line 504 of file context.cpp.

References is_valid().

Here is the call graph for this function:

The documentation for this class was generated from the following files:

rclcpp/include/rclcpp/context.hpp
rclcpp/src/rclcpp/context.cpp

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Context()

Member Function Documentation

◆ add_on_shutdown_callback()

◆ add_pre_shutdown_callback()

◆ get_on_shutdown_callbacks()

◆ get_pre_shutdown_callbacks()

◆ init()

◆ is_valid()

◆ on_shutdown()

◆ remove_on_shutdown_callback()

◆ remove_pre_shutdown_callback()

◆ shutdown()

◆ shutdown_reason()

◆ sleep_for()