dope-net 0.20.0

Owned network transports for dope
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

use std::convert::Infallible;

use dope_core::{
    driver::{
        result, retained,
        retained::flight,
        route::{self, kind},
    },
    io::fd::handles,
};

use crate::wire::send::{
    self, Either, Submitted,
    sources::{plain::Slice, vectored::Vectors},
};

pub trait Plain<'a> {
    /// Constructs a retained direct-send view.
    /// # Safety
    /// The bytes stay fixed through completion or quiescence.
    unsafe fn retain(self) -> send::Plain<'a>;
}

impl<'a> Plain<'a> for &'a [u8] {
    unsafe fn retain(self) -> send::Plain<'a> {
        send::Plain::proven(self)
    }
}

/// Native submission which erases the borrowed representation's lifetime.
pub trait Ready<'a> {
    /// # Safety
    /// Retain descriptor authority and the immutable payload/message graph at
    /// fixed addresses through completion or quiescence.
    unsafe fn submit<'owner, 'd: 'owner, Tag: route::Tag + route::Select<kind::Send>>(
        self,
        fd: &handles::Descriptor<'d>,
        target: route::Target<'d, Tag>,
        slots: &flight::Slots<'d, Tag>,
        driver: retained::Context<'_, 'owner, 'd>,
    ) -> Result<Submitted<'d>, result::SubmitError>
    where
        'owner: 'a;
}

impl<'a> Ready<'a> for Infallible {
    unsafe fn submit<'owner, 'd: 'owner, Tag: route::Tag + route::Select<kind::Send>>(
        self,
        _: &handles::Descriptor<'d>,
        _: route::Target<'d, Tag>,
        _: &flight::Slots<'d, Tag>,
        _: retained::Context<'_, 'owner, 'd>,
    ) -> Result<Submitted<'d>, result::SubmitError>
    where
        'owner: 'a,
    {
        match self {}
    }
}

impl<'a> Ready<'a> for Slice<'a> {
    unsafe fn submit<'owner, 'd: 'owner, Tag: route::Tag + route::Select<kind::Send>>(
        self,
        fd: &handles::Descriptor<'d>,
        target: route::Target<'d, Tag>,
        slots: &flight::Slots<'d, Tag>,
        driver: retained::Context<'_, 'owner, 'd>,
    ) -> Result<Submitted<'d>, result::SubmitError>
    where
        'owner: 'a,
    {
        let op = retained::raw::Submission::send(fd, self.view, target);
        // SAFETY: the caller retains the exact bytes and descriptor authority
        // through the terminal completion represented by the returned flight.
        let flight = unsafe { op.try_submit(driver, slots) }?;
        Ok(Submitted {
            bytes: self.bytes,
            flight,
        })
    }
}

impl<'a> Ready<'a> for Vectors<'a> {
    unsafe fn submit<'owner, 'd: 'owner, Tag: route::Tag + route::Select<kind::Send>>(
        self,
        fd: &handles::Descriptor<'d>,
        target: route::Target<'d, Tag>,
        slots: &flight::Slots<'d, Tag>,
        driver: retained::Context<'_, 'owner, 'd>,
    ) -> Result<Submitted<'d>, result::SubmitError>
    where
        'owner: 'a,
    {
        let op = retained::raw::Submission::send_msg(fd, self.message, target);
        // SAFETY: the caller retains the exact message graph, payload and
        // descriptor authority through terminal completion or quiescence.
        let flight = unsafe { op.try_submit(driver, slots) }?;
        Ok(Submitted {
            bytes: self.bytes,
            flight,
        })
    }
}

impl<'a, L: Ready<'a>, R: Ready<'a>> Ready<'a> for Either<L, R> {
    unsafe fn submit<'owner, 'd: 'owner, Tag: route::Tag + route::Select<kind::Send>>(
        self,
        fd: &handles::Descriptor<'d>,
        target: route::Target<'d, Tag>,
        slots: &flight::Slots<'d, Tag>,
        driver: retained::Context<'_, 'owner, 'd>,
    ) -> Result<Submitted<'d>, result::SubmitError>
    where
        'owner: 'a,
    {
        // SAFETY: the active branch retains the exact graph covered by the
        // caller's submission contract; selecting it changes no addresses.
        match self {
            Self::Left(data) => unsafe { data.submit(fd, target, slots, driver) },
            Self::Right(data) => unsafe { data.submit(fd, target, slots, driver) },
        }
    }
}

pub(crate) struct Submission<R>(pub(crate) R);

impl<R> Submission<R> {
    pub(crate) fn submit<'a, 'owner: 'a, 'd: 'owner, Tag: route::Tag + route::Select<kind::Send>>(
        self,
        fd: &handles::Descriptor<'d>,
        target: route::Target<'d, Tag>,
        slots: &flight::Slots<'d, Tag>,
        driver: retained::Context<'_, 'owner, 'd>,
    ) -> Result<Submitted<'d>, result::SubmitError>
    where
        R: Ready<'a>,
    {
        // SAFETY: the installed pool retains wire and queue storage; direct callers
        // additionally establish the original source graph's retention contract.
        unsafe { self.0.submit(fd, target, slots, driver) }
    }
}