rclcpp  master
C++ ROS Client Library API
Public Member Functions | List of all members
rclcpp::WaitSetTemplate< SynchronizationPolicy, StoragePolicy > Class Template Referencefinal

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 >:
Inheritance graph
[legend]
Collaboration diagram for rclcpp::WaitSetTemplate< SynchronizationPolicy, StoragePolicy >:
Collaboration graph
[legend]

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_tget_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< WaitSetTemplatewait (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]subscriptionsVector of subscriptions to be added.
[in]guard_conditionsVector of guard conditions to be added.
[in]timersVector of timers to be added.
[in]clientsVector of clients and their associated entity to be added.
[in]servicesVector of services and their associated entity to be added.
[in]waitablesVector of waitables and their associated entity to be added.
[in]contextCustom context to be used, defaults to global default.
Exceptions
std::invalid_argumentIf 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]subscriptionSubscription to be added.
[in]maskA class which controls which parts of the subscription to add.
Exceptions
std::invalid_argumentif subscription is nullptr.
std::runtime_errorif subscription has already been added or is associated with another wait set.
exceptionsbased 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]subscriptionSubscription to be removed.
[in]maskA class which controls which parts of the subscription to remove.
Exceptions
std::invalid_argumentif subscription is nullptr.
std::runtime_errorif subscription is not part of the wait set.
exceptionsbased 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_conditionGuard condition to be added.
Exceptions
std::invalid_argumentif guard_condition is nullptr.
std::runtime_errorif guard_condition has already been added or is associated with another wait set.
exceptionsbased 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_conditionGuard condition to be removed.
Exceptions
std::invalid_argumentif guard_condition is nullptr.
std::runtime_errorif guard_condition is not part of the wait set.
exceptionsbased 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]timerTimer to be added.
Exceptions
std::invalid_argumentif timer is nullptr.
std::runtime_errorif timer has already been added or is associated with another wait set.
exceptionsbased 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]timerTimer to be removed.
Exceptions
std::invalid_argumentif timer is nullptr.
std::runtime_errorif timer is not part of the wait set.
exceptionsbased 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]clientClient to be added.
Exceptions
std::invalid_argumentif client is nullptr.
std::runtime_errorif client has already been added or is associated with another wait set.
exceptionsbased 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]clientClient to be removed.
Exceptions
std::invalid_argumentif client is nullptr.
std::runtime_errorif client is not part of the wait set.
exceptionsbased 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]serviceService to be added.
Exceptions
std::invalid_argumentif service is nullptr.
std::runtime_errorif service has already been added or is associated with another wait set.
exceptionsbased 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]serviceService to be removed.
Exceptions
std::invalid_argumentif service is nullptr.
std::runtime_errorif service is not part of the wait set.
exceptionsbased 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]waitableWaitable to be added.
[in]associated_entityType erased shared pointer associated with the waitable. This may be nullptr.
Exceptions
std::invalid_argumentif waitable is nullptr.
std::runtime_errorif waitable has already been added or is associated with another wait set.
exceptionsbased 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]waitableWaitable to be removed.
Exceptions
std::invalid_argumentif waitable is nullptr.
std::runtime_errorif waitable is not part of the wait set.
exceptionsbased 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
exceptionsbased 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_waitIf > 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::RCLErroron unhandled rcl errors or,
std::runtime_errorif unknown WaitResultKind

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