[#390] Renamed {try_}wait into {try_}wait_and_process_events

Author: elfenpiff

examples/rust/event_multiplexing/wait.rs

@@ -68,7 +68,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     // loops until the user has pressed CTRL+c, the application has received a SIGTERM or SIGINT
     // signal or the user has called explicitly `waitset.stop()` in the `on_event` callback. We
     // didn't add this to the example so feel free to play around with it.
-    waitset.wait(on_event)?;
+    waitset.wait_and_process_events(on_event)?;
 
     println!("Exit");
 

iceoryx2-ffi/cxx/include/iox2/waitset.hpp

@@ -24,8 +24,8 @@
 namespace iox2 {
 /// The [`WaitSetGuard`] is returned by [`WaitSet::attach_deadline()`], [`WaitSet::attach_notification()`]
 /// or [`WaitSet::attach_interval()`]. As soon as it goes out-of-scope it detaches the attachment.
-/// It can also be used to determine the origin of an event in [`WaitSet::wait()`] or
-/// [`WaitSet::try_wait()`] via [`WaitSetAttachmentId::has_event_from()`] or
+/// It can also be used to determine the origin of an event in [`WaitSet::wait_and_process_events()`] or
+/// [`WaitSet::try_wait_and_process_events()`] via [`WaitSetAttachmentId::has_event_from()`] or
 /// [`WaitSetAttachmentId::has_missed_deadline()`].
 template <ServiceType S>
 class WaitSetGuard {
@@ -93,8 +93,8 @@ template <ServiceType S>
 auto operator<(const WaitSetAttachmentId<S>& lhs, const WaitSetAttachmentId<S>& rhs) -> bool;
 
 /// The [`WaitSet`] implements a reactor pattern and allows to wait on multiple events in one
-/// single call [`WaitSet::try_wait()`] until it wakes up or to run repeatedly with
-/// [`WaitSet::wait()`] until the a interrupt or termination signal was received or the user
+/// single call [`WaitSet::try_wait_and_process_events()`] until it wakes up or to run repeatedly with
+/// [`WaitSet::wait_and_process_events()`] until the a interrupt or termination signal was received or the user
 /// has explicitly requested to stop with [`WaitSet::stop()`].
 ///
 /// The [`Listener`] can be attached as well as sockets or anything else that
@@ -110,7 +110,7 @@ class WaitSet {
     auto operator=(WaitSet&&) noexcept -> WaitSet&;
     ~WaitSet();
 
-    /// Can be called from within a callback during [`WaitSet::wait()`] to signal the [`WaitSet`]
+    /// Can be called from within a callback during [`WaitSet::wait_and_process_events()`] to signal the [`WaitSet`]
     /// to stop running after this iteration.
     void stop();
 
@@ -119,14 +119,15 @@ class WaitSet {
     /// acquire the source.
     /// If an interrupt- (`SIGINT`) or a termination-signal (`SIGTERM`) was received, it will exit
     /// the loop and inform the user via [`WaitSetRunResult`].
-    auto wait(const iox::function<void(WaitSetAttachmentId<S>)>& fn_call)
+    auto wait_and_process_events(const iox::function<void(WaitSetAttachmentId<S>)>& fn_call)
         -> iox::expected<WaitSetRunResult, WaitSetRunError>;
 
     /// Tries to wait on the [`WaitSet`]. The provided callback is called for every attachment that
     /// was triggered and the [`WaitSetAttachmentId`] is provided as an input argument to acquire the
     /// source.
     /// If nothing was triggered the [`WaitSet`] returns immediately.
-    auto try_wait(const iox::function<void(WaitSetAttachmentId<S>)>& fn_call) -> iox::expected<void, WaitSetRunError>;
+    auto try_wait_and_process_events(const iox::function<void(WaitSetAttachmentId<S>)>& fn_call)
+        -> iox::expected<void, WaitSetRunError>;
 
     /// Returns the capacity of the [`WaitSet`]
     auto capacity() const -> uint64_t;
@@ -138,7 +139,7 @@ class WaitSet {
     auto is_empty() const -> bool;
 
     /// Attaches a [`Listener`] as notification to the [`WaitSet`]. Whenever an event is received on the
-    /// object the [`WaitSet`] informs the user in [`WaitSet::wait()`] to handle the event.
+    /// object the [`WaitSet`] informs the user in [`WaitSet::wait_and_process_events()`] to handle the event.
     /// The object cannot be attached twice and the
     /// [`WaitSet::capacity()`] is limited by the underlying implementation.
     ///
@@ -149,7 +150,7 @@ class WaitSet {
     auto attach_notification(const Listener<S>& listener) -> iox::expected<WaitSetGuard<S>, WaitSetAttachmentError>;
 
     /// Attaches a [`FileDescriptorView`] as notification to the [`WaitSet`]. Whenever an event is received on the
-    /// object the [`WaitSet`] informs the user in [`WaitSet::wait()`] to handle the event.
+    /// object the [`WaitSet`] informs the user in [`WaitSet::wait_and_process_events()`] to handle the event.
     /// The object cannot be attached twice and the
     /// [`WaitSet::capacity()`] is limited by the underlying implementation.
     ///
@@ -161,7 +162,7 @@ class WaitSet {
     attach_notification(FileDescriptorView file_descriptor) -> iox::expected<WaitSetGuard<S>, WaitSetAttachmentError>;
 
     /// Attaches a [`Listener`] as deadline to the [`WaitSet`]. Whenever the event is received or the
-    /// deadline is hit, the user is informed in [`WaitSet::wait()`].
+    /// deadline is hit, the user is informed in [`WaitSet::wait_and_process_events()`].
     /// The object cannot be attached twice and the
     /// [`WaitSet::capacity()`] is limited by the underlying implementation.
     /// Whenever the object emits an event the deadline is reset by the [`WaitSet`].
@@ -174,7 +175,7 @@ class WaitSet {
                          iox::units::Duration deadline) -> iox::expected<WaitSetGuard<S>, WaitSetAttachmentError>;
 
     /// Attaches a [`FileDescriptorView`] as deadline to the [`WaitSet`]. Whenever the event is received or the
-    /// deadline is hit, the user is informed in [`WaitSet::wait()`].
+    /// deadline is hit, the user is informed in [`WaitSet::wait_and_process_events()`].
     /// The object cannot be attached twice and the
     /// [`WaitSet::capacity()`] is limited by the underlying implementation.
     /// Whenever the object emits an event the deadline is reset by the [`WaitSet`].
@@ -187,7 +188,7 @@ class WaitSet {
                          iox::units::Duration deadline) -> iox::expected<WaitSetGuard<S>, WaitSetAttachmentError>;
 
     /// Attaches a tick event to the [`WaitSet`]. Whenever the timeout is reached the [`WaitSet`]
-    /// informs the user in [`WaitSet::wait()`].
+    /// informs the user in [`WaitSet::wait_and_process_events()`].
     ///
     /// # Safety
     ///

iceoryx2-ffi/cxx/src/waitset.cpp

@@ -280,11 +280,12 @@ auto run_callback(iox2_waitset_attachment_id_h attachment_id, void* context) {
 }
 
 template <ServiceType S>
-auto WaitSet<S>::wait(const iox::function<void(WaitSetAttachmentId<S>)>& fn_call)
+auto WaitSet<S>::wait_and_process_events(const iox::function<void(WaitSetAttachmentId<S>)>& fn_call)
     -> iox::expected<WaitSetRunResult, WaitSetRunError> {
     iox2_waitset_run_result_e run_result = iox2_waitset_run_result_e_STOP_REQUEST;
     auto ctx = internal::ctx(fn_call);
-    auto result = iox2_waitset_wait(&m_handle, run_callback<S>, static_cast<void*>(&ctx), &run_result);
+    auto result =
+        iox2_waitset_wait_and_process_events(&m_handle, run_callback<S>, static_cast<void*>(&ctx), &run_result);
 
     if (result == IOX2_OK) {
         return iox::ok(iox::into<WaitSetRunResult>(static_cast<int>(run_result)));
@@ -294,10 +295,10 @@ auto WaitSet<S>::wait(const iox::function<void(WaitSetAttachmentId<S>)>& fn_call
 }
 
 template <ServiceType S>
-auto WaitSet<S>::try_wait(const iox::function<void(WaitSetAttachmentId<S>)>& fn_call)
+auto WaitSet<S>::try_wait_and_process_events(const iox::function<void(WaitSetAttachmentId<S>)>& fn_call)
     -> iox::expected<void, WaitSetRunError> {
     auto ctx = internal::ctx(fn_call);
-    auto result = iox2_waitset_try_wait(&m_handle, run_callback<S>, static_cast<void*>(&ctx));
+    auto result = iox2_waitset_try_wait_and_process_events(&m_handle, run_callback<S>, static_cast<void*>(&ctx));
 
     if (result == IOX2_OK) {
         return iox::ok();

iceoryx2-ffi/cxx/tests/src/waitset_tests.cpp

@@ -132,15 +132,15 @@ TYPED_TEST(WaitSetTest, attaching_same_notification_twice_fails) {
 
 TYPED_TEST(WaitSetTest, empty_waitset_returns_error_on_run) {
     auto sut = this->create_sut();
-    auto result = sut.wait([](auto) {});
+    auto result = sut.wait_and_process_events([](auto) {});
 
     ASSERT_THAT(result.has_error(), Eq(true));
     ASSERT_THAT(result.get_error(), Eq(WaitSetRunError::NoAttachments));
 }
 
 TYPED_TEST(WaitSetTest, empty_waitset_returns_error_on_run_once) {
     auto sut = this->create_sut();
-    auto result = sut.try_wait([](auto) {});
+    auto result = sut.try_wait_and_process_events([](auto) {});
 
     ASSERT_THAT(result.has_error(), Eq(true));
     ASSERT_THAT(result.get_error(), Eq(WaitSetRunError::NoAttachments));
@@ -153,7 +153,7 @@ TYPED_TEST(WaitSetTest, interval_attachment_blocks_for_at_least_timeout) {
     auto guard = sut.attach_interval(TIMEOUT).expect("");
 
     auto callback_called = false;
-    auto result = sut.wait([&](auto attachment_id) {
+    auto result = sut.wait_and_process_events([&](auto attachment_id) {
         callback_called = true;
         sut.stop();
         ASSERT_THAT(attachment_id.has_event_from(guard), Eq(true));
@@ -175,7 +175,7 @@ TYPED_TEST(WaitSetTest, deadline_attachment_blocks_for_at_least_timeout) {
     auto guard = sut.attach_deadline(listener, TIMEOUT).expect("");
 
     auto callback_called = false;
-    auto result = sut.wait([&](auto attachment_id) {
+    auto result = sut.wait_and_process_events([&](auto attachment_id) {
         callback_called = true;
         sut.stop();
         ASSERT_THAT(attachment_id.has_event_from(guard), Eq(false));
@@ -201,7 +201,7 @@ TYPED_TEST(WaitSetTest, deadline_attachment_wakes_up_when_notified) {
         auto notifier = this->create_notifier();
         notifier.notify().expect("");
     });
-    auto result = sut.wait([&](auto attachment_id) {
+    auto result = sut.wait_and_process_events([&](auto attachment_id) {
         callback_called = true;
         sut.stop();
         ASSERT_THAT(attachment_id.has_event_from(guard), Eq(true));
@@ -224,7 +224,7 @@ TYPED_TEST(WaitSetTest, notification_attachment_wakes_up_when_notified) {
         auto notifier = this->create_notifier();
         notifier.notify().expect("");
     });
-    auto result = sut.wait([&](auto attachment_id) {
+    auto result = sut.wait_and_process_events([&](auto attachment_id) {
         callback_called = true;
         sut.stop();
         ASSERT_THAT(attachment_id.has_event_from(guard), Eq(true));
@@ -266,7 +266,7 @@ TYPED_TEST(WaitSetTest, triggering_everything_works) {
     std::this_thread::sleep_for(std::chrono::milliseconds(TIMEOUT.toMilliseconds()));
     std::vector<bool> was_triggered(guards.size(), false);
 
-    sut.try_wait([&](auto attachment_id) {
+    sut.try_wait_and_process_events([&](auto attachment_id) {
            for (uint64_t idx = 0; idx < guards.size(); ++idx) {
                if (attachment_id.has_event_from(guards[idx])) {
                    was_triggered[idx] = true;

iceoryx2-ffi/ffi/src/api/waitset.rs

@@ -283,7 +283,7 @@ pub unsafe extern "C" fn iox2_waitset_capacity(handle: iox2_waitset_h_ref) -> c_
     }
 }
 
-/// Stops the current [`iox2_waitset_wait()`] operation. Any [`iox2_waitset_wait()`]
+/// Stops the current [`iox2_waitset_wait_and_process_events()`] operation. Any [`iox2_waitset_wait_and_process_events()`]
 /// call after this call is not affected and the user needs to call
 /// [`iox2_waitset_stop()`] again.
 ///
@@ -305,7 +305,7 @@ pub unsafe extern "C" fn iox2_waitset_stop(handle: iox2_waitset_h_ref) {
 
 /// Attaches a provided [`iox2_file_descriptor_ptr`] as notification to the
 /// [`iox2_waitset_h`]. As soon as the attachment receives data, the WaitSet
-/// wakes up in [`iox2_waitset_wait()`] and informs the user.
+/// wakes up in [`iox2_waitset_wait_and_process_events()`] and informs the user.
 ///
 /// With [`iox2_waitset_attachment_id_has_event_from()`](crate::iox2_waitset_attachment_id_has_event_from())
 /// the origin of the event can be determined from its corresponding
@@ -381,7 +381,7 @@ pub unsafe extern "C" fn iox2_waitset_attach_notification(
 
 /// Attaches a provided [`iox2_file_descriptor_ptr`] as deadline to the
 /// [`iox2_waitset_h`]. As soon as the attachment receives data or the deadline
-/// was missed, the WaitSet wakes up in [`iox2_waitset_wait()`] and informs the user.
+/// was missed, the WaitSet wakes up in [`iox2_waitset_wait_and_process_events()`] and informs the user.
 ///
 /// With [`iox2_waitset_attachment_id_has_event_from()`](crate::iox2_waitset_attachment_id_has_event_from())
 /// the origin of the event can be determined from its corresponding
@@ -469,7 +469,7 @@ pub unsafe extern "C" fn iox2_waitset_attach_deadline(
 }
 
 /// Attaches an interval to the [`iox2_waitset_h`]. As soon as the interval has passed
-/// the WaitSet wakes up in [`iox2_waitset_wait()`] and informs the user.
+/// the WaitSet wakes up in [`iox2_waitset_wait_and_process_events()`] and informs the user.
 ///
 /// With [`iox2_waitset_attachment_id_has_event_from()`](crate::iox2_waitset_attachment_id_has_event_from())
 /// the origin of the event can be determined from its corresponding
@@ -568,7 +568,7 @@ pub unsafe extern "C" fn iox2_waitset_attach_interval(
 ///  * the provided [`iox2_waitset_attachment_id_h`] in the callback must be released via
 ///    [`iox2_waitset_attachment_id_drop()`](crate::iox2_waitset_attachment_id_drop())
 #[no_mangle]
-pub unsafe extern "C" fn iox2_waitset_try_wait(
+pub unsafe extern "C" fn iox2_waitset_try_wait_and_process_events(
     handle: iox2_waitset_h_ref,
     callback: iox2_waitset_run_callback,
     callback_ctx: iox2_callback_context,
@@ -578,26 +578,38 @@ pub unsafe extern "C" fn iox2_waitset_try_wait(
     let waitset = &mut *handle.as_type();
 
     let run_once_result = match waitset.service_type {
-        iox2_service_type_e::IPC => waitset.value.as_ref().ipc.try_wait(|attachment_id| {
-            let attachment_id_ptr = iox2_waitset_attachment_id_t::alloc();
-            (*attachment_id_ptr).init(
-                waitset.service_type,
-                AttachmentIdUnion::new_ipc(attachment_id),
-                iox2_waitset_attachment_id_t::dealloc,
-            );
-            let attachment_id_handle_ptr = (*attachment_id_ptr).as_handle();
-            callback(attachment_id_handle_ptr, callback_ctx);
-        }),
-        iox2_service_type_e::LOCAL => waitset.value.as_ref().local.try_wait(|attachment_id| {
-            let attachment_id_ptr = iox2_waitset_attachment_id_t::alloc();
-            (*attachment_id_ptr).init(
-                waitset.service_type,
-                AttachmentIdUnion::new_local(attachment_id),
-                iox2_waitset_attachment_id_t::dealloc,
-            );
-            let attachment_id_handle_ptr = (*attachment_id_ptr).as_handle();
-            callback(attachment_id_handle_ptr, callback_ctx);
-        }),
+        iox2_service_type_e::IPC => {
+            waitset
+                .value
+                .as_ref()
+                .ipc
+                .try_wait_and_process_events(|attachment_id| {
+                    let attachment_id_ptr = iox2_waitset_attachment_id_t::alloc();
+                    (*attachment_id_ptr).init(
+                        waitset.service_type,
+                        AttachmentIdUnion::new_ipc(attachment_id),
+                        iox2_waitset_attachment_id_t::dealloc,
+                    );
+                    let attachment_id_handle_ptr = (*attachment_id_ptr).as_handle();
+                    callback(attachment_id_handle_ptr, callback_ctx);
+                })
+        }
+        iox2_service_type_e::LOCAL => {
+            waitset
+                .value
+                .as_ref()
+                .local
+                .try_wait_and_process_events(|attachment_id| {
+                    let attachment_id_ptr = iox2_waitset_attachment_id_t::alloc();
+                    (*attachment_id_ptr).init(
+                        waitset.service_type,
+                        AttachmentIdUnion::new_local(attachment_id),
+                        iox2_waitset_attachment_id_t::dealloc,
+                    );
+                    let attachment_id_handle_ptr = (*attachment_id_ptr).as_handle();
+                    callback(attachment_id_handle_ptr, callback_ctx);
+                })
+        }
     };
 
     match run_once_result {
@@ -631,7 +643,7 @@ pub unsafe extern "C" fn iox2_waitset_try_wait(
 ///  * the provided [`iox2_waitset_attachment_id_h`] in the callback must be released via
 ///    [`iox2_waitset_attachment_id_drop()`](crate::iox2_waitset_attachment_id_drop())
 #[no_mangle]
-pub unsafe extern "C" fn iox2_waitset_wait(
+pub unsafe extern "C" fn iox2_waitset_wait_and_process_events(
     handle: iox2_waitset_h_ref,
     callback: iox2_waitset_run_callback,
     callback_ctx: iox2_callback_context,
@@ -643,26 +655,38 @@ pub unsafe extern "C" fn iox2_waitset_wait(
     let waitset = &mut *handle.as_type();
 
     let run_result = match waitset.service_type {
-        iox2_service_type_e::IPC => waitset.value.as_ref().ipc.wait(|attachment_id| {
-            let attachment_id_ptr = iox2_waitset_attachment_id_t::alloc();
-            (*attachment_id_ptr).init(
-                waitset.service_type,
-                AttachmentIdUnion::new_ipc(attachment_id),
-                iox2_waitset_attachment_id_t::dealloc,
-            );
-            let attachment_id_handle_ptr = (*attachment_id_ptr).as_handle();
-            callback(attachment_id_handle_ptr, callback_ctx);
-        }),
-        iox2_service_type_e::LOCAL => waitset.value.as_ref().local.wait(|attachment_id| {
-            let attachment_id_ptr = iox2_waitset_attachment_id_t::alloc();
-            (*attachment_id_ptr).init(
-                waitset.service_type,
-                AttachmentIdUnion::new_local(attachment_id),
-                iox2_waitset_attachment_id_t::dealloc,
-            );
-            let attachment_id_handle_ptr = (*attachment_id_ptr).as_handle();
-            callback(attachment_id_handle_ptr, callback_ctx);
-        }),
+        iox2_service_type_e::IPC => {
+            waitset
+                .value
+                .as_ref()
+                .ipc
+                .wait_and_process_events(|attachment_id| {
+                    let attachment_id_ptr = iox2_waitset_attachment_id_t::alloc();
+                    (*attachment_id_ptr).init(
+                        waitset.service_type,
+                        AttachmentIdUnion::new_ipc(attachment_id),
+                        iox2_waitset_attachment_id_t::dealloc,
+                    );
+                    let attachment_id_handle_ptr = (*attachment_id_ptr).as_handle();
+                    callback(attachment_id_handle_ptr, callback_ctx);
+                })
+        }
+        iox2_service_type_e::LOCAL => {
+            waitset
+                .value
+                .as_ref()
+                .local
+                .wait_and_process_events(|attachment_id| {
+                    let attachment_id_ptr = iox2_waitset_attachment_id_t::alloc();
+                    (*attachment_id_ptr).init(
+                        waitset.service_type,
+                        AttachmentIdUnion::new_local(attachment_id),
+                        iox2_waitset_attachment_id_t::dealloc,
+                    );
+                    let attachment_id_handle_ptr = (*attachment_id_ptr).as_handle();
+                    callback(attachment_id_handle_ptr, callback_ctx);
+                })
+        }
     };
 
     match run_result {

iceoryx2-ffi/ffi/src/api/waitset_attachment_id.rs

@@ -112,8 +112,8 @@ impl HandleToType for iox2_waitset_attachment_id_h_ref {
 
 // BEGIN C API
 /// Release an [`iox2_waitset_attachment_id_h`] that was acquired by calling either
-/// * [`iox2_waitset_wait()`](crate::iox2_waitset_wait())
-/// * [`iox2_waitset_try_wait()`](crate::iox2_waitset_try_wait())
+/// * [`iox2_waitset_wait_and_process_events()`](crate::iox2_waitset_wait_and_process_events())
+/// * [`iox2_waitset_try_wait_and_process_events()`](crate::iox2_waitset_try_wait_and_process_events())
 ///
 /// # Safety
 ///  * `handle` must be valid and provided by the previously mentioned functions.