dope-core 0.13.0

The manifold runtime
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

use std::io;
use std::os::fd::BorrowedFd;

use crate::backend::Backend;
use crate::backend::ops::raw::control::{ControlBackend, RawQuiesce};
use crate::io::fd::Fd;
use crate::io::socket::option::SocketOption;

use super::token::Token;
use super::{DriverContext, OutboundReservation, PushError};

#[doc(hidden)]
#[must_use]
pub struct Quiesce<'a> {
    backend: &'a mut Backend,
    state: RawQuiesce,
    targets: bool,
}

#[doc(hidden)]
#[must_use]
pub struct QuiesceOutcome {
    targets: bool,
    poison: bool,
}

impl QuiesceOutcome {
    pub fn has_targets(&self) -> bool {
        self.targets
    }

    pub fn needs_poison(&self) -> bool {
        self.poison
    }
}

impl<'a> Quiesce<'a> {
    fn new(backend: &'a mut Backend) -> Self {
        Self {
            backend,
            state: <Backend as ControlBackend>::begin_quiesce(),
            targets: false,
        }
    }

    /// Synchronously revokes backend access to `target`.
    ///
    /// Once this returns, the owner may release memory retained by the
    /// submission. [`Self::finish`] performs any remaining backend-owned
    /// result reclamation for the complete batch.
    pub fn cancel(&mut self, target: Token) {
        <Backend as ControlBackend>::quiesce_target(self.backend, &mut self.state, target);
        self.targets = true;
    }

    pub fn finish(self) -> QuiesceOutcome {
        QuiesceOutcome {
            targets: self.targets,
            poison: <Backend as ControlBackend>::finish_quiesce(self.backend, self.state),
        }
    }
}

pub trait ContextControl {
    fn prepare_drop(&mut self);
    fn register_shutdown_fd(&mut self, fd: BorrowedFd<'_>) -> io::Result<()>;
    fn reserve_route(&mut self, id: u8) -> bool;
    fn release_route(&mut self, id: u8);
    fn poison_route(&mut self, id: u8);
    fn quiesce(&mut self, targets: &[Token]) -> bool;
    /// Queues an option without waiting for its kernel completion.
    fn submit_option(
        &mut self,
        fd: &Fd<'_>,
        option: impl Into<SocketOption>,
    ) -> Result<(), PushError>;
}

impl ContextControl for DriverContext<'_, '_> {
    fn prepare_drop(&mut self) {
        <Backend as ControlBackend>::prepare_drop(self.backend());
    }

    fn register_shutdown_fd(&mut self, fd: BorrowedFd<'_>) -> io::Result<()> {
        <Backend as ControlBackend>::register_shutdown_fd(self.backend(), fd)
    }

    fn reserve_route(&mut self, id: u8) -> bool {
        <Backend as ControlBackend>::reserve_route(self.backend(), id)
    }

    fn release_route(&mut self, id: u8) {
        <Backend as ControlBackend>::release_route(self.backend(), id);
    }

    fn poison_route(&mut self, id: u8) {
        <Backend as ControlBackend>::poison_route(self.backend(), id);
    }

    fn quiesce(&mut self, targets: &[Token]) -> bool {
        let mut quiesce = Quiesce::new(self.backend());
        for target in targets {
            quiesce.cancel(*target);
        }
        quiesce.finish().needs_poison()
    }

    fn submit_option(
        &mut self,
        fd: &Fd<'_>,
        option: impl Into<SocketOption>,
    ) -> Result<(), PushError> {
        let option = option.into();
        <Backend as ControlBackend>::submit_option(
            self.backend(),
            fd.slot(),
            option.level(),
            option.name(),
            option.value(),
        )
    }
}

impl<'d> DriverContext<'_, 'd> {
    #[doc(hidden)]
    pub fn quiesce_batch(&mut self) -> Quiesce<'_> {
        Quiesce::new(self.backend())
    }

    pub fn reserve_outbound(&mut self, count: u32) -> io::Result<OutboundReservation<'d>> {
        let base = <Backend as ControlBackend>::reserve_outbound(self.backend(), count)?;
        Ok(OutboundReservation::new(base, count))
    }

    #[doc(hidden)]
    pub fn retire_outbound(&mut self, reservation: OutboundReservation<'d>) {
        let (base, count) = reservation.into_range();
        <Backend as ControlBackend>::retire_fixed(self.backend(), base, count);
    }

    #[doc(hidden)]
    pub fn retire_fixed_fd(&mut self, fd: &mut Fd<'d>) {
        let Some(slot) = fd.retire_slot(self.driver_ref()) else {
            return;
        };
        self.backend().close_fd(slot);
        <Backend as ControlBackend>::retire_fixed(self.backend(), slot.raw(), 1);
    }
}