noxious 1.0.4

The core library for noxious, a Rust port of Toxiproxy
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
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153

use thiserror::Error;
use tokio::sync::{broadcast, watch};
use tracing::instrument;

/// The receiver for the stop signal, which can be used to indicate that
/// a part, or all of the system is required to shut down.
/// This stop handle can be cloned to pass the signal to multiple async tasks,
/// and it can be forked to let child tasks have their own stop logic in addition
/// to the parent system  stop logic.
#[derive(Debug)]
pub struct Stop {
    stopped: bool,
    receiver: broadcast::Receiver<()>,
    sender: broadcast::Sender<()>,
}

impl Stop {
    /// Create a new Stop and Stopper
    pub fn new() -> (Stop, Stopper) {
        let (sender, receiver) = broadcast::channel::<()>(1);
        let stopper = Stopper::new(sender.clone());
        let stop = Stop {
            stopped: false,
            receiver,
            sender,
        };
        (stop, stopper)
    }

    /// Check if this particular instance of Stop has received a stop signal.
    /// Note: Only use this in conjunction with `recv`, because if this instance
    /// of Stop does not receive the signal, this will return false.
    pub fn stop_received(&self) -> bool {
        self.stopped
    }

    /// Wait for the stop signal to be received
    pub async fn recv(&mut self) {
        if self.stopped {
            return;
        }

        let _ = self.receiver.recv().await;

        self.stopped = true;
    }

    /// Creates a sub-signal that has its own stopper but propagates the stop signal from the original
    pub fn fork(&self) -> (Stop, Stopper) {
        let (forked_stop, forked_stopper) = Stop::new();
        let forked_sender = forked_stop.sender.clone();
        let mut original_receiver = self.sender.subscribe();
        tokio::spawn(async move {
            while original_receiver.recv().await.is_ok() {
                if forked_sender.send(()).is_err() {
                    // Channel closed, we can no longer forward signal from original to fork
                    break;
                }
            }
            drop(forked_sender);
        });
        (forked_stop, forked_stopper)
    }

    /// Creates a new stopper for this Stop signal that can be used to stop this Stop and all
    /// its forked descendants
    pub fn get_stopper(&self) -> Stopper {
        Stopper::new(self.sender.clone())
    }
}

impl Clone for Stop {
    fn clone(&self) -> Self {
        Self {
            stopped: self.stopped,
            receiver: self.sender.subscribe(),
            sender: self.sender.clone(),
        }
    }
}

impl std::fmt::Display for Stop {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        if self.stop_received() {
            write!(f, "stopped")
        } else {
            write!(f, "NOT stopped")
        }
    }
}

/// A handle that can send a stop signal once to all subscribers
#[derive(Debug, Clone)]
pub struct Stopper {
    sender: broadcast::Sender<()>,
}

impl Stopper {
    pub(crate) fn new(sender: broadcast::Sender<()>) -> Self {
        Self { sender }
    }

    /// Sends the stop signal
    #[instrument(level = "trace", skip(self))]
    pub fn stop(self) {
        let _ = self.sender.send(());
    }
}
/// A receiver for the close signal, which is used to indicate that a resource
/// is ready to close
#[derive(Debug, Clone)]
pub struct Close {
    receiver: watch::Receiver<Option<()>>,
}

/// The sender for the close signal, to indicate that the owner of this closer
/// is ready to close
#[derive(Debug)]
pub struct Closer {
    sender: watch::Sender<Option<()>>,
}

/// The listen channel closed before the close signal was received
#[derive(Error, Copy, Clone, Debug)]
#[error("Close channel closed")]
pub struct CloseError;

/// Could not snd the close signal, listener for close dropped
#[derive(Error, Copy, Clone, Debug)]
#[error("Could not close, already closed?")]
pub struct CloserError;

impl Close {
    /// Create a new Close and Closer
    pub fn new() -> (Close, Closer) {
        let (sender, receiver) = watch::channel(None);
        let close = Close { receiver };
        let closer = Closer { sender };
        (close, closer)
    }

    /// Wait for the close signal
    pub async fn recv(mut self) -> Result<(), CloseError> {
        self.receiver.changed().await.map_err(|_| CloseError)
    }
}

impl Closer {
    /// Send the close signal and consume this closer
    pub fn close(self) -> Result<(), CloseError> {
        self.sender.send(Some(())).map_err(|_| CloseError)
    }
}