fidl_next/protocol/
transport.rs

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
// Copyright 2024 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

use core::error::Error;
use core::future::Future;

use crate::{Decoder, Encoder};

// Design philosophy:
//
// - Fan-out is best handled by protocols (via executors)
// - Fan-in is best handled by transports (in whatever way is appropriate)
//
// Therefore:
//
// - A transport may only have one receiver at a time. To parallelize, spawn a future for each
//   message.
// - A transport may have many senders at a time. If a transport is serialized, then it must
//   determine the best way to enqueue operations.

/// A transport layer which can send and receive messages.
///
/// The futures provided by this trait should be cancel-safe, which constrains their behavior:
///
/// - Operations should not partially complete.
/// - Operations should only complete during polling.
pub trait Transport: 'static {
    /// The error type for the transport.
    type Error: Error + Send + Sync + 'static;

    /// Splits the transport into a sender and receiver.
    fn split(self) -> (Self::Sender, Self::Receiver);

    /// The sender half of the transport.
    type Sender: Send;
    /// The buffer type for senders.
    type SendBuffer: Send;
    /// The encoder for send buffers.
    type Encoder<'b>: Encoder + Send
    where
        Self: 'b;
    /// The future type for send operations.
    type SendFuture<'s>: Future<Output = Result<(), Self::Error>> + Send
    where
        Self: 's;

    /// Acquires an empty send buffer for the transport.
    fn acquire(sender: &Self::Sender) -> Self::SendBuffer;
    /// Gets the encoder for a buffer.
    fn encoder(buffer: &mut Self::SendBuffer) -> Self::Encoder<'_>;
    /// Sends an encoded message over the transport.
    fn send(sender: &Self::Sender, buffer: Self::SendBuffer) -> Self::SendFuture<'_>;

    /// The receiver half of the transport.
    type Receiver: Send;
    /// The future type for receive operations.
    type RecvFuture<'r>: Future<Output = Result<Option<Self::RecvBuffer>, Self::Error>> + Send
    where
        Self: 'r;
    /// The buffer type for receivers.
    type RecvBuffer: Send;
    /// The decoder for receive buffers.
    type Decoder<'b>: Decoder<'b> + Send
    where
        Self: 'b;

    /// Receives an encoded message over the transport.
    fn recv(receiver: &mut Self::Receiver) -> Self::RecvFuture<'_>;
    /// Gets the decoder for a buffer.
    fn decoder(buffer: &mut Self::RecvBuffer) -> Self::Decoder<'_>;
}