dfir_rs 0.16.0

DFIR runtime for Rust, used by Hydro.
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

//! Trait for the `demux_enum` derive and operator.

use std::task::{Context, Poll};

pub use dfir_macro::DemuxEnum;
use dfir_pipes::Toggle;
use dfir_pipes::push::PushStep;

/// Trait for use with the `demux_enum` operator (Sink-based version).
///
/// This trait is meant to be derived: `#[derive(DemuxEnum)]`.
///
/// The derive will implement this such that `Outputs` can be any tuple where each item is a
/// `Sink` that corresponds to each of the variants of the tuple, in alphabetic order.
#[diagnostic::on_unimplemented(
    note = "ensure there is exactly one output for each enum variant.",
    note = "ensure that the type for each output is a tuple of the field for the variant: `()`, `(a,)`, or `(a, b, ...)`."
)]
pub trait DemuxEnumSink<Outputs>: DemuxEnumBase {
    /// The error type for pushing self into the `Outputs` `Sink`s.
    type Error;

    /// Call `poll_ready` on all `Outputs`.
    fn poll_ready(outputs: &mut Outputs, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>;

    /// Pushes `self` into the corresponding output sink in `outputs`.
    fn start_send(self, outputs: &mut Outputs) -> Result<(), Self::Error>;

    /// Call `poll_flush` on all `Outputs`.
    fn poll_flush(outputs: &mut Outputs, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>;

    /// Call `poll_close` on all `Outputs`.
    fn poll_close(outputs: &mut Outputs, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>;
}

/// Trait for use with the `demux_enum` operator (Push-based version).
///
/// This trait is meant to be derived: `#[derive(DemuxEnum)]`.
///
/// The derive will implement this such that `Outputs` can be any tuple where each item is a
/// `Push` that corresponds to each of the variants of the tuple, in alphabetic order.
#[diagnostic::on_unimplemented(
    note = "ensure there is exactly one output for each enum variant.",
    note = "ensure that the type for each output is a tuple of the field for the variant: `()`, `(a,)`, or `(a, b, ...)`."
)]
pub trait DemuxEnumPush<Outputs, Meta: Copy>: DemuxEnumBase {
    /// The context type, inherited from the downstream pushes.
    type Ctx<'ctx>: dfir_pipes::Context<'ctx>;

    /// Whether this push can return [`PushStep::Pending`], inherited from the
    /// downstream pushes.
    type CanPend: Toggle;

    /// Poll readiness of all output pushes.
    fn poll_ready(outputs: &mut Outputs, ctx: &mut Self::Ctx<'_>) -> PushStep<Self::CanPend>;

    /// Pushes `self` into the corresponding output push in `outputs`.
    fn start_send(self, meta: Meta, outputs: &mut Outputs);

    /// Flushes all output pushes.
    fn poll_flush(outputs: &mut Outputs, ctx: &mut Self::Ctx<'_>) -> PushStep<Self::CanPend>;

    /// Supplies all outputs with bounds on the number of items about to be sent.
    fn size_hint(outputs: &mut Outputs, hint: (usize, Option<usize>));
}
/// Special case of [`DemuxEnum`] for when there is only one variant.
#[diagnostic::on_unimplemented(
    note = "requires that the enum have only one variant.",
    note = "ensure there are no missing outputs; there must be exactly one output for each enum variant."
)]
pub trait SingleVariant: DemuxEnumBase {
    /// Output tuple type.
    type Output;
    /// Convert self into it's single variant tuple Output.
    fn single_variant(self) -> Self::Output;
}

/// Base implementation to constrain that [`DemuxEnum<SOMETHING>`] is implemented.
#[diagnostic::on_unimplemented(note = "use `#[derive(dfir_rs::DemuxEnum)]`")]
pub trait DemuxEnumBase {}