Struct WaitSet 

pub struct WaitSet<Service: Service> { /* private fields */ }

The WaitSet implements a reactor pattern and allows to wait on multiple events in one single call WaitSet::wait_and_process_once() until it wakes up or to run repeatedly with WaitSet::wait_and_process() until the a interrupt or termination signal was received or the user has explicitly requested to stop by returning CallbackProgression::Stop in the provided callback.

An struct must implement SynchronousMultiplexing to be attachable. The Listener can be attached as well as sockets or anything else that is FileDescriptorBased.

Can be created via the WaitSetBuilder.

Implementations

impl<Service: Service> WaitSet<Service>

pub fn attach_notification<'waitset, 'attachment, T: SynchronousMultiplexing + Debug>( &'waitset self, attachment: &'attachment T, ) -> Result<WaitSetGuard<'waitset, 'attachment, Service>, WaitSetAttachmentError>

Attaches an object as notification to the WaitSet. Whenever an event is received on the object the WaitSet informs the user in WaitSet::wait_and_process() to handle the event. The object cannot be attached twice and the WaitSet::capacity() is limited by the underlying implementation.

pub fn attach_deadline<'waitset, 'attachment, T: SynchronousMultiplexing + Debug>( &'waitset self, attachment: &'attachment T, deadline: Duration, ) -> Result<WaitSetGuard<'waitset, 'attachment, Service>, WaitSetAttachmentError>

Attaches an object as deadline to the WaitSet. Whenever the event is received or the deadline is hit, the user is informed in WaitSet::wait_and_process(). 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.

pub fn attach_interval( &self, interval: Duration, ) -> Result<WaitSetGuard<'_, '_, Service>, WaitSetAttachmentError>

Attaches a tick event to the WaitSet. Whenever the timeout is reached the WaitSet informs the user in WaitSet::wait_and_process().

pub fn wait_and_process<F: FnMut(WaitSetAttachmentId<Service>) -> CallbackProgression>( &self, fn_call: F, ) -> Result<WaitSetRunResult, WaitSetRunError>

Waits until an event arrives on the WaitSet, then collects all events by calling the provided fn_call callback with the corresponding WaitSetAttachmentId. In contrast to WaitSet::wait_and_process_once() it will never return until the user explicitly requests it by returning CallbackProgression::Stop or by receiving a signal.

The provided callback must return CallbackProgression::Continue to continue the event processing and handle the next event or CallbackProgression::Stop to return from this call immediately. All unhandled events will be lost forever and the call will return WaitSetRunResult::StopRequest.

If an interrupt- (SIGINT) or a termination-signal (SIGTERM) was received, it will exit the loop and inform the user with WaitSetRunResult::Interrupt or WaitSetRunResult::TerminationRequest.

Example

use iceoryx2::prelude::*;


let waitset = WaitSetBuilder::new().create::<ipc::Service>()?;

let on_event = |attachment_id: WaitSetAttachmentId<ipc::Service>| {
    if attachment_id.has_event_from(&guard) {
        // when a certain event arrives we stop the event processing
        // to terminate the process
        CallbackProgression::Stop
    } else {
        CallbackProgression::Continue
    }
};

waitset.wait_and_process(on_event)?;
println!("goodbye");

pub fn wait_and_process_once<F: FnMut(WaitSetAttachmentId<Service>) -> CallbackProgression>( &self, fn_call: F, ) -> Result<WaitSetRunResult, WaitSetRunError>

Waits until an event arrives on the WaitSet, then collects all events by calling the provided fn_call callback with the corresponding WaitSetAttachmentId and then returns. This makes it ideal to be called in some kind of event-loop.

The provided callback must return CallbackProgression::Continue to continue the event processing and handle the next event or CallbackProgression::Stop to return from this call immediately. All unhandled events will be lost forever and the call will return WaitSetRunResult::StopRequest.

If an interrupt- (SIGINT) or a termination-signal (SIGTERM) was received, it will exit the loop and inform the user with WaitSetRunResult::Interrupt or WaitSetRunResult::TerminationRequest.

When no signal was received and all events were handled, it will return WaitSetRunResult::AllEventsHandled.

Example

use iceoryx2::prelude::*;

let waitset = WaitSetBuilder::new().create::<ipc::Service>()?;

let on_event = |attachment_id: WaitSetAttachmentId<ipc::Service>| {
    // do some event processing
    CallbackProgression::Continue
};

// main event loop
loop {
    // blocks until an event arrives, handles all arrived events
    // and then returns.
    waitset.wait_and_process_once(on_event)?;
    // do some event post processing
    println!("handled events");
}

pub fn wait_and_process_once_with_timeout<F: FnMut(WaitSetAttachmentId<Service>) -> CallbackProgression>( &self, fn_call: F, timeout: Duration, ) -> Result<WaitSetRunResult, WaitSetRunError>

Waits until an event arrives on the WaitSet or the provided timeout has passed, then collects all events by calling the provided fn_call callback with the corresponding WaitSetAttachmentId and then returns. This makes it ideal to be called in some kind of event-loop.

The provided callback must return CallbackProgression::Continue to continue the event processing and handle the next event or CallbackProgression::Stop to return from this call immediately. All unhandled events will be lost forever and the call will return WaitSetRunResult::StopRequest.

If an interrupt- (SIGINT) or a termination-signal (SIGTERM) was received, it will exit the loop and inform the user with WaitSetRunResult::Interrupt or WaitSetRunResult::TerminationRequest.

When no signal was received and all events were handled, it will return WaitSetRunResult::AllEventsHandled.

Example

use iceoryx2::prelude::*;

let waitset = WaitSetBuilder::new().create::<ipc::Service>()?;

let on_event = |attachment_id: WaitSetAttachmentId<ipc::Service>| {
    // do some event processing
    CallbackProgression::Continue
};

const TIMEOUT: Duration = Duration::MAX;

// main event loop
loop {
    // blocks until an event arrives or TIMEOUT was reached, handles all arrived events
    // and then returns.
    waitset.wait_and_process_once_with_timeout(on_event, TIMEOUT)?;
    // do some event post processing
    println!("handled events");
}

pub fn capacity(&self) -> usize

Returns the capacity of the WaitSet

pub fn len(&self) -> usize

Returns the number of attachments.

pub fn is_empty(&self) -> bool

Returns true if the WaitSet has no attachments, otherwise false.

pub fn signal_handling_mode(&self) -> SignalHandlingMode

Returns the SignalHandlingMode with which the WaitSet was created.

Trait Implementations

impl<Service: Debug + Service> Debug for WaitSet<Service>

where Service::Reactor: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.