Transport

fidl_next

Trait Transport 

Source 
pub trait Transport {
    type Error: Clone + Error + Send + Sync + 'static;
    type Shared: Send + Sync;
    type Exclusive: Send;
    type SendBuffer: Encoder + Send;
    type SendFutureState: Send;
    type RecvFutureState: Send;
    type RecvBuffer: Decoder + Send;

    // Required methods
    fn split(self) -> (Self::Shared, Self::Exclusive);
    fn acquire(shared: &Self::Shared) -> Self::SendBuffer;
    fn begin_send(
        shared: &Self::Shared,
        buffer: Self::SendBuffer,
    ) -> Self::SendFutureState;
    fn poll_send(
        future: Pin<&mut Self::SendFutureState>,
        cx: &mut Context<'_>,
        shared: &Self::Shared,
    ) -> Poll<Result<(), Option<Self::Error>>>;
    fn begin_recv(
        shared: &Self::Shared,
        exclusive: &mut Self::Exclusive,
    ) -> Self::RecvFutureState;
    fn poll_recv(
        future: Pin<&mut Self::RecvFutureState>,
        cx: &mut Context<'_>,
        shared: &Self::Shared,
        exclusive: &mut Self::Exclusive,
    ) -> Poll<Result<Self::RecvBuffer, Option<Self::Error>>>;
}
Expand description

A transport backend which can send and receive messages.

§Terminology

Note that this trait does not correspond directly with the FIDL notion of a transport. For clarity, implementors of this trait should be called “transport backends”, as they are specific implementations of the more general notion of a “transport” in FIDL.

In FIDL, protocols can be assigned a “transport” such as “Channel” or “Driver”. The choice of transport for a protocol controls the concrete types used for client ends and server ends of that protocol. A protocol with “Channel” transport will have client and server ends that are Zircon channels; a protocol with “Driver” transport will have client and server ends that are Driver channels.

All transport backends must be able to send and receive buffers of bytes. In addition to those bytes, transport backends may also support sending and receiving resource types like Zircon and Driver handles with those bytes. The additional resource types a transport backend supports defines which protocols can be run over that transport backend: a protocol can be run over a transport backend if all of the resource types its messages may contain can be sent and received using that transport backend. This may or may not have a correlation with the FIDL transport of that protocol.

§Implementation

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.

SendFuture should return Poll::Ready with an error when polled after the transport backend is closed.

Required Associated Types§

Source

type Error: Clone + Error + Send + Sync + 'static

The error type for the transport backend.

Source

type Shared: Send + Sync

The shared part of the transport backend. It is provided by shared reference while sending and receiving. For an MPSC, this would contain a sender.

Source

type Exclusive: Send

The exclusive part of the transport backend. It is provided by mutable reference only while receiving. For an MPSC, this would contain a receiver.

Source

type SendBuffer: Encoder + Send

The buffer type for sending.

Source

type SendFutureState: Send

The future state for send operations.

Source

type RecvFutureState: Send

The future state for receive operations.

Source

type RecvBuffer: Decoder + Send

The buffer type for receivers.

Required Methods§

Source

fn split(self) -> (Self::Shared, Self::Exclusive)

Splits the transport backend into shared and exclusive pieces.

Source

fn acquire(shared: &Self::Shared) -> Self::SendBuffer

Acquires an empty send buffer for the transport backend.

Source

fn begin_send( shared: &Self::Shared, buffer: Self::SendBuffer, ) -> Self::SendFutureState

Begins sending a SendBuffer over this transport backend.

Returns the state for a future which can be polled with poll_send.

Source

fn poll_send( future: Pin<&mut Self::SendFutureState>, cx: &mut Context<'_>, shared: &Self::Shared, ) -> Poll<Result<(), Option<Self::Error>>>

Polls a SendFutureState for completion with the shared part of the transport backend.

When ready, polling returns one of three values:

  • Ok(()) if the buffer was successfully sent.
  • Err(None) if the connection was terminated normally (e.g. with PEER_CLOSED).
  • Err(Some(error)) if the connection was terminated abnormally.
Source

fn begin_recv( shared: &Self::Shared, exclusive: &mut Self::Exclusive, ) -> Self::RecvFutureState

Begins receiving a RecvBuffer over this transport backend.

Returns the state for a future which can be polled with poll_recv.

Source

fn poll_recv( future: Pin<&mut Self::RecvFutureState>, cx: &mut Context<'_>, shared: &Self::Shared, exclusive: &mut Self::Exclusive, ) -> Poll<Result<Self::RecvBuffer, Option<Self::Error>>>

Polls a RecvFutureState for completion with a receiver.

When ready, polling returns one of three values:

  • Ok(buffer) if buffer was successfully received.
  • Err(None) if the connection was terminated normally (e.g. with PEER_CLOSED).
  • Err(Some(error)) if the connection was terminated abnormally.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§