| # Rust bindings | |
| ## Generating FIDL Rust crates | |
| A FIDL Rust crate can be generated from a FIDL library in two ways: | |
| 1. Manually, using the | |
| [standard FIDL toolchain](/docs/development/languages/fidl/guides/cli.md). | |
| 2. Automatically, | |
| [using the Fuchsia build system](/docs/development/languages/rust/fidl_crates.md) | |
| (which under the hood uses the standard FIDL toolchain). This option is only | |
| available within the Fuchsia source tree. | |
| ## Libraries {#libraries} | |
| A FIDL `library` maps to a Rust library crate named `fidl_`, followed by the | |
| full library path with underscores instead of dots. | |
| For example, given the `library` declaration: | |
| ```fidl | |
| library fuchsia.examples; | |
| ``` | |
| The corresponding FIDL crate is named `fidl_fuchsia_examples`: | |
| ```rust | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/fidl_crates/src/main.rs" region_tag="import" adjust_indentation="auto" %} | |
| ``` | |
| ## Traits {#traits} | |
| Some methods and constants in FIDL Rust crates are provided by implementing | |
| traits from the [FIDL runtime crate](/src/lib/fidl/rust/fidl/). To access them, | |
| you must import the corresponding traits. The easiest way to do this is to | |
| import them all at once from the prelude module: | |
| ```rust | |
| use fidl::prelude::*; | |
| ``` | |
| The prelude re-exports traits using the `as _` syntax, so the glob import only | |
| brings traits into scope for resolving methods and constants. It does not import | |
| the trait names themselves. | |
| ## Constants {#constants} | |
| Given the [constants][lang-constants]: | |
| ```fidl | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/fuchsia.examples/types.test.fidl" region_tag="consts" %} | |
| ``` | |
| The FIDL toolchain generates the following constants: | |
| * `pub const BOARD_SIZE: u8` | |
| * `pub const NAME: &str` | |
| The correspondence between FIDL primitive types and Rust types is outlined in | |
| [built-in types](#builtins). | |
| ## Fields | |
| This section describes how the FIDL toolchain converts FIDL types to native | |
| types in Rust. These types can appear as members in an aggregate type or as | |
| parameters to a protocol method. | |
| ### Built-in types {#builtins} | |
| Note: In Rust, the equivalent type for a optional FIDL type `T:optional` is an | |
| `Option` of the Rust type for `T`. These are not explicitly listed in the table | |
| below. | |
| In following table, when both an "owned" and "borrowed" variant are specified, | |
| the "owned" type refers to the type that would appear in an aggregate type (e.g. | |
| as the type of a struct field or vector element), and the "borrowed" type refers | |
| to the type that would appear if it were used as a protocol method parameter | |
| (from the client's perspective) or response tuple value (from the server's | |
| perspective). The distinction between owned and borrowed exists in order to take | |
| advantage of Rust’s ownership model. When making a request with a parameter of | |
| type `T`, the [proxied function call](#protocols-client) does not need to take | |
| ownership of `T` so the FIDL toolchain needs to generate a borrowed version of | |
| `T`. Borrowed versions often use `&mut` since the type `T` may contain handles, | |
| in which case the FIDL bindings zero out the handles when encoding, which | |
| modifies the input. Using `&mut` instead of taking ownership allows callers to | |
| reuse the input value if it does not contain handles. | |
| |FIDL Type|Rust Type| | |
| |--- |--- | | |
| |`bool`|`bool`| | |
| |`int8`|`i8`| | |
| |`int16`|`i16`| | |
| |`int32`|`i32`| | |
| |`int64`|`i64`| | |
| |`uint8`|`u8`| | |
| |`uint16`|`u16`| | |
| |`uint32`|`u32`| | |
| |`uint64`|`u64`| | |
| |`float32`|`f32`| | |
| |`float64`|`f64`| | |
| |`array<T, N>`|`&mut [T; N]` *(borrowed)*<br> `[T, N]` *(owned)*| | |
| |`vector<T>:N`|`&[T]` *(borrowed, when T is a numeric primitive)*<br> `&mut dyn ExactSizeIterator` *(borrowed)*<br>`Vec` *(owned)*| | |
| |`string`|`&str` *(borrowed)*<br>`String` *(owned)*| | |
| |`server_end:P`|`fidl::endpoints::ServerEnd<PMarker>`, *where `PMarker` is the [marker type](#protocols) for this protocol.*| | |
| |`client_end:P`|`fidl::endpoints::ClientEnd<PMarker>` *where `PMarker` is the [marker type](#protocols) for this protocol.*| | |
| |`zx.Handle`|`fidl::Handle`| | |
| |`zx.Handle:S`|The corresponding handle type is used. For example,`fidl::Channel` or `fidl::Vmo`| | |
| #### User defined types {#user-defined-types} | |
| Bits, enums, and tables are always referred to using their generated type `T`. | |
| structs and unions can be either required or optional, and used in an owned | |
| context or borrowed context, which means that there are four possible equivalent | |
| Rust types. For a given `struct T` or `union T`, the types are as follows: | |
| ||owned|borrowed| | |
| |--- |--- |--- | | |
| |required|`T`|`&mut T`| | |
| |optional|`Option<T>`|`Option<&mut T>`| | |
| ### Request, response, and event parameters {#request-response-event-parameters} | |
| When FIDL needs to generate a single Rust type representing the parameters to a | |
| request, response, or event, such as for [result types](#protocols-client), it | |
| uses the following rules: | |
| * Multiple parameters are represented as a tuple of the parameter types. | |
| * A single parameter is represented just using the parameter's type. | |
| * An empty set of parameters is represented using the unit type `()`. | |
| ## Types {#types} | |
| ### Bits {#types-bits} | |
| Given the [bits][lang-bits] definition: | |
| ```fidl | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/fuchsia.examples/types.test.fidl" region_tag="bits" %} | |
| ``` | |
| The FIDL toolchain generates a set of | |
| [`bitflags`](https://fuchsia-docs.firebaseapp.com/rust/bitflags/) called | |
| `FileMode` with flags `FileMode::READ`, `FileMode::WRITE`, and | |
| `FileMode::EXECUTE`. | |
| The `bitflags` struct also provides the following methods: | |
| * `get_unknown_bits(&self) -> u16`: Returns a primitive value containing only | |
| the unknown members from this bits value. For [strict][lang-flexible] bits, it | |
| is marked `#[deprecated]` and always returns 0. | |
| * `has_unknown_bits(&self) -> bool`: Returns whether this value contains any | |
| unknown bits. For [strict][lang-flexible] bits, it is marked `#[deprecated]` | |
| and always returns `false`. | |
| The generated `FileMode` struct always has the complete set of [`#[derive]` | |
| rules](#derives). | |
| Example usage: | |
| ```rust | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/fidl_crates/src/main.rs" region_tag="bits" adjust_indentation="auto" %} | |
| ``` | |
| ### Enums {#types-enums} | |
| Given the [enum][lang-enums] definition: | |
| ```fidl | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/fuchsia.examples/types.test.fidl" region_tag="enums" %} | |
| ``` | |
| The FIDL toolchain generates a Rust `enum` using the specified underlying type, | |
| or `u32` if none is specified: | |
| ```rust | |
| #[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)] | |
| #[repr(u32)] | |
| pub enum LocationType { | |
| Museum = 1, | |
| Airport = 2, | |
| Restaurant = 3, | |
| } | |
| ``` | |
| With the following methods: | |
| * `from_primitive(prim: u32) -> Option<Self>`: Returns `Some` of the enum | |
| variant corresponding to the discriminant value if any, and `None` otherwise. | |
| * `into_primitive(&self) -> u32`: Returns the underlying discriminant value. | |
| * `is_unknown(&self) -> bool`: Returns whether this enum is unknown. For | |
| [strict][lang-flexible] types, it is marked `#[deprecated]` and always returns | |
| `false`. | |
| If `LocationType` is [flexible][lang-flexible], it will have the following | |
| additional methods: | |
| * `from_primitive_allow_unknown(prim: u32) -> Self`: Create an instance of the | |
| enum from a primitive value. | |
| * `unknown() -> Self`: Return a placeholder unknown enum value. If the enum | |
| contains a member marked with [`[Unknown]`][unknown-attr], then the value | |
| returned by this method contains the value of specified unknown member. | |
| The generated `LocationType` `enum` always has the complete set of [`#[derive]` | |
| rules](#derives). | |
| Example usage: | |
| ```rust | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/fidl_crates/src/main.rs" region_tag="enums_init" adjust_indentation="auto" %} | |
| ``` | |
| To provide source-compatibility, [flexible][lang-flexible] enums have an unknown | |
| macro that should be used to match against unknown members instead of the `_` | |
| pattern. For example, see the use of the `LocationTypeUnknown!()` macro: | |
| ```rust | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/fidl_crates/src/main.rs" region_tag="enums_flexible_match" adjust_indentation="auto" %} | |
| ``` | |
| The unknown macro acts the same as a `_` pattern, but it can be configured to | |
| expand to an exhaustive match. This is useful for discovering missing cases. | |
| ### Structs {#types-structs} | |
| Given the [struct][lang-structs] declaration: | |
| ```fidl | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/fuchsia.examples/types.test.fidl" region_tag="structs" %} | |
| ``` | |
| The FIDL toolchain generates a Rust `struct`: | |
| ```rust | |
| #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)] | |
| pub struct Color { | |
| pub id: u32, | |
| pub name: String, | |
| } | |
| ``` | |
| Note: The Rust bindings do not support default values for FIDL struct members, | |
| so the default value for `name` does not affect the generated Rust `struct`. | |
| The generated `Color` `struct` follows the [`#[derive]` rules](#derives). | |
| Example usage: | |
| ```rust | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/fidl_crates/src/main.rs" region_tag="structs" adjust_indentation="auto" %} | |
| ``` | |
| ### Unions {#types-unions} | |
| Given the [union][lang-unions] definition: | |
| ```fidl | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/fuchsia.examples/types.test.fidl" region_tag="unions" %} | |
| ``` | |
| The FIDL toolchain generates a Rust `enum`: | |
| ```rust | |
| #[derive(Debug, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)] | |
| pub enum JsonValue { | |
| IntValue(i32), | |
| StringValue(String), | |
| } | |
| ``` | |
| With the following methods: | |
| * `ordinal(&self) -> u64`: Returns the ordinal of the active variant, as | |
| specified in the FIDL type. | |
| * `is_unknown(&self) -> bool`: Returns whether this union is unknown. Always | |
| returns `false` for non-flexible union types. For [strict][lang-flexible] | |
| types, it is marked `#[deprecated]` and always returns `false`. | |
| If `JsonValue` is [flexible][lang-flexible], it will have the following | |
| additional methods: | |
| * `unknown_variant_for_testing() -> Self`: Create an unknown union value. This | |
| should only be used in tests. | |
| The generated `JsonValue` `enum` follows the [`#[derive]` rules](#derives). | |
| Example usage: | |
| ```rust | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/fidl_crates/src/main.rs" region_tag="unions_init" adjust_indentation="auto" %} | |
| ``` | |
| #### Flexible unions and unknown variants | |
| [Flexible][lang-flexible] unions have an extra variant generated to represent | |
| the unknown case. This variant is considered private and should not be | |
| referenced directly. | |
| To provide source-compatibility, [flexible][lang-flexible] unions have an | |
| unknown macro that should be used to match against unknown members instead of | |
| the `_` pattern. For example, see the use of the `JsonValueUnknown!()` macro: | |
| ```rust | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/fidl_crates/src/main.rs" region_tag="unions_flexible_match" adjust_indentation="auto" %} | |
| ``` | |
| The unknown macro acts the same as a `_` pattern, but it can be configured to | |
| expand to an exhaustive match. This is useful for discovering missing cases. | |
| When a FIDL message containing a union with an unknown variant is decoded into | |
| `JsonValue`, `JsonValue::is_unknown()` returns true. | |
| Flexible unions have a custom `PartialEq` to make unknown variants behave like | |
| NaN: they do not compare equal to anything, including themselves. See [RFC-0137: | |
| Discard unknown data in FIDL][rfc-0137] for background on this decision. | |
| [Strict][lang-flexible] unions fail when decoding an unknown variant. | |
| [Flexible][lang-flexible] unions succeed when decoding an unknown variant, but | |
| fail when re-encoding it. | |
| ### Tables {#types-tables} | |
| Given the [table][lang-tables] definition: | |
| ```fidl | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/fuchsia.examples/types.test.fidl" region_tag="tables" %} | |
| ``` | |
| The FIDL toolchain generates a `struct` `User` with optional members: | |
| ```rust | |
| #[derive(Debug, PartialEq)] | |
| pub struct User { | |
| pub age: Option<u8>, | |
| pub name: Option<String>, | |
| #[doc(hidden)] | |
| pub __source_breaking: fidl::marker::SourceBreaking, | |
| } | |
| ``` | |
| If any unknown fields are encountered during decoding, they are discarded. There | |
| is no way to access them or determine if they occurred. | |
| The `__source_breaking` member signals that initializing the table exhaustively | |
| causes API breakage when new fields are added. Instead, you should use the | |
| struct update syntax to fill in unspecified fields with `Default::default()`. | |
| For example: | |
| ```rust | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/fidl_crates/src/main.rs" region_tag="tables_init" adjust_indentation="auto" %} | |
| ``` | |
| Similarly, tables do not permit exhaustive matching. Instead, you must use the | |
| `..` syntax to ignore unspecified fields. For example: | |
| ```rust | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/fidl_crates/src/main.rs" region_tag="tables_match" adjust_indentation="auto" %} | |
| ``` | |
| The generated `User` `struct` follows the [`#[derive]` rules](#derives). | |
| ### Inline layouts | |
| The generated Rust code uses the [the name reserved by `fidlc`][anon-names] for | |
| inline layouts. | |
| ### Derives {#derives} | |
| When the FIDL toolchain generates a new `struct` or `enum` for a FIDL type, it | |
| attempts to `derive` as many traits from a predefined list of useful traits as | |
| it can, including `Debug`, `Copy`, `Clone`, etc. The complete list of traits can | |
| be found in [Appendix A](#derived-traits). | |
| For aggregate types, such as structs, unions, and tables, the set of derives is | |
| determined by starting with the list of all possible derives and then removing | |
| some based on the fields that are transitively present in the type. For example, | |
| aggregate types that transitively contain a `vector` do not derive `Copy`, and | |
| types that my contain a `handle` (i.e. types that are not marked as | |
| [`resource`][lang-resource]) do not derive `Copy` and `Clone`. When in doubt, | |
| refer to the generated code to check which traits are derived by a specific | |
| type. See [Appendix B](#fill-derives) for implementation details. | |
| ## Protocols {#protocols} | |
| Given a [protocol][lang-protocols]: | |
| ```fidl | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/fuchsia.examples/types.test.fidl" region_tag="protocols" %} | |
| ``` | |
| Note: The `MakeMove` method above returns a bool representing success, and a | |
| optional response value. This is considered un-idiomatic, you should use an [error type](#protocols-results) | |
| instead. | |
| The main entrypoint for interacting with `TicTacToe` is the `TicTacToeMarker` | |
| struct, which contains two associated types: | |
| * `Proxy`: The associated proxy type for use with async clients. In this | |
| example, this is a generated `TicTacToeProxy` type. Synchronous clients should | |
| use `TicTacToeSynchronousProxy` directly (see | |
| [Synchronous](#protocols-client-synchronous)), which is not stored in an | |
| associated type on the `TicTacToeMarker`. | |
| * `RequestStream`: The associated [request stream](#protocol-request-stream) that servers | |
| implementing this protocol will need to handle. In this example, this is | |
| `TicTacToeRequestStream`, which is generated by FIDL. | |
| Additionally, `TicTacToeMarker` has the following associated constants from | |
| implementing `fidl::endpoints::ProtocolMarker`: | |
| * `DEBUG_NAME: &’static str`: The name of the service suitable for debug | |
| purposes. | |
| Note: To use `DEBUG_NAME` you must [import the `ProtocolMarker` trait](#traits). | |
| Other code may be generated depending on the [Protocol and method | |
| attributes](#protocol-method-attributes) applied to the protocol or its methods. | |
| ### Client {#protocols-client} | |
| #### Asynchronous {#protocols-client-asynchronous} | |
| For asynchronous clients, the FIDL toolchain generates a `TicTacToeProxy` struct | |
| with the following: | |
| Associated types: | |
| * `TicTacToeProxy::MakeMoveResponseFut`: The `Future` type for the response of a | |
| two way method. This type implements `std::future::Future<Output = | |
| Result<(bool, Option<Box<GameState>>), fidl::Error>> + Send`. | |
| Methods: | |
| * `new(channel: fidl::AsyncChannel) -> TicTacToeProxy`: Create a new proxy for | |
| `TicTacToe`. | |
| * `take_event_stream(&self) -> TicTacToeEventStream`: Get a `Stream` of events | |
| from the server end (see [Events](#protocols-events-client)). | |
| Methods from implementing `fidl::endpoints::Proxy`: | |
| * `from_channel(channel: fidl::AsyncChannel) -> TicTacToeProxy`: Same as | |
| `TicTacToeProxy::new`. | |
| * `into_channel(self) -> Result<fidl::AsyncChannel>`: Attempt to convert the | |
| proxy back into a channel. | |
| * `as_channel(&self) -> &fidl::AsyncChannel`: Get a reference to the proxy's | |
| underlying channel | |
| * `is_closed(&self) -> bool`: Check if the proxy has received the `PEER_CLOSED` | |
| signal. | |
| * `on_closed<'a>(&'a self) -> fuchsia_async::OnSignals<'a>`: Get a future that | |
| completes when the proxy receives the `PEER_CLOSED` signal. | |
| Note: To use the above methods you must [import the `Proxy` trait](#traits). | |
| Methods from implementing `TicTacToeProxyInterface`: | |
| * `start_game(&self, mut start_first: bool) -> Result<(), fidl::Error>`: Proxy | |
| method for a fire and forget protocol method. It takes as arguments the | |
| request parameters and returns an empty result. | |
| * `make_move(&self, mut row: u8, mut col: u8) -> Self::MakeMoveResponseFut`: | |
| Proxy method for a two way method. It takes as arguments the request | |
| parameters and returns a `Future` of the response. | |
| An example of setting up an asynchronous proxy is available in the | |
| [Rust tutorial][tutorial]. | |
| The `TicTacToeProxyInterface` trait can be useful for testing client code. For | |
| example, if you write a function that takes `&T` as a parameter where `T: | |
| TicTacToeProxyInterface`, you can unit test it with a fake proxy type: | |
| ```rust | |
| use futures::future::{ready, Ready}; | |
| struct FakeTicTacToeProxy { | |
| move_response: (bool, Option<Box<GameState>>), | |
| } | |
| impl TicTacToeProxyInterface for FakeTicTacToeProxy { | |
| fn start_game(&self, mut start_first: bool) -> Result<(), fidl::Error> { | |
| Ok(()) | |
| } | |
| type MakeMoveResponseFut = Ready<fidl::Result<(bool, Option<Box<GameState>>)>>; | |
| fn make_move(&self, mut row: u8, mut col: u8) -> Self::MakeMoveResponseFut { | |
| ready(self.move_response.clone()) | |
| } | |
| } | |
| ``` | |
| ##### Handle Conversions {#protocols-client-asynchronous-conversions} | |
| This flowchart illustrates the various conversions available between handle | |
| wrapper types for asynchronous clients in the Rust FIDL ecosystem. Note that | |
| dotted lines indicate fallible methods or functions. | |
| ```mermaid | |
| graph BT | |
| raw_handle[<a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/zx/sys/type.zx_handle_t.html'>zx_handle_t</a>] | |
| owned_handle[<a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/zx/struct.Handle.html'>zx::Handle</a>] | |
| owned_channel[<a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/zx/struct.Channel.html'>zx::Channel</a>] | |
| client_end[<a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl/endpoints/struct.ClientEnd.html'>ClientEnd<TicTacToeMarker></a>] | |
| async_channel[<a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fuchsia_async/struct.Channel.html'>AsyncChannel</a>] | |
| proxy[<a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl_fuchsia_examples/struct.TicTacToeProxy.html'><b>TicTacToeProxy</b></a>] | |
| raw_handle-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/zx/struct.Handle.html#method.from_raw'>zx::Handle::from_raw()</a> -->owned_handle | |
| owned_handle-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/zx/trait.HandleBased.html#method.into_raw'>.into_raw()</a> -->raw_handle | |
| owned_handle-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/zx/struct.Channel.html#impl-From%3CHandle%3E-for-Channel'>zx::Channel::from()</a> -->owned_channel | |
| owned_channel-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/zx/struct.Handle.html#impl-From%3CChannel%3E-for-Handle'>zx::Handle::from()</a> -->owned_handle | |
| owned_channel-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fuchsia_async/struct.Channel.html#method.from_channel'>AsyncChannel::from_channel()</a> -->async_channel | |
| async_channel-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fuchsia_async/struct.Channel.html#method.into_zx_channel'>.into_zx_channel()</a> -->owned_channel | |
| owned_channel-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl/endpoints/struct.ClientEnd.html#impl-From%3CChannel%3E-for-ClientEnd%3CT%3E'>ClientEnd::from()</a> -->client_end | |
| client_end-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl/endpoints/struct.ClientEnd.html#method.into_proxy'>.into_proxy()</a> -->proxy | |
| client_end-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl/endpoints/struct.ClientEnd.html#method.into_channel'>.into_channel()</a> -->owned_channel | |
| async_channel-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl/endpoints/trait.Proxy.html#tymethod.from_channel'>Proxy::from_channel()</a> -->proxy | |
| proxy-. "<a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl/endpoints/trait.Proxy.html#method.into_client_end'>.into_client_end()</a>" .-> client_end | |
| proxy-. "<a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl/endpoints/trait.Proxy.html#tymethod.into_channel'>.into_channel()</a>" .->async_channel | |
| %% following edges help disambiguate clientend and proxy in layout | |
| client_end ~~~ async_channel | |
| async_channel ~~~ client_end | |
| client_end ~~~ owned_channel | |
| owned_channel ~~~ client_end | |
| ``` | |
| #### Synchronous {#protocols-client-synchronous} | |
| For synchronous clients of the `TicTacToe` protocol, the FIDL toolchain | |
| generates a `TicTacToeSynchronousProxy` struct with the following methods: | |
| * `new(channel: fidl::Channel) -> TicTacToeSynchronousProxy`: Returns a new | |
| synchronous proxy over the client end of a channel. The server end is assumed | |
| to implement the `TicTacToe` protocol. | |
| * `into_channel(self) -> fidl::Channel`: Convert the proxy back into a channel. | |
| * `start_game(&self, mut a: i64) -> Result<(), fidl::Error>`: Proxy method | |
| for a fire and forget method: it takes the request parameters as arguments and | |
| returns an empty result. | |
| * `make_move(&self, mut row: u8, mut col: u8, __deadline: zx::MonotonicInstant) -> | |
| Result<(bool, Option<Box<GameState>>), fidl::Error>`: Proxy method for a two | |
| way method. It takes the request parameters as arguments followed by a | |
| deadline parameter, which dictates how long the method call will wait for a | |
| response (or `zx::MonotonicInstant::INFINITE` to block indefinitely). It returns a | |
| `Result` of the [response parameters](#request-response-event-parameters). | |
| * `wait_for_event(&self, deadline: zx::MonotonicInstant) -> | |
| Result<TicTacToeEvent, fidl::Error>`: Blocks until an event is received or the | |
| deadline expires (use `zx::MonotonicInstant::INFINITE` to block indefinitely). It returns | |
| a `Result` of the [`TicTacToeEvent` enum](#protocols-events-client). | |
| An example of setting up a synchronous proxy is available in the | |
| [Rust tutorial][tutorial]. | |
| ##### Handle Conversions {#protocols-client-synchronous-conversions} | |
| This flowchart illustrates the various conversions available between handle | |
| wrapper types for synchronous clients in the Rust FIDL ecosystem. | |
| ```mermaid | |
| graph BT | |
| raw_handle[<a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/zx/sys/type.zx_handle_t.html'>zx_handle_t</a>] | |
| owned_handle[<a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/zx/struct.Handle.html'>zx::Handle</a>] | |
| owned_channel[<a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/zx/struct.Channel.html'>zx::Channel</a>] | |
| client_end[<a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl/endpoints/struct.ClientEnd.html'>fidl::endpoints::ClientEnd<TicTacToeMarker></a>] | |
| sync_proxy[<a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl_fuchsia_examples/struct.TicTacToeSynchronousProxy.html'><b>TicTacToeSynchronousProxy</b></a>] | |
| raw_handle-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/zx/struct.Handle.html#method.from_raw'>zx::Handle::from_raw()</a> -->owned_handle | |
| owned_handle-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/zx/trait.HandleBased.html#method.into_raw'>.into_raw()</a> -->raw_handle | |
| owned_handle-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/zx/struct.Channel.html#impl-From%3CHandle%3E-for-Channel'>zx::Channel::from()</a> -->owned_channel | |
| owned_channel-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/zx/struct.Handle.html#impl-From%3CChannel%3E-for-Handle'>zx::Handle::from()</a> -->owned_handle | |
| owned_channel-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl/endpoints/struct.ClientEnd.html#impl-From%3CChannel%3E-for-ClientEnd%3CT%3E'>ClientEnd::from()</a> -->client_end | |
| client_end-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl/endpoints/struct.ClientEnd.html#method.into_channel'>.into_channel()</a> -->owned_channel | |
| client_end-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl/endpoints/struct.ClientEnd.html#method.into_sync_proxy'>.into_sync_proxy()</a> -->sync_proxy | |
| sync_proxy-- "<a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl/endpoints/trait.SynchronousProxy.html#tymethod.into_channel'>.into_channel()</a>" -->owned_channel | |
| owned_channel-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl/endpoints/trait.SynchronousProxy.html#tymethod.from_channel'>SynchronousProxy::from_channel()</a> -->sync_proxy | |
| ``` | |
| ### Server {#protocols-server} | |
| #### Protocol request stream {#protocol-request-stream} | |
| To represent the stream of incoming requests to a server, the FIDL toolchain | |
| generates a `TicTacToeRequestStream` type that implements `futures::Stream<Item | |
| = Result<TicTacToeRequest, fidl::Error>>` as well as | |
| `fidl::endpoints::RequestStream`. Each protocol has a corresponding request | |
| stream type. | |
| ##### Handle Conversions {#protocol-request-stream-conversions} | |
| This flowchart illustrates the various conversions available between handle | |
| wrapper types for asynchronous servers in the Rust FIDL ecosystem. | |
| ```mermaid | |
| graph BT | |
| raw_handle[<a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/zx/sys/type.zx_handle_t.html'>zx_handle_t</a>] | |
| owned_handle[<a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/zx/struct.Handle.html'>zx::Handle</a>] | |
| owned_channel[<a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/zx/struct.Channel.html'>zx::Channel</a>] | |
| server_end[<a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl/endpoints/struct.ServerEnd.html'>ServerEnd<TicTacToeMarker></a>] | |
| async_channel[<a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fuchsia_async/struct.Channel.html'>AsyncChannel</a>] | |
| serve_inner[<a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl/server/struct.ServeInner.html'>ServeInner</a>] | |
| request_stream[<a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl_fuchsia_examples/struct.TicTacToeRequestStream.html'><b>TicTacToeRequestStream</b></a>] | |
| raw_handle-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/zx/struct.Handle.html#method.from_raw'>zx::Handle::from_raw()</a> -->owned_handle | |
| owned_handle-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/zx/trait.HandleBased.html#method.into_raw'>.into_raw()</a> -->raw_handle | |
| owned_handle-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/zx/struct.Channel.html#impl-From%3CHandle%3E-for-Channel'>zx::Channel::from()</a> -->owned_channel | |
| owned_channel-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/zx/struct.Handle.html#impl-From%3CChannel%3E-for-Handle'>zx::Handle::from()</a> -->owned_handle | |
| owned_channel-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fuchsia_async/struct.Channel.html#method.from_channel'>AsyncChannel::from_channel()</a> -->async_channel | |
| async_channel-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fuchsia_async/struct.Channel.html#method.into_zx_channel'>.into_zx_channel()</a> -->owned_channel | |
| owned_channel-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl/endpoints/struct.ServerEnd.html#impl-From%3CChannel%3E-for-ServerEnd%3CT%3E'>ServerEnd::from()</a> -->server_end | |
| server_end-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl/endpoints/struct.ServerEnd.html#method.into_channel'>.into_channel()</a> -->owned_channel | |
| async_channel-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl/server/struct.ServeInner.html#method.new'>ServeInner::new()</a> -->serve_inner | |
| serve_inner-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl/server/struct.ServeInner.html#method.into_channel'>.into_channel()</a> -->async_channel | |
| serve_inner-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl/endpoints/trait.RequestStream.html#tymethod.from_inner'>RequestStream::from_inner()</a> -->request_stream | |
| server_end-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl/endpoints/struct.ServerEnd.html#method.into_stream'>.into_stream()</a> -->request_stream | |
| request_stream-- "<a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl/endpoints/trait.RequestStream.html#tymethod.into_inner'>.into_inner()</a>" -->serve_inner | |
| async_channel-- <a target="_blank" href='https://fuchsia-docs.firebaseapp.com/rust/fidl/endpoints/trait.RequestStream.html#tymethod.from_channel'>RequestStream::from_channel()</a> -->request_stream | |
| ``` | |
| #### Request enum {#request-enum} | |
| `TicTacToeRequest` is an enum representing the possible requests of the | |
| `TicTacToe` protocol. It has the following variants: | |
| * `StartGame { start_first: bool, control_handle: TicTacToeControlHandle }`: A | |
| fire and forget request, which contains the request parameters and a [control handle](#protocol-control-handle). | |
| * `MakeMove { row: u8, col: u8, responder: TicTacToeMakeMoveResponder }`: A two | |
| way method request, which contains the request parameters and a | |
| [responder](#request-responder). | |
| One such enum is generated for each protocol. | |
| #### Request responder {#request-responder} | |
| Each two way method has a corresponding generated responder type, which the | |
| server uses to respond to a request. In this example, which only has one two way | |
| method, the FIDL toolchain generates `TicTacToeMakeMoveResponder`, which | |
| provides the following methods: | |
| * `send(self, mut success: bool, mut new_state: Option<&mut GameState>) -> | |
| Result<(), fidl::Error>`: Sends a response. | |
| * `send_no_shutdown_on_err(self, mut success: bool, mut new_state: Option<&mut | |
| GameState>) -> Result<(), fidl::Error>`: Similar to `send` but does not shut | |
| down the channel if an error occurs. | |
| * `control_handle(&self) -> &TicTacToeControlHandle`: Get the underlying | |
| [control handle](#protocol-control-handle). | |
| * `drop_without_shutdown(mut self)`: Drop the Responder without shutting down | |
| the channel. | |
| #### Protocol control handle {#protocol-control-handle} | |
| The FIDL toolchain generates `TicTacToeControlHandle` to encapsulate the client | |
| endpoint of the `TicTacToe` protocol on the server side. It contains the | |
| following methods: | |
| * `shutdown(&self)`: Shut down the channel. | |
| * `shutdown_with_epitaph(&self, status: zx_status::Status)`: Send an epitaph and | |
| then shut down the channel. | |
| * `send_on_opponent_move(&self, mut new_state: &mut GameState) -> Result<(), | |
| fidl::Error>`: Proxy method for an event, which takes as arguments the event’s | |
| parameters and returns an empty result (see | |
| [Events](#protocols-events-server)). | |
| ### Events {#protocols-events} | |
| #### Client {#protocols-events-client} | |
| For receiving events on the asynchronous client, the FIDL toolchain generates a | |
| `TicTacToeEventStream`, which can be obtained using the `take_event_stream()` | |
| method on the [`TicTacToeProxy`](#protocols-client-asynchronous). | |
| `TicTacToeEventStream` implements `futures::Stream<Item = Result<TicTacToeEvent, | |
| fidl::Error>>`. | |
| For receiving events on the synchronous client, the FIDL toolchain generates a | |
| `wait_for_event` method on the | |
| [`TicTacToeSynchronousProxy`](#protocols-client-synchronous) that returns a | |
| `TicTacToeEvent`. | |
| `TicTacToeEvent` is an enum representing the possible events. It has the | |
| following variants: | |
| * `OnOpponentMove { new_state: GameState }`: Discriminant for the | |
| `TicTacToeEvent` event. | |
| And provides the following methods: | |
| * `into_on_opponent_move(self) -> Option<GameState>`: Return `Some` of the | |
| [parameters](#request-response-event-parameters) of the event, or `None` if | |
| the variant does not match the method call. | |
| #### Server {#protocols-events-server} | |
| Servers can send events by using the [control handle](#protocol-control-handle) | |
| corresponding to the protocol. The control handle can be obtained through a | |
| `TicTacToeRequest` received from the client. For fire and forget methods, the | |
| control handle is available through the `control_handle` field, and for two way | |
| methods, it is available through the `control_handle()` method on the responder. | |
| A control handle for a protocol can also be obtained through the corresponding | |
| request stream (in this example, `TicTacToeRequestStream`), since it implements | |
| `fidl::endpoints::RequestStream`. | |
| ### Results {#protocols-results} | |
| For a method with an error type: | |
| ```fidl | |
| protocol TicTacToe { | |
| MakeMove(struct { | |
| row uint8; | |
| col uint8; | |
| }) -> (struct { | |
| new_state GameState; | |
| }) error MoveError; | |
| }; | |
| ``` | |
| The FIDL toolchain generates a public `TicTacToeMakeMoveResult` type alias for | |
| `std::result::Result<GameState, MoveError>`. The rest of the bindings code for | |
| this method is generated as if it has a single response parameter `result` of | |
| type `TicTacToeMakeMoveResult`. The type used for a successful result follows | |
| the [parameter type conversion rules](#request-response-event-parameters). | |
| ### Unknown interaction handling {#unknown-interaction-handling} | |
| #### Server-side | |
| When a protocol is declared as `open` or `ajar`, the generated [request | |
| enum](#request-enum) will have an additional variant called | |
| `_UnknownMethod` which has these fields: | |
| ```rust | |
| #[non_exhaustive] | |
| _UnknownMethod { | |
| /// Ordinal of the method that was called. | |
| ordinal: u64, | |
| /// Control handle for the protocol. | |
| control_handle: TicTacToeControlHandle, | |
| /// Enum indicating whether the method is a one-way method or a two way | |
| /// method. This field only exists if the protocol is open. | |
| method_type: fidl::MethodType, | |
| } | |
| ``` | |
| `MethodType` is an enum with two unit variants, `OneWay` and `TwoWay`, | |
| which tells which kind of method was called. | |
| Whenever the server receives a flexible unknown event, the request stream will | |
| emit this variant of the request enum. | |
| #### Client-side | |
| There is no way for the client to tell if a `flexible` one-way method was known | |
| to the server or not. For `flexible` two-way methods, if the method is not known | |
| to the server, the client will receive an `Err` result with a value of | |
| `fidl::Error::UnsupportedMethod`. The `UnsupportedMethod` error is only possible | |
| for a flexible two-way method. | |
| Aside from the possibility of getting an `UnsupportedMethod` error, there are no | |
| API differences between `strict` and `flexible` methods on the client. | |
| For `open` and `ajar` protocols, the generated [event | |
| enum](#protocols-events-client) will have an additional variant called | |
| `_UnknownEvent` which has these fields: | |
| ```rust | |
| #[non_exhaustive] | |
| _UnknownEvent { | |
| /// Ordinal of the event that was sent. | |
| ordinal: u64, | |
| } | |
| ``` | |
| Whenever the client receives an unknown event, the client event stream will emit | |
| this variant of the event enum. | |
| ### Protocol composition {#protocol-composition} | |
| FIDL does not have a concept of inheritance, and generates full code as | |
| described above for all [composed protocols][lang-protocol-composition]. In | |
| other words, the code generated for the following: | |
| ```fidl | |
| protocol A { | |
| Foo(); | |
| }; | |
| protocol B { | |
| compose A; | |
| Bar(); | |
| }; | |
| ``` | |
| Is the same as the following code: | |
| ```fidl | |
| protocol A { | |
| Foo(); | |
| }; | |
| protocol B { | |
| Foo(); | |
| Bar(); | |
| }; | |
| ``` | |
| ### Protocol and method attributes {#protocol-method-attributes} | |
| #### Transitional | |
| The `@transitional` attribute only affects the `ProxyInterface` trait, which is | |
| sometimes used in test code. For non-test code, protocols can be transitioned on | |
| the server side by having request handlers temporarily use a catch-all match arm | |
| in the `Request` handler. Client code does not need to be soft transitioned | |
| since the generated proxy will always implement all methods. | |
| For methods annotated with the `@transitional` attribute, the `ProxyInterface` | |
| trait for [asynchronous clients](#protocols-client-asynchronous}) provides | |
| default implementations that call `unimplemented!()`. As noted earlier, this has | |
| no effect on the `Proxy` type, which always implements all the trait's methods. | |
| However, it can help for soft transitions when the `ProxyInterface` trait is | |
| used for fake proxies in client-side unit tests. | |
| #### Discoverable | |
| For protocols annotated with the `@discoverable` attribute, the Marker type | |
| additionally implements the `fidl::endpoints::DiscoverableProtocolMarker` trait. | |
| This provides the `PROTOCOL_NAME` associated constant. | |
| ## Explicit encoding and decoding {#encoding-decoding} | |
| FIDL messages are automatically encoded when they are sent and decoded when they | |
| are received. You can also encode and decode explicitly, for example to persist | |
| FIDL data to a file. Following [RFC-0120: Standalone use of the FIDL wire | |
| format][rfc-0120], the bindings offer a [persistence API](#persistence) and a | |
| [standalone API](#standalone). | |
| ### Persistence {#persistence} | |
| The recommended way to explicitly encode and decode is to use [`persist`] and | |
| [`unpersist`]. This works for [non-resource][lang-resource] structs, tables, and | |
| unions. | |
| For example, you can persist a [`Color` struct](#types-structs): | |
| ```rust | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/persistence/src/lib.rs" region_tag="persist" adjust_indentation="auto" %} | |
| ``` | |
| And then unpersist it later: | |
| ```rust | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/persistence/src/lib.rs" region_tag="unpersist" adjust_indentation="auto" %} | |
| ``` | |
| ### Standalone {#standalone} | |
| For advanced use cases where the [persistence API](#persistence) is not | |
| sufficient, you can use the standalone encoding and decoding API. This works for | |
| all structs, tables, and unions. There are two sets of functions: one for | |
| [value][lang-resource] types, and one for [resource][lang-resource] types. | |
| For example, since [`JsonValue` union](#types-unions) is a value type, we encode | |
| it using [`standalone_encode_value`]: | |
| ```rust | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/persistence/src/lib.rs" region_tag="standalone_encode_value" adjust_indentation="auto" %} | |
| ``` | |
| This returns a vector of bytes and an opaque object that stores wire format | |
| metadata. To decode, pass both values to [`standalone_decode_value`]: | |
| ```rust | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/persistence/src/lib.rs" region_tag="standalone_decode_value" adjust_indentation="auto" %} | |
| ``` | |
| As another example, consider the struct `EventStruct`: | |
| ```fidl | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/fuchsia.examples/types.test.fidl" region_tag="resource_structs" %} | |
| ``` | |
| Since this is a resource type, we encode it using | |
| [`standalone_encode_resource`]: | |
| ```rust | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/persistence/src/lib.rs" region_tag="standalone_encode_resource" adjust_indentation="auto" %} | |
| ``` | |
| In addition to bytes and wire format metadata, this also returns a vector of | |
| [`HandleDisposition`]s. To decode, convert the handle dispositions to | |
| [`HandleInfo`]s, and then pass all three values to | |
| [`standalone_decode_resource`]: | |
| ```rust | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/persistence/src/lib.rs" region_tag="standalone_decode_resource" adjust_indentation="auto" %} | |
| ``` | |
| ## Appendix A: Derived traits {#derived-traits} | |
| ```go | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlgen_rust/codegen/ir.go" region_tag="derived_traits" adjust_indentation="auto" %} | |
| ``` | |
| ## Appendix B: Fill derives {#fill-derives} | |
| The calculation of traits derivation rules is visible in | |
| [fidlgen_rust](/tools/fidl/fidlgen_rust/codegen/ir.go): | |
| ```go | |
| {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlgen_rust/codegen/ir.go" region_tag="fill_derives" adjust_indentation="auto" %} | |
| ``` | |
| <!-- link labels --> | |
| [`HandleDisposition`]: https://fuchsia-docs.firebaseapp.com/rust/zx/struct.HandleDisposition.html | |
| [`HandleInfo`]: https://fuchsia-docs.firebaseapp.com/rust/zx/struct.HandleInfo.html | |
| [`persist`]: https://fuchsia-docs.firebaseapp.com/rust/fidl/fn.persist.html | |
| [`standalone_encode_value`]: https://fuchsia-docs.firebaseapp.com/rust/fidl/fn.standalone_encode_value.html | |
| [`standalone_encode_resource`]: https://fuchsia-docs.firebaseapp.com/rust/fidl/fn.standalone_encode_resource.html | |
| [`standalone_decode_value`]: https://fuchsia-docs.firebaseapp.com/rust/fidl/fn.standalone_decode_value.html | |
| [`standalone_decode_resource`]: https://fuchsia-docs.firebaseapp.com/rust/fidl/fn.standalone_decode_resource.html | |
| [`unpersist`]: https://fuchsia-docs.firebaseapp.com/rust/fidl/fn.unpersist.html | |
| [anon-names]: /docs/reference/fidl/language/language.md#inline-layouts | |
| [lang-bits]: /docs/reference/fidl/language/language.md#bits | |
| [lang-constants]: /docs/reference/fidl/language/language.md#constants | |
| [lang-enums]: /docs/reference/fidl/language/language.md#enums | |
| [lang-flexible]: /docs/reference/fidl/language/language.md#strict-vs-flexible | |
| [lang-protocol-composition]: /docs/reference/fidl/language/language.md#protocol-composition | |
| [lang-protocols]: /docs/reference/fidl/language/language.md#protocols | |
| [lang-resource]: /docs/reference/fidl/language/language.md#value-vs-resource | |
| [lang-structs]: /docs/reference/fidl/language/language.md#structs | |
| [lang-tables]: /docs/reference/fidl/language/language.md#tables | |
| [lang-unions]: /docs/reference/fidl/language/language.md#unions | |
| [rfc-0120]: /docs/contribute/governance/rfcs/0120_standalone_use_of_fidl_wire_format.md | |
| [rfc-0137]: /docs/contribute/governance/rfcs/0137_discard_unknown_data_in_fidl.md | |
| [tutorial]: /docs/development/languages/fidl/tutorials/rust | |
| [unknown-attr]: /docs/reference/fidl/language/attributes.md#unknown |