swctx 0.3.0

One-shot channel with some special semantics.
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

use std::sync::Arc;

use crate::err::Error;

use super::{Shared, State};


/// End-point used to send value to the paired [`WaitCtx`](super::WaitCtx).
#[repr(transparent)]
pub struct SetCtx<T, S: Clone, E>(pub(crate) Arc<Shared<T, S, E>>);

impl<T, S, E> SetCtx<T, S, E>
where
  S: Clone
{
  /// Set the internal [`SetCtx`] state.
  ///
  /// If an `SetCtx` is dropped prematurely (i.e. without setting a value or
  /// repering a failure) an `Error::Aborted(S)` will automatically be sent to
  /// the linked [`WaitCtx`](super::WaitCtx) object, where `S` will be set to
  /// the value last set using `set_state()`.
  ///
  /// ```
  /// use std::thread;
  /// use swctx::{mkpair, Error};
  ///
  /// #[derive(Clone, Debug, Default, PartialEq)]
  /// enum State {
  ///   #[default]
  ///   Init,
  ///   InThread
  /// }
  ///
  /// let (sctx, wctx) = mkpair::<&str, State, &str>();
  /// let jh = thread::spawn(move || {
  ///   sctx.set_state(State::InThread);
  ///   // sctx is prematurely dropped here
  /// });
  /// jh.join().unwrap();
  ///
  /// assert_eq!(wctx.wait(), Err(Error::Aborted(State::InThread)));
  /// ```
  ///
  /// # Errors
  /// If the corresponding [`WaitCtx`](super::WaitCtx) has been dropped,
  /// [`Error::LostWaiter`] will be returned.
  pub fn set_state(&self, s: S) -> Result<(), Error<S, E>> {
    let mut inner = self.0.inner.lock();
    if inner.wctx_dropped {
      return Err(Error::LostWaiter);
    }
    inner.sctx_state = s;
    drop(inner);
    Ok(())
  }

  /// Consume the `SetCtx` and store a value for the wait context to return.
  ///
  /// # Errors
  /// If the corresponding [`WaitCtx`](super::WaitCtx) has been dropped,
  /// [`Error::LostWaiter`] will be returned.
  pub fn set(self, data: T) -> Result<(), Error<S, E>> {
    // - This and `fail()` consume `self`.
    // - The wait context does not modify the state.
    // - The only other method is `set_state()` and it only touches
    //   `sctx_state` and not `state`.
    //
    // These facts allow us to safely assume that the state does not need to be
    // checked here -- it can only be `Waiting`.
    let mut inner = self.0.inner.lock();
    if inner.wctx_dropped {
      return Err(Error::LostWaiter);
    }

    inner.state = State::Data(data);
    self.0.notify_waiter(&mut inner);
    drop(inner);

    Ok(())
  }

  /// Consume the `SetCtx` and store an error value for the wait context to
  /// return.
  ///
  /// # Errors
  /// If the corresponding [`WaitCtx`](super::WaitCtx) has been dropped,
  /// [`Error::LostWaiter`] will be returned.
  pub fn fail(self, error: E) -> Result<(), Error<S, E>> {
    // See comments in SetCtx::set() for implementation details.
    let mut inner = self.0.inner.lock();
    if inner.wctx_dropped {
      return Err(Error::LostWaiter);
    }

    inner.state = State::Err(Error::App(error));
    self.0.notify_waiter(&mut inner);
    drop(inner);

    Ok(())
  }
}

impl<T, S, E> Drop for SetCtx<T, S, E>
where
  S: Clone
{
  fn drop(&mut self) {
    let mut inner = self.0.inner.lock();
    match inner.state {
      State::Waiting => {
        inner.state = State::Err(Error::Aborted(inner.sctx_state.clone()));
        self.0.notify_waiter(&mut inner);
        drop(inner);
      }
      State::Data(_) | State::Err(_) | State::Finalized => {
        // Do nothing.
        // For the Data base, assume the waiter will handle the data.
      }
    }
  }
}

// vim: set ft=rust et sw=2 ts=2 sts=2 cinoptions=2 tw=79 :