bytes-handoff 1.0.0

Incremental async byte ingestion and bounded owned write handoff.
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

use bytes::Bytes;
use thiserror::Error;

#[derive(Debug, Error)]
pub enum BufferError {
    #[error("buffer limit exceeded: attempted {attempted} bytes, limit {limit} bytes")]
    LimitExceeded { attempted: usize, limit: usize },
    #[error("split prefix out of bounds: requested {requested} bytes, available {available} bytes")]
    SplitOutOfBounds { requested: usize, available: usize },
    #[error("read error: {0}")]
    Io(#[from] std::io::Error),
}

#[derive(Debug, Error)]
pub enum WriteError {
    #[error("write handoff is closed")]
    Closed,
    #[error("write exceeds byte budget: attempted {attempted} bytes, limit {limit} bytes")]
    ByteBudgetExceeded { attempted: usize, limit: usize },
    #[error("write error: {0}")]
    Io(#[from] std::io::Error),
}

#[derive(Debug, Error)]
#[error("write handoff backpressure: {reason}")]
pub struct WriteBackpressure {
    reason: BackpressureReason,
    bytes: Bytes,
}

impl WriteBackpressure {
    pub(crate) fn closed(bytes: Bytes) -> Self {
        Self {
            reason: BackpressureReason::Closed,
            bytes,
        }
    }

    pub(crate) fn queue_full(bytes: Bytes) -> Self {
        Self {
            reason: BackpressureReason::QueueFull,
            bytes,
        }
    }

    pub(crate) fn byte_budget_exceeded(bytes: Bytes, attempted: usize, limit: usize) -> Self {
        Self {
            reason: BackpressureReason::ByteBudgetExceeded { attempted, limit },
            bytes,
        }
    }

    pub fn into_bytes(self) -> Bytes {
        self.bytes
    }

    pub fn reason(&self) -> BackpressureReason {
        self.reason
    }
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum BackpressureReason {
    Closed,
    QueueFull,
    ByteBudgetExceeded { attempted: usize, limit: usize },
}

impl std::fmt::Display for BackpressureReason {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Closed => f.write_str("closed"),
            Self::QueueFull => f.write_str("queue full"),
            Self::ByteBudgetExceeded { attempted, limit } => {
                write!(
                    f,
                    "byte budget exceeded: attempted {attempted} bytes, limit {limit} bytes"
                )
            }
        }
    }
}