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//! [`Client`]s and [`Server`]s are constructed from a transport, and can be
44//! `run` with a corresponding [`ClientHandler`] or [`ServerHandler`]. The
45//! client or server will then run its event loop to receive data through the
46//! transport. Clients use the handler to handle incoming events, and
47//! coordinate with any [`ClientSender`]s to route two-way method responses to
48//! waiting futures. Servers use the handler to handle incoming one-way and
49//! two-way method requests, but do not generally coordinate with their
50//! associated [`ServerSender`]s.
51//!
52//! [`ClientSender`]s and [`ServerSender`]s implement `Clone`, and should be
53//! cloned to send from multiple locations.
54
55#![deny(
56    future_incompatible,
57    missing_docs,
58    nonstandard_style,
59    unused,
60    warnings,
61    clippy::all,
62    clippy::alloc_instead_of_core,
63    clippy::missing_safety_doc,
64    clippy::std_instead_of_core,
65    // TODO: re-enable this lint after justifying unsafe blocks
66    // clippy::undocumented_unsafe_blocks,
67    rustdoc::broken_intra_doc_links,
68    rustdoc::missing_crate_level_docs
69)]
70#![forbid(unsafe_op_in_unsafe_fn)]
71
72mod buffer;
73mod concurrency;
74mod endpoints;
75mod error;
76mod flexible;
77mod flexible_result;
78mod framework_error;
79#[cfg(feature = "fuchsia")]
80pub mod fuchsia;
81pub mod mpsc;
82mod service;
83#[cfg(test)]
84mod testing;
85mod transport;
86mod wire;
87
88pub use self::buffer::*;
89pub use self::endpoints::*;
90pub use self::error::*;
91pub use self::flexible::*;
92pub use self::flexible_result::*;
93pub use self::framework_error::*;
94pub use self::service::*;
95pub use self::transport::*;
96pub use self::wire::*;
fidl_next_protocol/lib.rs

fidl_next_protocol/
lib.rs
