# WaitSet
## Thread Safety
The WaitSet is **not** thread-safe!
- It is **not** allowed to attach or detach _Triggerable_
classes with `attachEvent` or `detachEvent` when another thread is currently
waiting for notifications with `wait` or `timedWait`.
- Do **not** call any of the WaitSet methods concurrently.
The _TriggerHandle_ on the other hand, is thread-safe! Therefore you are allowed to
attach/detach a _TriggerHandle_ to a _Triggerable_ while another thread may
trigger the _TriggerHandle_.
## Introduction
The WaitSet is a set to which you can attach objects so that they can signal a wide variety
of events to one single notifiable. The typical approach is that one creates a
WaitSet, attaches multiple subscribers, user triggers or other _Triggerables_ to it and
then wait until one or many of the attached entities signal an event. If that happens one receives
a list of _NotificationInfos_ which is corresponding to all occurred events.
## Events and States
In this context, we define the state of an object as a specified set of values
to which the members of that object are set. An event on the other hand
is defined as a state change. Usually, an event changes the state of the corresponding
object but this is not mandatory.
States and events can be attached to a WaitSet. The user will be informed only once
by the WaitSet for every event which occurred. If the event occurred multiple times
before the user has requested an event update from the WaitSet the user will still
be informed only once. State changes are induced by events
and the user will be informed about a specific state as long as the state persists.
The subscriber for instance has the state `SubscriberState::HAS_DATA` and the event
`SubscriberEvent::DATA_RECEIVED`. If you attach the subscriber event
`SubscriberEvent::DATA_RECEIVED` to a WaitSet you will be notified about every new
incoming sample whenever you call `WaitSet::wait` or `WaitSet::timedWait`. If multiple
samples were sent before you called those methods you will still receive only one
notification.
If you attach the state `SubscriberState::HAS_DATA` you will
be notified by `WaitSet::wait` or `WaitSet::timedWait` as long as there are received
samples present in the subscriber queue.
## Expected Output
[](https://asciinema.org/a/RmfrWRQIULiFGt7dC8PamKGeK)
## Glossary
- **Event** a state change of an object; a _Triggerable_ will signal an event via a _TriggerHandle_ to
a _Notifyable_. For instance one can attach the subscriber event `DATA_RECEIVED` to _WaitSet_.
This will cause the subscriber to notify the WaitSet via the _TriggerHandle_ everytime a
sample was received.
- **NotificationCallback** a callback attached to a _NotificationInfo_. It must have the
following signature `void ( NotificationOrigin )`. Any free function, static
class method and non capturing lambda expression is allowed. You have to ensure the lifetime of that callback.
This can become important when you would like to use lambda expressions.
- **NotificationId** an id which is tagged to an event. It does not need to be unique
or follow any restrictions. The user can choose any arbitrary `uint64_t`. Assigning
the same _NotificationId_ to multiple _Events_ can be useful when you would like to
group _Events_.
- **NotificationInfo** a class that corresponds to _Triggers_ and is used to inform
the user which _Event_ occurred. You can use the _NotificationInfo_ to acquire
the _NotificationId_, call the _NotificationCallback_ or acquire the _NotificationOrigin_.
- **NotificationOrigin** the pointer to the class where the _Event_ originated from, short
pointer to the _Triggerable_.
- **Notifyable** is a class which listens to events. A _TriggerHandle_ which corresponds to a _Trigger_
is used to notify the _Notifyable_ that an event occurred. The WaitSet is a _Notifyable_.
- **State** a specified set of values to which the members of an object are set.
- **Trigger** a class which is used by the _Notifyable_ to acquire the information which events were
signalled. It corresponds to a _TriggerHandle_. If the _Notifyable_ goes out of scope the corresponding
_TriggerHandle_ will be invalidated and if the _Triggerable_ goes out of scope the corresponding
_Trigger_ will be invalidated.
- **Triggerable** a class which has attached a _TriggerHandle_ to itself to signal
certain _Events_ to a _Notifyable_.
- **TriggerHandle** a thread-safe class which can be used to trigger a _Notifyable_.
If a _TriggerHandle_ goes out of scope it will detach itself from the _Notifyable_. A _TriggerHandle_ is
logical equal to another _Trigger_ if they:
- are attached to the same _Notifyable_ (or in other words they are using the
same `ConditionVariable`)
- they have the same _NotificationOrigin_
- they have the same callback to verify that they were triggered
(`hasNotificationCallback`)
- they have the same _NotificationId_
- **WaitSet** a _Notifyable_ which manages a set of _Triggers_ which are corresponding to _Events_.
A user may attach or detach events. The _Waitset_ is listening
to the whole set of _Triggers_ and if one or more _Triggers_ are triggered by an event it will notify
the user. If a _WaitSet_ goes out of scope all attached _Triggers_ will be
invalidated.
## Quick Overview
**Events** or **States** can be attached to a **Notifyable** like the **WaitSet**.
The **WaitSet** will listen on **Triggers** for a signal that an **Event** has occurred and it hands out
**TriggerHandles** to **Triggerable** objects. The **TriggerHandle** is used to inform the **WaitSet**
about the occurrence of an **Event**. When returning from `WaitSet::wait()` the user is provided with a vector of **NotificationInfos**
associated with **Events** which had occurred and **States** which persists. The **NotificationOrigin**, **NotificationId** and **NotificationCallback**
are stored inside of the **NotificationInfo** and can be acquired by the user.
!!! warning
Please be aware of the thread-safety restrictions of the _WaitSet_ and
read the [Thread Safety](#thread-safety) chapter carefully.
## Reference
| task | call |
|:-----|:-----|
|attach subscriber event to a WaitSet|`waitset.attachEvent(subscriber, iox::popo::SubscriberEvent::DATA_RECEIVED, 123, &mySubscriberCallback)`|
|attach subscriber state to a WaitSet|`waitset.attachState(subscriber, iox::popo::SubscriberState::HAS_DATA, 123, &mySubscriberCallback)`|
|attach user trigger to a WaitSet|`waitset.attachEvent(userTrigger, 456, &myUserTriggerCallback)`|
|wait for triggers |`auto triggerVector = myWaitSet.wait();` |
|wait for triggers with timeout |`auto triggerVector = myWaitSet.timedWait(1_s);` |
|check if event/state originated from some object|`notification->doesOriginateFrom(ptrToSomeObject)`|
|get id of the event/state|`notification->getNotificationId()`|
|call eventCallback|`(*notification)()`|
|acquire _NotificationOrigin_|`notification->getOrigin<OriginType>();`|
## Use Cases
This example consists of 6 use cases.
1. `ice_waitset_basic`: A single subscriber is notified by the WaitSet if data arrives.
2. `ice_waitset_gateway.cpp`: We build a gateway to forward data
to another network. A list of subscriber events are handled in an uniform way
by defining a callback which is executed for every subscriber who
has received data.
3. `ice_waitset_grouping`: We would like to group multiple subscribers into 2 distinct
groups and handle them whenever they have a specified state according to their group membership.
4. `ice_waitset_individual`: A list of subscribers where every subscriber is
handled differently.
5. `ice_waitset_timer_driven_execution`: We use the WaitSet to trigger a cyclic call which should
execute an algorithm every 1 s.
6. `ice_waitset_trigger`: We create our o
ros2 rolling完整代码
需积分: 5 145 浏览量
2023-10-01
00:32:29
上传
评论
收藏 335.69MB GZ 举报
ros2 rolling完整代码 （2000个子文件） 
depender.c 957B exlib.c 718B exlib.c 718B SimpleTest.cpp 164KB ResizeTest.cpp 111KB Cdr.cpp 70KB unit_test.cpp 22KB FastCdr.cpp 20KB class_loader_core.cpp 20KB joint.cpp 19KB camera_info_manager.cpp 18KB keyboard_handler_unix_tests.cpp 18KB link.cpp 17KB interactive_marker_server.cpp 17KB laser_geometry.cpp 17KB projection_test.cpp 16KB test_kdl_parser.cpp 15KB robot_state_publisher.cpp 15KB test_interactive_marker_server.cpp 15KB utest.cpp 14KB test_interactive_marker_client.cpp 14KB tools.cpp 14KB interactive_marker_client.cpp 13KB urdf_unit_test.cpp 12KB keyboard_handler_windows_tests.cpp 11KB utest.cpp 11KB parse_ini.cpp 11KB turtle.cpp 11KB teleop_turtle_key.cpp 11KB urdf_sensor.cpp 10KB keyboard_handler_unix_impl.cpp 10KB parse_yml.cpp 10KB turtle_frame.cpp 10KB unique_ptr_test.cpp 9KB model.cpp 9KB message_context.cpp 9KB default_unix_key_map.cpp 9KB menu_handler.cpp 9KB default_windows_key_map.cpp 7KB keyboard_handler_windows_impl.cpp 7KB image_transport.cpp 7KB kdl_parser.cpp 7KB publisher.cpp 6KB test_moving_average_statistics.cpp 6KB test_qos_override.cpp 6KB test_received_message_age.cpp 6KB test_parse_yml.cpp 6KB camera_subscriber.cpp 6KB draw_square.cpp 6KB multi_library_class_loader.cpp 6KB test_subscriber.cpp 6KB test_message_passing.cpp 6KB composite_plugin_provider.cpp 6KB publication_server.cpp 5KB utest.cpp 5KB list_transports.cpp 5KB test_inertia_rpy.cpp 5KB urdf_to_graphviz.cpp 5KB subscriber.cpp 5KB camera_publisher.cpp 5KB urdf_model_state.cpp 5KB class_loader.cpp 5KB test_parse_ini.cpp 5KB meta_object.cpp 5KB nodelet_plugin_provider.cpp 5KB urdf_version_test.cpp 5KB test_two_links_change_fixed_joint.cpp 4KB retriever.cpp 4KB republish.cpp 4KB keyboard_handler_base.cpp 4KB test_remapping.cpp 4KB plugin_descriptor.cpp 4KB settings.cpp 4KB unique_ptr_test.cpp 4KB pose.cpp 4KB test_collector.cpp 4KB check_urdf.cpp 4KB test_publisher.cpp 4KB parse.cpp 4KB roscpp_plugin_provider.cpp 4KB recursive_plugin_provider.cpp 3KB test_two_links_moving_joint.cpp 3KB plugin_bridge.cpp 3KB test_received_message_period.cpp 3KB parse_wrapper.cpp 3KB generic_proxy.cpp 3KB check_kdl_parser.cpp 3KB plugin_context.cpp 3KB interactive_marker_fixtures.cpp 3KB test.cpp 3KB test_camera_common.cpp 3KB test_two_links_fixed_joint_prefix.cpp 3KB test_single_subscriber_publisher.cpp 3KB test_two_links_fixed_joint.cpp 3KB plugin_provider.cpp 3KB poller.cpp 3KB twist.cpp 3KB camera_common.cpp 3KB moving_average.cpp 3KB convert.cpp 3KB共 2000 条
- 1
- 2
- 3
- 4
- 5
- 6
- 20
资源评论
