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. These types and
8//! traits are all "untyped" - that is, they do not know about the specific types of the FIDL
9//! messages being sent and received. They only deal with protocol-layer semantics: requests and
10//! responses, clients and servers, and transports.
11//!
12//! ## Transports
13//!
14//! This crate uses "transport" to refer to the specific object which moves bytes and handles from a
15//! sender to a receiver. For example, this crate may refer to a channel, socket, file, or other
16//! byte source/sink as a "transport". This differs from the `@transport(..)` annotation in the FIDL
17//! language, which can be added to protocols.
18//!
19//! FIDL transports implement the [`Transport`] trait. This trait defines several key properties:
20//!
21//! - The associated [`Sender`](Transport::Sender) and [`Receiver`](Transport::Receiver) types.
22//! - The buffer types for sending and receiving data.
23//! - The `async` methods for sending and receiving data with those buffers.
24//!
25//! All types in the protocol layer are generic over the transport, making it easy to add support
26//! for new types of transports.
27//!
28//! By default, both sending and receiving data with a transport are asynchronous operations.
29//! However, transports may support synchronous send operations by implementing the
30//! [`NonBlockingTransport`] trait. This trait allows users to replace `.await`-ing a send operation
31//! with [`.send_immediately()`](NonBlockingTransport::send_immediately), which synchronously
32//! completes the send future.
33//!
34//! This crate provides an implementation of `Transport` for Fuchsia channels.
35//!
36//! ## Clients and servers
37//!
38//! [`Client`]s and [`Server`]s are constructed from a transport, and can be `run` with a
39//! corresponding [`ClientHandler`] or [`ServerHandler`]. The client or server will then run its
40//! event loop to receive data through the transport. Clients use the handler to handle incoming
41//! events, and communicate with any [`ClientSender`]s to route two-way method responses to waiting
42//! futures. Servers use the handler to handle incoming one-way and two-way method requests, but do
43//! not generally communicate with its associated [`ServerSender`]s.
44//!
45//! [`ClientSender`]s and [`ServerSender`]s generally implement `Clone`, and should be cloned to
46//! send from multiple locations.
47
48#![deny(
49    future_incompatible,
50    missing_docs,
51    nonstandard_style,
52    unused,
53    warnings,
54    clippy::all,
55    clippy::alloc_instead_of_core,
56    clippy::missing_safety_doc,
57    clippy::std_instead_of_core,
58    // TODO: re-enable this lint after justifying unsafe blocks
59    // clippy::undocumented_unsafe_blocks,
60    rustdoc::broken_intra_doc_links,
61    rustdoc::missing_crate_level_docs
62)]
63#![forbid(unsafe_op_in_unsafe_fn)]
64
65mod buffer;
66mod client;
67mod error;
68mod flexible;
69mod flexible_result;
70mod framework_error;
71#[cfg(feature = "fuchsia")]
72pub mod fuchsia;
73mod lockers;
74pub mod mpsc;
75mod server;
76mod service;
77#[cfg(test)]
78mod testing;
79mod transport;
80mod wire;
81
82pub use self::buffer::*;
83pub use self::client::*;
84pub use self::error::*;
85pub use self::flexible::*;
86pub use self::flexible_result::*;
87pub use self::framework_error::*;
88pub use self::server::*;
89pub use self::service::*;
90pub use self::transport::*;
91pub use self::wire::*;
fidl_next_protocol/lib.rs

fidl_next_protocol/
lib.rs
