rclcpp::Context Class Reference

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

#include <context.hpp>

Inheritance diagram for rclcpp::Context:

Collaboration diagram for rclcpp::Context:

Public Types
using	OnShutdownCallback = OnShutdownCallbackHandle::OnShutdownCallbackType

Public Member Functions
	Context ()
	Default constructor, after which the Context is still not "initialized". More...
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. More...
bool	is_valid () const
	Return true if the context is valid, otherwise false. More...
const rclcpp::InitOptions &	get_init_options () const
	Return the init options used during init. More...
rclcpp::InitOptions	get_init_options ()
	Return a copy of the init options used during init. More...
size_t	get_domain_id () const
	Return actual domain id. More...
std::string	shutdown_reason () const
	Return the shutdown reason, or empty string if not shutdown. More...
virtual bool	shutdown (const std::string &reason)
	Shutdown the context, making it uninitialized and therefore invalid for derived entities. More...
virtual OnShutdownCallback	on_shutdown (OnShutdownCallback callback)
	Add a on_shutdown callback to be called when shutdown is called for this context. More...
virtual OnShutdownCallbackHandle	add_on_shutdown_callback (OnShutdownCallback callback)
	Add a on_shutdown callback to be called when shutdown is called for this context. More...
virtual bool	remove_on_shutdown_callback (const OnShutdownCallbackHandle &callback_handle)
	Remove an registered on_shutdown callbacks. More...
std::vector< OnShutdownCallback >	get_on_shutdown_callbacks () const
	Return the shutdown callbacks. More...
std::shared_ptr< rcl_context_t >	get_rcl_context ()
	Return the internal rcl context. More...
bool	sleep_for (const std::chrono::nanoseconds &nanoseconds)
	Sleep for a given period of time or until shutdown() is called. More...
virtual void	interrupt_all_sleep_for ()
	Interrupt any blocking sleep_for calls, causing them to return immediately and return true. More...
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. More...
Public Member Functions inherited from std::enable_shared_from_this< Context >
T	enable_shared_from_this (T... args)
T	operator= (T... args)
T	shared_from_this (T... args)
T	~enable_shared_from_this (T... args)

Protected Member Functions
virtual 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. It is often used in conjunction with rclcpp::init, or rclcpp::init_local, and rclcpp::shutdown.

Member Typedef Documentation

OnShutdownCallback

using rclcpp::Context::OnShutdownCallback = OnShutdownCallbackHandle::OnShutdownCallbackType

Constructor & Destructor Documentation

Context()

rclcpp::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_sigint option in the InitOptions class.

~Context()

virtual rclcpp::Context::~Context ( )

virtual

Member Function Documentation

init()

virtual void rclcpp::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_handers() or use rclcpp::init(). In addition to installing the signal handlers, the shutdown_on_sigint 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

is_valid()

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

get_init_options() [1/2]

const rclcpp::InitOptions& rclcpp::Context::get_init_options

(

)

const

Return the init options used during init.

get_init_options() [2/2]

rclcpp::InitOptions rclcpp::Context::get_init_options

(

)

Return a copy of the init options used during init.

get_domain_id()

size_t rclcpp::Context::get_domain_id

(

)

const

Return actual domain id.

shutdown_reason()

std::string rclcpp::Context::shutdown_reason

(

)

const

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

This function is thread-safe.

shutdown()

virtual bool rclcpp::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.

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

on_shutdown()

virtual OnShutdownCallback rclcpp::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 asynchronoulsy 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

add_on_shutdown_callback()

virtual OnShutdownCallbackHandle rclcpp::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 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 created callback handle

remove_on_shutdown_callback()

virtual bool rclcpp::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.

get_on_shutdown_callbacks()

std::vector<OnShutdownCallback> rclcpp::Context::get_on_shutdown_callbacks

(

)

const

Return the shutdown callbacks.

Returned callbacks are a copy of the registered callbacks.

get_rcl_context()

std::shared_ptr<rcl_context_t> rclcpp::Context::get_rcl_context

(

)

Return the internal rcl context.

sleep_for()

bool rclcpp::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_sigint=true and SIGINT 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.

interrupt_all_sleep_for()

virtual void rclcpp::Context::interrupt_all_sleep_for ( )

virtual

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

get_sub_context()

template<typename SubContext , typename ... Args>

std::shared_ptr<SubContext> rclcpp::Context::get_sub_context ( Args &&...  args )

inline

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

clean_up()

virtual void rclcpp::Context::clean_up ( )

protectedvirtual

---

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

• include/rclcpp/context.hpp