Encapsulates sets of waitable items which can be waited on as a group. More...

#include <wait_set_template.hpp>

Inheritance diagram for rclcpp::WaitSetTemplate< SynchronizationPolicy, StoragePolicy >:

Collaboration diagram for rclcpp::WaitSetTemplate< SynchronizationPolicy, StoragePolicy >:

Public Member Functions
	WaitSetTemplate (const typename StoragePolicy::SubscriptionsIterable &subscriptions={}, const typename StoragePolicy::GuardConditionsIterable &guard_conditions={}, const typename StoragePolicy::TimersIterable &timers={}, const typename StoragePolicy::ClientsIterable &clients={}, const typename StoragePolicy::ServicesIterable &services={}, const typename StoragePolicy::WaitablesIterable &waitables={}, rclcpp::Context::SharedPtr context=rclcpp::contexts::get_global_default_context())
	Construct a wait set with optional initial waitable entities and optional custom context. More...

const rcl_wait_set_t &	get_rcl_wait_set () const
	Return the internal rcl wait set object. More...

void	add_subscription (std::shared_ptr< rclcpp::SubscriptionBase > subscription, rclcpp::SubscriptionWaitSetMask mask={})
	Add a subscription to this wait set. More...

void	remove_subscription (std::shared_ptr< rclcpp::SubscriptionBase > subscription, rclcpp::SubscriptionWaitSetMask mask={})
	Remove a subscription from this wait set. More...

void	add_guard_condition (std::shared_ptr< rclcpp::GuardCondition > guard_condition)
	Add a guard condition to this wait set. More...

void	remove_guard_condition (std::shared_ptr< rclcpp::GuardCondition > guard_condition)
	Remove a guard condition from this wait set. More...

void	add_timer (std::shared_ptr< rclcpp::TimerBase > timer)
	Add a timer to this wait set. More...

void	remove_timer (std::shared_ptr< rclcpp::TimerBase > timer)
	Remove a timer from this wait set. More...

void	add_client (std::shared_ptr< rclcpp::ClientBase > client)
	Add a client to this wait set. More...

void	remove_client (std::shared_ptr< rclcpp::ClientBase > client)
	Remove a client from this wait set. More...

void	add_service (std::shared_ptr< rclcpp::ServiceBase > service)
	Add a service to this wait set. More...

void	remove_service (std::shared_ptr< rclcpp::ServiceBase > service)
	Remove a service from this wait set. More...

void	add_waitable (std::shared_ptr< rclcpp::Waitable > waitable, std::shared_ptr< void > associated_entity=nullptr)
	Add a waitable to this wait set. More...

void	remove_waitable (std::shared_ptr< rclcpp::Waitable > waitable)
	Remove a waitable from this wait set. More...

void	prune_deleted_entities ()
	Remove any destroyed entities from the wait set. More...

template<class Rep = int64_t, class Period = std::milli>
RCUTILS_WARN_UNUSED WaitResult< WaitSetTemplate >	wait (std::chrono::duration< Rep, Period > time_to_wait=std::chrono::duration< Rep, Period >(-1))
	Wait for any of the entities in the wait set to be ready, or a period of time to pass. More...

Detailed Description

template<class SynchronizationPolicy, class StoragePolicy>
class rclcpp::WaitSetTemplate< SynchronizationPolicy, StoragePolicy >

Encapsulates sets of waitable items which can be waited on as a group.

This class uses the rcl_wait_set_t as storage, but it also helps manage the ownership of associated rclcpp types.

Constructor & Destructor Documentation

◆ WaitSetTemplate()

template<class SynchronizationPolicy , class StoragePolicy >

rclcpp::WaitSetTemplate< SynchronizationPolicy, StoragePolicy >::WaitSetTemplate	(	const typename StoragePolicy::SubscriptionsIterable &	subscriptions = `{}`,
		const typename StoragePolicy::GuardConditionsIterable &	guard_conditions = `{}`,
		const typename StoragePolicy::TimersIterable &	timers = `{}`,
		const typename StoragePolicy::ClientsIterable &	clients = `{}`,
		const typename StoragePolicy::ServicesIterable &	services = `{}`,
		const typename StoragePolicy::WaitablesIterable &	waitables = `{}`,
		rclcpp::Context::SharedPtr	context = `rclcpp::contexts::get_global_default_context()`
	)

inlineexplicit

Construct a wait set with optional initial waitable entities and optional custom context.

For the waitables, they have additionally an "associated" entity, which you can read more about in the add and remove functions for those types in this class.

Parameters

[in]	subscriptions	Vector of subscriptions to be added.
[in]	guard_conditions	Vector of guard conditions to be added.
[in]	timers	Vector of timers to be added.
[in]	clients	Vector of clients and their associated entity to be added.
[in]	services	Vector of services and their associated entity to be added.
[in]	waitables	Vector of waitables and their associated entity to be added.
[in]	context	Custom context to be used, defaults to global default.

Exceptions

std::invalid_argument If context is nullptr.

Member Function Documentation

◆ get_rcl_wait_set()

template<class SynchronizationPolicy , class StoragePolicy >

const rcl_wait_set_t& rclcpp::WaitSetTemplate< SynchronizationPolicy, StoragePolicy >::get_rcl_wait_set ( ) const

inline

Return the internal rcl wait set object.

This method provides no thread-safety when accessing this structure. The state of this structure can be updated at anytime by methods like wait(), add_*(), remove_*(), etc.

◆ add_subscription()

template<class SynchronizationPolicy , class StoragePolicy >

void rclcpp::WaitSetTemplate< SynchronizationPolicy, StoragePolicy >::add_subscription	(	std::shared_ptr< rclcpp::SubscriptionBase >	subscription,
		rclcpp::SubscriptionWaitSetMask	mask = `{}`
	)

inline

Add a subscription to this wait set.

See also: add_guard_condition() for details of how this method works.

Additionally to the documentation for add_guard_condition, this method has a mask parameter which allows you to control which parts of the subscription is added to the wait set with this call. For example, you might want to include the actual subscription to this wait set, but add the intra-process waitable to another wait set. If intra-process is disabled, no error will occur, it will just be skipped.

When introspecting after waiting, this subscription's shared pointer will be the Waitable's (intra-process or the QoS Events) "associated entity" pointer, for more easily figuring out which subscription which waitable goes with afterwards.

Parameters

[in]	subscription	Subscription to be added.
[in]	mask	A class which controls which parts of the subscription to add.

Exceptions

std::invalid_argument	if subscription is nullptr.
std::runtime_error	if subscription has already been added or is associated with another wait set.
exceptions	based on the policies used.

◆ remove_subscription()

template<class SynchronizationPolicy , class StoragePolicy >

void rclcpp::WaitSetTemplate< SynchronizationPolicy, StoragePolicy >::remove_subscription	(	std::shared_ptr< rclcpp::SubscriptionBase >	subscription,
		rclcpp::SubscriptionWaitSetMask	mask = `{}`
	)

inline

Remove a subscription from this wait set.

See also: remove_guard_condition() for details of how this method works.

Additionally to the documentation for add_guard_condition, this method has a mask parameter which allows you to control which parts of the subscription is added to the wait set with this call. You may remove items selectively from the wait set in a different order than they were added.

Parameters

[in]	subscription	Subscription to be removed.
[in]	mask	A class which controls which parts of the subscription to remove.

Exceptions

std::invalid_argument	if subscription is nullptr.
std::runtime_error	if subscription is not part of the wait set.
exceptions	based on the policies used.

◆ add_guard_condition()

template<class SynchronizationPolicy , class StoragePolicy >

void rclcpp::WaitSetTemplate< SynchronizationPolicy, StoragePolicy >::add_guard_condition ( std::shared_ptr< rclcpp::GuardCondition > guard_condition )

inline

Add a guard condition to this wait set.

Guard condition is added to the wait set, and shared ownership is held while waiting. However, if between calls to wait() the guard condition's reference count goes to zero, it will be implicitly removed on the next call to wait().

Except in the case of a fixed sized storage, where changes to the wait set cannot occur after construction, in which case it holds shared ownership at all times until the wait set is destroy, but this method also does not exist on a fixed sized wait set.

This function may be thread-safe depending on the SynchronizationPolicy used with this class. Using the ThreadSafeWaitSetPolicy will ensure that wait() is interrupted and returns before this function adds the guard condition. Otherwise, it is not safe to call this function concurrently with wait().

This function will not be enabled (will not be available) if the StoragePolicy does not allow editing of the wait set after initialization.

Parameters

[in] guard_condition Guard condition to be added.

Exceptions

std::invalid_argument	if guard_condition is nullptr.
std::runtime_error	if guard_condition has already been added or is associated with another wait set.
exceptions	based on the policies used.

◆ remove_guard_condition()

template<class SynchronizationPolicy , class StoragePolicy >

void rclcpp::WaitSetTemplate< SynchronizationPolicy, StoragePolicy >::remove_guard_condition ( std::shared_ptr< rclcpp::GuardCondition > guard_condition )

inline

Remove a guard condition from this wait set.

Guard condition is removed from the wait set, and if needed the shared ownership is released.

This function may be thread-safe depending on the SynchronizationPolicy used with this class. Using the ThreadSafeWaitSetPolicy will ensure that wait() is interrupted and returns before this function removes the guard condition. Otherwise, it is not safe to call this function concurrently with wait().

This function will not be enabled (will not be available) if the StoragePolicy does not allow editing of the wait set after initialization.

Parameters

[in] guard_condition Guard condition to be removed.

Exceptions

std::invalid_argument	if guard_condition is nullptr.
std::runtime_error	if guard_condition is not part of the wait set.
exceptions	based on the policies used.

◆ add_timer()

template<class SynchronizationPolicy , class StoragePolicy >

void rclcpp::WaitSetTemplate< SynchronizationPolicy, StoragePolicy >::add_timer ( std::shared_ptr< rclcpp::TimerBase > timer )

inline

Add a timer to this wait set.

See also: add_guard_condition() for details of how this method works.

Parameters

[in] timer Timer to be added.

Exceptions

std::invalid_argument	if timer is nullptr.
std::runtime_error	if timer has already been added or is associated with another wait set.
exceptions	based on the policies used.

◆ remove_timer()

template<class SynchronizationPolicy , class StoragePolicy >

void rclcpp::WaitSetTemplate< SynchronizationPolicy, StoragePolicy >::remove_timer ( std::shared_ptr< rclcpp::TimerBase > timer )

inline

Remove a timer from this wait set.

See also: remove_guard_condition() for details of how this method works.

Parameters

[in] timer Timer to be removed.

Exceptions

std::invalid_argument	if timer is nullptr.
std::runtime_error	if timer is not part of the wait set.
exceptions	based on the policies used.

◆ add_client()

template<class SynchronizationPolicy , class StoragePolicy >

void rclcpp::WaitSetTemplate< SynchronizationPolicy, StoragePolicy >::add_client ( std::shared_ptr< rclcpp::ClientBase > client )

inline

Add a client to this wait set.

See also: add_guard_condition() for details of how this method works.

Parameters

[in] client Client to be added.

Exceptions

std::invalid_argument	if client is nullptr.
std::runtime_error	if client has already been added or is associated with another wait set.
exceptions	based on the policies used.

◆ remove_client()

template<class SynchronizationPolicy , class StoragePolicy >

void rclcpp::WaitSetTemplate< SynchronizationPolicy, StoragePolicy >::remove_client ( std::shared_ptr< rclcpp::ClientBase > client )

inline

Remove a client from this wait set.

See also: remove_guard_condition() for details of how this method works.

Parameters

[in] client Client to be removed.

Exceptions

std::invalid_argument	if client is nullptr.
std::runtime_error	if client is not part of the wait set.
exceptions	based on the policies used.

◆ add_service()

template<class SynchronizationPolicy , class StoragePolicy >

void rclcpp::WaitSetTemplate< SynchronizationPolicy, StoragePolicy >::add_service ( std::shared_ptr< rclcpp::ServiceBase > service )

inline

Add a service to this wait set.

See also: add_guard_condition() for details of how this method works.

Parameters

[in] service Service to be added.

Exceptions

std::invalid_argument	if service is nullptr.
std::runtime_error	if service has already been added or is associated with another wait set.
exceptions	based on the policies used.

◆ remove_service()

template<class SynchronizationPolicy , class StoragePolicy >

void rclcpp::WaitSetTemplate< SynchronizationPolicy, StoragePolicy >::remove_service ( std::shared_ptr< rclcpp::ServiceBase > service )

inline

Remove a service from this wait set.

See also: remove_guard_condition() for details of how this method works.

Parameters

[in] service Service to be removed.

Exceptions

std::invalid_argument	if service is nullptr.
std::runtime_error	if service is not part of the wait set.
exceptions	based on the policies used.

◆ add_waitable()

template<class SynchronizationPolicy , class StoragePolicy >

void rclcpp::WaitSetTemplate< SynchronizationPolicy, StoragePolicy >::add_waitable	(	std::shared_ptr< rclcpp::Waitable >	waitable,
		std::shared_ptr< void >	associated_entity = `nullptr`
	)

inline

Add a waitable to this wait set.

See also: add_guard_condition() for details of how this method works.

Additionally, this function has an optional parameter which can be used to more quickly associate this waitable with an entity when it is ready, and so that the ownership maybe held in order to keep the waitable's parent in scope while waiting. If it is set to nullptr it will be ignored. The destruction of the associated entity's shared pointer will not cause the waitable to be removed, but it will cause the associated entity pointer to be nullptr when introspecting this waitable after waiting.

Note that rclcpp::QOSEventHandlerBase are just a special case of rclcpp::Waitable and can be added with this function.

Parameters

[in]	waitable	Waitable to be added.
[in]	associated_entity	Type erased shared pointer associated with the waitable. This may be nullptr.

Exceptions

std::invalid_argument	if waitable is nullptr.
std::runtime_error	if waitable has already been added or is associated with another wait set.
exceptions	based on the policies used.

◆ remove_waitable()

template<class SynchronizationPolicy , class StoragePolicy >

void rclcpp::WaitSetTemplate< SynchronizationPolicy, StoragePolicy >::remove_waitable ( std::shared_ptr< rclcpp::Waitable > waitable )

inline

Remove a waitable from this wait set.

See also: remove_guard_condition() for details of how this method works.

Parameters

[in] waitable Waitable to be removed.

Exceptions

std::invalid_argument	if waitable is nullptr.
std::runtime_error	if waitable is not part of the wait set.
exceptions	based on the policies used.

◆ prune_deleted_entities()

template<class SynchronizationPolicy , class StoragePolicy >

void rclcpp::WaitSetTemplate< SynchronizationPolicy, StoragePolicy >::prune_deleted_entities ( )

inline

Remove any destroyed entities from the wait set.

When the storage policy does not maintain shared ownership for the life of the wait set, e.g. the DynamicStorage policy, it is possible for an entity to go out of scope and be deleted without this wait set noticing. Therefore there are weak references in this wait set which need to be periodically cleared. This function performs that clean up.

Since this involves removing entities from the wait set, and is only needed if the wait set does not keep ownership of the added entities, the storage policies which are static will not need this function and therefore do not provide this function.

Exceptions

exceptions based on the policies used.

◆ wait()

template<class SynchronizationPolicy , class StoragePolicy >

template<class Rep = int64_t, class Period = std::milli>

RCUTILS_WARN_UNUSED WaitResult<WaitSetTemplate> rclcpp::WaitSetTemplate< SynchronizationPolicy, StoragePolicy >::wait ( std::chrono::duration< Rep, Period > time_to_wait = std::chrono::duration<Rep, Period>(-1) )

inline

Wait for any of the entities in the wait set to be ready, or a period of time to pass.

This function will return when either one of the entities within this wait set is ready, or a period of time has passed, which ever is first. The term "ready" means different things for different entities, but generally it means some condition is met asynchronously for which this function waits.

This function can either wait for a period of time, do no waiting (non-blocking), or wait indefinitely, all based on the value of the time_to_wait parameter. Waiting is always measured against the std::chrono::steady_clock. If waiting indefinitely, the Timeout result is not possible. There is no "cancel wait" function on this class, but if you want to wait indefinitely but have a way to asynchronously interrupt this method, then you can use a dedicated rclcpp::GuardCondition for that purpose.

This function will modify the internal rcl_wait_set_t, so introspecting the wait set during a call to wait is never safe. You should always wait, then introspect, and then, only when done introspecting, wait again.

It may be thread-safe to add and remove entities to the wait set concurrently with this function, depending on the SynchronizationPolicy that is used. With the rclcpp::wait_set_policies::ThreadSafeSynchronization policy this function will stop waiting to allow add or remove of an entity, and then resume waiting, so long as the timeout has not been reached.

Parameters

[in] time_to_wait If > 0, time to wait for entities to be ready, if == 0, check if anything is ready without blocking, or if < 0, wait indefinitely until one of the items is ready. Default is -1, so wait indefinitely.

Returns: Ready when one of the entities is ready, or; Timeout when the given time to wait is exceeded, not possible when time_to_wait is < 0, or; Empty if the wait set is empty, avoiding the possibility of waiting indefinitely on an empty wait set.

Exceptions

rclcpp::exceptions::RCLError	on unhandled rcl errors or,
std::runtime_error	if unknown WaitResultKind

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

include/rclcpp/wait_set_template.hpp

Public Member Functions

Detailed Description

template<class SynchronizationPolicy, class StoragePolicy> class rclcpp::WaitSetTemplate< SynchronizationPolicy, StoragePolicy >

Constructor & Destructor Documentation

◆ WaitSetTemplate()

Member Function Documentation

◆ get_rcl_wait_set()

◆ add_subscription()

◆ remove_subscription()

◆ add_guard_condition()

◆ remove_guard_condition()

◆ add_timer()

◆ remove_timer()

◆ add_client()

◆ remove_client()

◆ add_service()

◆ remove_service()

◆ add_waitable()

◆ remove_waitable()

◆ prune_deleted_entities()

◆ wait()

template<class SynchronizationPolicy, class StoragePolicy>
class rclcpp::WaitSetTemplate< SynchronizationPolicy, StoragePolicy >