iceoryx2-cal 0.9.2

iceoryx2: [internal] high-level traits and implementations that represents OS primitives in an exchangeable fashion
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

// Copyright (c) 2024 Contributors to the Eclipse Foundation
//
// See the NOTICE file(s) distributed with this work for additional
// information regarding copyright ownership.
//
// This program and the accompanying materials are made available under the
// terms of the Apache Software License 2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0, or the MIT license
// which is available at https://opensource.org/licenses/MIT.
//
// SPDX-License-Identifier: Apache-2.0 OR MIT

use core::{fmt::Debug, time::Duration};

use super::{ListenerCreateError, ListenerWaitError, NotifierNotifyError};

pub mod semaphore;

/// The [`SignalMechanism`] is a building block for [`crate::event::Event`]
/// concept. Its task is to
/// wake up another process/thread with a signal.
pub trait SignalMechanism: Send + Sync + Debug {
    /// Creates a [`SignalMechanism`]. It cannot be used until
    /// [`SignalMechanism::init()`] was called.
    fn new() -> Self;

    /// Initializes the [`SignalMechanism`] in place.
    ///
    /// # Safety
    ///   * [`SignalMechanism::init()`] must called exactly once before all other methods
    unsafe fn init(&mut self) -> Result<(), ListenerCreateError>;

    /// Notifies the counter-part of the [`SignalMechanism`] meaning
    /// that a [`SignalMechanism::try_wait()`], [`SignalMechanism::timed_wait()`]
    /// or [`SignalMechanism::blocking_wait()`] call wakes up and returns true.
    ///
    /// # Safety
    ///   * [`SignalMechanism::init()`] must have been called exactly once
    ///   * Must not be dropped while in use from another process
    unsafe fn notify(&self) -> Result<(), NotifierNotifyError>;

    /// When a signal was received it returns true, otherwise false.
    ///
    /// # Safety
    ///   * [`SignalMechanism::init()`] must have been called exactly once
    ///   * Must not be dropped while in use from another process
    unsafe fn try_wait(&self) -> Result<bool, ListenerWaitError>;

    /// When a signal was received it returns true, otherwise it blocks until
    /// the timeout has passed. If in the meantime a signal arrives it wakes
    /// up and returns true. If no signal was received it returns false.
    ///
    /// This call can be woken up by an operating system SIGINT signal. In this case
    /// it returns [`ListenerWaitError::InterruptSignal`].
    ///
    /// # Safety
    ///   * [`SignalMechanism::init()`] must have been called exactly once
    ///   * Must not be dropped while in use from another process
    unsafe fn timed_wait(&self, timeout: Duration) -> Result<bool, ListenerWaitError>;

    /// When a signal was received it returns true, otherwise it blocks until
    /// a signal was received.
    /// This call can be woken up by an operating system SIGINT signal. In this case
    /// it returns [`ListenerWaitError::InterruptSignal`].
    ///
    /// # Safety
    ///   * [`SignalMechanism::init()`] must have been called exactly once
    ///   * Must not be dropped while in use from another process
    unsafe fn blocking_wait(&self) -> Result<(), ListenerWaitError>;
}