how-far 0.1.0

Cancellation, progress, and weighted phases through one interface for library authors
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

//! A pulse made from a cancellation policy alone.
use crate::{Child, Execution, PhaseSpec, PlanError, Pulse, Report, SharedPulse, Total};
use alloc::{sync::Arc, vec::Vec};
use core::fmt;
use enough::{Stop, StopReason};

/// A stop policy held by value or by reference. Only an owned one can be shared.
#[derive(Clone)]
pub(crate) enum StopSource<'a> {
    Borrowed(&'a dyn Stop),
    Owned(Arc<dyn Stop>),
}
impl StopSource<'_> {
    pub(crate) fn get(&self) -> &dyn Stop {
        match self {
            Self::Borrowed(stop) => *stop,
            Self::Owned(stop) => stop.as_ref(),
        }
    }
    pub(crate) fn owned(&self) -> Result<Arc<dyn Stop>, PlanError> {
        match self {
            Self::Borrowed(_) => Err(PlanError::NotShareable),
            Self::Owned(stop) => Ok(stop.clone()),
        }
    }
}

/// Cancellation without progress: a pulse made from any [`Stop`].
///
/// For an application that holds a cancellation token, such as a `Stopper` or
/// a deadline, and calls a library that takes `&dyn Pulse`. Every phase the
/// library plans checks the same stop; reports go nowhere, and plans are only
/// validated. An owned stop can be [shared](Pulse::share) with spawned work; a
/// borrowed one serves scoped work and refuses to be shared.
///
/// ```
/// use how_far::{prelude::*, PhaseSpec, Stages, StopOnly, StopReason, Total};
///
/// // A library that knows nothing about the caller's token.
/// fn encode(rows: u64, pulse: &dyn Pulse) -> Result<(), StopReason> {
///     Stages::new(pulse, &[PhaseSpec::new("rows", 1, Total::Exact(rows))])
///         .complete_with(|stages| stages.run(|stage| {
///             for _ in 0..rows {
///                 stage.step(1)?;
///             }
///             Ok(())
///         }))
/// }
///
/// struct Cancelled;
/// impl Stop for Cancelled {
///     fn check(&self) -> Result<(), StopReason> {
///         Err(StopReason::Cancelled)
///     }
/// }
/// assert_eq!(encode(8, &StopOnly::new(Cancelled)), Err(StopReason::Cancelled));
/// assert_eq!(encode(8, &StopOnly::borrowed(&how_far::Unstoppable)), Ok(()));
/// ```
pub struct StopOnly<'a> {
    stop: StopSource<'a>,
}

impl StopOnly<'static> {
    /// Own `stop`; the pulse and its shared views can outlive the caller.
    pub fn new(stop: impl Stop + 'static) -> Self {
        Self {
            stop: StopSource::Owned(Arc::new(stop)),
        }
    }
}

impl<'a> StopOnly<'a> {
    /// Borrow `stop`, without allocating. [`Pulse::share`] then fails with
    /// [`PlanError::NotShareable`], since the view could outlive the borrow.
    pub fn borrowed(stop: &'a dyn Stop) -> Self {
        Self {
            stop: StopSource::Borrowed(stop),
        }
    }
}

impl fmt::Debug for StopOnly<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("StopOnly")
            .field("owned", &matches!(self.stop, StopSource::Owned(_)))
            .finish()
    }
}

impl Stop for StopOnly<'_> {
    #[track_caller]
    fn check(&self) -> Result<(), StopReason> {
        self.stop.get().check()
    }
    fn may_stop(&self) -> bool {
        self.stop.get().may_stop()
    }
}

impl Report for StopOnly<'_> {
    fn advance(&self, _: u64) {}
    fn may_report(&self) -> bool {
        false
    }
}

impl Pulse for StopOnly<'_> {
    fn split(&self, _: Execution, parts: &[PhaseSpec<'_>]) -> Result<Vec<Child<'_>>, PlanError> {
        PhaseSpec::validate_split(parts)?;
        // Untracked children check this token at every level and share
        // through it.
        Ok(crate::pulse::untracked_children(self, parts.len()))
    }
    /// Nobody observes the total, so a revision is accepted and discarded.
    fn set_total(&self, _: Total) -> Result<(), PlanError> {
        Ok(())
    }
    fn share(&self) -> Result<SharedPulse, PlanError> {
        Ok(SharedPulse::new(StopOnly {
            stop: StopSource::Owned(self.stop.owned()?),
        }))
    }
}