rclcpp
master
C++ ROS Client Library API
|
Encapsulates sets of waitable items which can be waited on as a group. More...
#include <wait_set_template.hpp>
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... | |
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.
|
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.
[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. |
std::invalid_argument | If context is nullptr. |
|
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.
|
inline |
Add a subscription to this wait set.
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.
[in] | subscription | Subscription to be added. |
[in] | mask | A class which controls which parts of the subscription to add. |
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. |
|
inline |
Remove a subscription from this wait set.
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.
[in] | subscription | Subscription to be removed. |
[in] | mask | A class which controls which parts of the subscription to remove. |
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. |
|
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.
[in] | guard_condition | Guard condition to be added. |
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. |
|
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.
[in] | guard_condition | Guard condition to be removed. |
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. |
|
inline |
Add a timer to this wait set.
[in] | timer | Timer to be added. |
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. |
|
inline |
Remove a timer from this wait set.
[in] | timer | Timer to be removed. |
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. |
|
inline |
Add a client to this wait set.
[in] | client | Client to be added. |
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. |
|
inline |
Remove a client from this wait set.
[in] | client | Client to be removed. |
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. |
|
inline |
Add a service to this wait set.
[in] | service | Service to be added. |
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. |
|
inline |
Remove a service from this wait set.
[in] | service | Service to be removed. |
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. |
|
inline |
Add a waitable to this wait set.
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.
[in] | waitable | Waitable to be added. |
[in] | associated_entity | Type erased shared pointer associated with the waitable. This may be nullptr. |
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. |
|
inline |
Remove a waitable from this wait set.
[in] | waitable | Waitable to be removed. |
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. |
|
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 | based on the policies used. |
|
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.
[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. |
rclcpp::exceptions::RCLError | on unhandled rcl errors or, |
std::runtime_error | if unknown WaitResultKind |