fidl_next_protocol/
lib.rs

1// Copyright 2024 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5//! Protocol support for FIDL.
6//!
7//! This crate provides a number of types and traits related to FIDL protocols.
8//! These types and traits are all "untyped" - that is, they do not know about
9//! the specific types of the FIDL messages being sent and received. They only
10//! deal with protocol-layer semantics: requests and responses, clients and
11//! servers, and transports.
12//!
13//! ## Transports
14//!
15//! This crate uses "transport" to refer to the specific object which moves
16//! bytes and handles from a sender to a receiver. For example, this crate may
17//! refer to a channel, socket, file, or other byte source/sink as a
18//! "transport". This differs from the `@transport(..)` annotation in the FIDL
19//! language, which can be added to protocols.
20//!
21//! FIDL transports implement the [`Transport`] trait. This trait defines
22//! several key properties:
23//!
24//! - The associated [`Shared`](Transport::Shared) and
25//!   [`Exclusive`](Transport::Exclusive) types.
26//! - The buffer types for sending and receiving data.
27//! - The `async` methods for sending and receiving data with those buffers.
28//!
29//! All types in the protocol layer are generic over the transport, making it
30//! easy to add support for new types of transports.
31//!
32//! By default, both sending and receiving data with a transport are
33//! asynchronous operations. However, transports may support synchronous send
34//! operations by implementing the [`NonBlockingTransport`] trait. This trait
35//! allows users to replace `.await`-ing a send operation with
36//! [`.send_immediately()`](NonBlockingTransport::send_immediately), which
37//! synchronously completes the send future.
38//!
39//! This crate provides an implementation of `Transport` for Fuchsia channels.
40//!
41//! ## Clients and servers
42//!
43//! [`ClientDispatcher`]s and [`ServerDispatcher`]s are constructed from a
44//! transport, and can be `run` with a corresponding [`ClientHandler`] or
45//! [`ServerHandler`]. The dispatcher will then run its event loop to receive
46//! data through the transport. Client dispatchers use their handlers to handle
47//! incoming events, and coordinate with any [`Client`]s to route two-way method
48//! responses to waiting futures. Server dispatchers use their handlers to
49//! handle incoming one-way and two-way method requests, but do not generally
50//! coordinate with their associated [`Server`]s.
51//!
52//! [`Client`]s and [`Server`]s implement `Clone`, and should be cloned to
53//! interact with the connection from multiple locations.
54//!
55//! ## Message ordering
56//!
57//! Dispatchers are guaranteed to handle requests and events serially and in the
58//! order they are received. However, because the responses to two-way messages
59//! are awaited at the call site and not handled by the dispatcher, there is no
60//! guarantee about the relative orderings of responses and subsequent events.
61//! This means that if a malformed two-way response is received, the resulting
62//! connection closure may not occur before subsequent events are processed.
63//!
64//! Two-way responses are guaranteed to preserve completion order relative to
65//! each other: if response A is received before response B, and the future
66//! awaiting response B completes, then the future awaiting response A will
67//! complete on the next poll. However, the executor may schedule tasks ready to
68//! make progress in any order it chooses. This means that the orders in which
69//! tasks awaiting two-way responses were scheduled may not match the orders in
70//! which those responses were received.
71
72#![deny(
73    future_incompatible,
74    missing_docs,
75    nonstandard_style,
76    unused,
77    warnings,
78    clippy::all,
79    clippy::alloc_instead_of_core,
80    clippy::missing_safety_doc,
81    clippy::std_instead_of_core,
82    // TODO: re-enable this lint after justifying unsafe blocks
83    // clippy::undocumented_unsafe_blocks,
84    rustdoc::broken_intra_doc_links,
85    rustdoc::missing_crate_level_docs
86)]
87#![forbid(unsafe_op_in_unsafe_fn)]
88
89mod buffer;
90mod concurrency;
91mod endpoints;
92mod error;
93mod flexible;
94mod flexible_result;
95mod framework_error;
96#[cfg(feature = "fuchsia")]
97pub mod fuchsia;
98pub mod mpsc;
99mod service;
100#[cfg(test)]
101mod testing;
102mod transport;
103mod wire;
104
105pub use self::buffer::*;
106pub use self::endpoints::*;
107pub use self::error::*;
108pub use self::flexible::*;
109pub use self::flexible_result::*;
110pub use self::framework_error::*;
111pub use self::service::*;
112pub use self::transport::*;
113pub use self::wire::*;
fidl_next_protocol/lib.rs

fidl_next_protocol/
lib.rs
