This file is a excessive stage overview of the Fuchsia Interface Definition
Language (FIDL), which is the language passe to picture interprocess
communication (IPC) protocols passe by programs running on Fuchsia. This overview
introduces the ideas in the assist of FIDL — builders aware of these ideas
already can open writing code by following the tutorials, or
dive deeper by discovering out the language or
bindings references.

What is FIDL?

Whereas “FIDL” stands for “Fuchsia Interface Definition Language,” the observe
itself might well also fair furthermore be passe to consult with a series of slightly a couple of ideas:

• FIDL wire format: the FIDL wire format specifies how FIDL
  messages are represented in memory for transmission over IPC
• FIDL language: the FIDL language is the syntax in which
  protocols are described in .fidl recordsdata
• FIDL compiler: the FIDL compiler generates code for
  programs to use and put in pressure protocols
• FIDL bindings: the FIDL bindings are
  language-explicit runtime enhance libraries and code mills that provide
  APIs for manipulating FIDL recordsdata structures and protocols.

The principle job of FIDL is to enable numerous clients and providers and products to interoperate.
Consumer diversity is aided by decoupling the implementation of the IPC mechanism
from its definition, and is simplified by automated code skills.

The FIDL language presents a well-recognized (though simplified) C-relish declaration
syntax that enables the provider supplier to precisely account for their protocols. In model
recordsdata forms, relish integers, floats, and strings, might well also fair furthermore be organized into more
advanced aggregate structures and unions. Mounted arrays and dynamically sized
vectors might well also fair furthermore be constructed from each the extraordinary forms and the mix forms,
and these can all be mixed into even more advanced recordsdata structures.

As a result of the series of shopper implementation target languages (C, C++, Rust, Fling,
and numerous others), we make now now not desire to burden the developer of the provider with providing
a protocol implementation for every and each body.

Here is the place aside the FIDL toolchain is available in. The developer of the provider creates
loyal one .fidl definition file, which defines the protocol. Using this file,
the FIDL compiler then generates shopper and server code in any of the supported
target languages.

In loads of cases, there’ll easiest be one implementation of the server (as an illustration,
the explicit provider might well be implemented in C++), whereas there would be any
series of implementations of the buyer, in a extensive quantity of languages.

Cowl that the Fuchsia working machine has no innate recordsdata of FIDL. The
FIDL bindings use a extraordinary channel communication mechanism in Fuchsia. The
FIDL bindings and libraries put into effect a predicament of semantic behavior and persistence
codecs on how that channel is passe.

FIDL structure

From a developer’s level of look, the following are the principle components:

• FIDL definition file — here’s a textual negate file (ending in .fidl by
  convention) that defines the values, and protocols (programs with their
  parameters),
• shopper code — generated by the FIDL compiler (fidlc) toolchain for
  every explicit target language, and
• server code — furthermore generated by the FIDL compiler toolchain.

As a undoubtedly straightforward example of a FIDL definition file, steal into myth an “echo” provider
— regardless of the buyer sends to the server, the server loyal echoes support to
the buyer.

Line numbers had been added for clarity and are now now not segment of the .fidl file.

1   library fidl.examples.echo;
2
3   @discoverable
4   protocol Echo {
5       EchoString(struct {
6           fee string:now now not mandatory;
7       }) -> (struct {
8           response string:now now not mandatory;
9       });
10  };

Let’s fight through it line by line.

Line 1: The library keyword is passe to account for a namespace for this
protocol. FIDL protocols in slightly a couple of libraries might well need the an identical title, so the
namespace is passe to reveal apart amongst them.

Line 3: The @discoverable attribute indicates that the
protocol that follows must be made available for clients to join to.

Line 4: The protocol keyword introduces the title of the protocol, here
it’s known as Echo.

Lines 5-9: The capacity, its parameters, and return values. There are two abnormal
functions of this line:

• Cowl the declaration string:now now not mandatory (for every fee and response). The
  string segment indicates that the parameters are strings (sequences of
  characters), while the now now not mandatory constraint indicates that the parameter is
  now now not mandatory.
• The parameters are wrapped in a struct, which is the pinnacle stage form
  containing the capacity parameters.
• The -> segment indicates the return, which appears to be like after the capacity
  declaration, now now not sooner than. Unlike C++ or Java, one way can return loads of
  values.

The above FIDL file, then, has declared one protocol, known as Echo, with one
capacity, known as EchoString, that takes a nullable string and returns a nullable
string.

The easy example above passe loyal one recordsdata form, the string as each the enter
to the capacity to boot as the output.

The that you furthermore might can imagine FIDL recordsdata forms are very versatile:

form MyRequest=struct {
    serial uint32;
    key string;
    alternate options vector;
};

The above declares a structure known as MyRequest with three contributors: an
unsigned 32-bit integer known as serial, a string known as key, and a vector of
unsigned 32-bit integers known as alternate options

Messaging Devices

In expose to realize FIDL’s messaging, we now relish got to rupture things up into two
layers, and interpret some definitions.

At the backside (the working machine layer), there is an asynchronous
communications way geared in direction of neutral development of a sender and a
receiver:

• sender — the discover collectively that originates a message,
• receiver — the discover collectively that receives a message,

Sending a message is a non-blocking operation: the sender sends the message, and
is then free to proceed processing, despite what the receiver is doing.

A receiver can, if it wants to, block in expose to appear forward to a message.

The tip layer implements FIDL messages, and makes use of the backside (asynchronous)
layer. It affords with shoppers and servers:

• shopper — the discover collectively that is making a ask (of a server),
• server — the discover collectively that is processing a ask (on behalf of a
  shopper).

The terms “sender” and “receiver” construct sense when we’re discussing the
messages themselves — the underlying communications way is now now not undoubtedly
concerned about the roles that we now relish assigned to the events, loyal that one is
sending and one is receiving.

The terms “shopper” and “server” construct sense when we’re discussing the roles
that the events play. In explicit, a shopper would be a sender at one time,
and a receiver at a honorable time; same for the server.

Practically speaking, in the context of a shopper / server interplay, that
components that there are loads of gadgets:

1. blocking call — shopper sends to server, waits for reply
2. fire and omit — shopper sends to server, does now not question reply
3. callback or async call — shopper sends to server, however does now not
   block; a reply is delivered asynchronously some time later
4. occasion — server sends to shopper, without the buyer having asked
   for recordsdata

The principle is synchronous, the comfort are asynchronous. We are going to focus on these in
expose.

Consumer sends to server, waits for a reply

This model is the primitive “blocking call” or “purpose call” available in
most programming languages, with the exception of that the invocation is performed over a channel,
and thus can fail attributable to transport stage errors.

From the level of look of the buyer, it includes a call that blocks, while
the server performs some processing.

Here is a step-by-step description:

1. A consumer makes a call (optionally containing recordsdata) and blocks.
2. The server receives the buyer’s call (and now now not mandatory recordsdata), and performs some
   quantity of processing.
3. At the server‘s discretion, it replies to the buyer (with now now not mandatory recordsdata).
4. The server‘s reply causes the buyer to unblock.

To place in pressure this synchronous messaging model over an asynchronous messaging
way is easy. Steal that every the buyer-to-server and server-to-shopper
message transfers are, on the backside layer in the protocol, asynchronous. The
synchronization occurs on the buyer conclude, by having the buyer block except the
server‘s message arrives.

Most continuously, in this model, the buyer and server relish advance to an agreement:

• recordsdata circulation is initiated by the buyer,
• the buyer shall relish at most easiest one message excellent,
• the server shall ship a message to the buyer easiest in response to a shopper’s
  message
• the buyer shall look forward to the server‘s response sooner than continuing.

This blocking model is continuously passe the place aside the buyer wants to discover the reply to
its most modern ask sooner than it’ll proceed.

As an instance, the buyer might well also fair ask recordsdata from the server, and now now not have the selection to lift out
any slightly a couple of vital processing except that recordsdata arrives.

Or, the buyer might well must impression steps in a explicit expose, and must attributable to this truth
make sure that every step completes sooner than initiating the subsequent one. If an error
occurs, the buyer might well must impression corrective actions that depend upon how some distance
the operation has proceeded — one other reason to be synchronized to the
completion of every step.

Consumer sends to server, no reply

This model is furthermore identified as “fire and omit.” In it, the buyer sends the
message to the server. and then carries on with its operation. In distinction to
the blocking model, the buyer does now now not block, nor does it question a
response.

This model is passe in cases the place aside the buyer does now not must (or can now now not)
synchronize to the processing of its ask.

The classic example is a logging machine. The patron sends logging recordsdata to
the logging server (circles “1” and “2” in the way above), however has no reason
to dam. Pretty a couple of things can plod unpleasant on the server conclude:

1. the server is busy and can now now not tackle the write ask at this second,
2. the media is beefy and the server can now now not write the info,
3. the server has encountered a fault,
4. and numerous others.

Nevertheless, the buyer is now now not undoubtedly in a position to lift out the rest about these concerns, so
blocking would loyal fabricate more concerns.

Consumer sends to server, however does now not block

This model, and the subsequent one (“server sends to shopper, without shopper asking for
recordsdata”) are an identical.

In the expose model, the buyer sends a message to a server, however does now not block.
Nevertheless, the buyer expects some roughly response from the server, however the major
here is that it’s now now not synchronous with the ask.

This permits extensive flexibility in the buyer / server interplay.

Whereas the synchronous model forces the buyer to wait except the server replies,
the expose model frees the buyer to lift out one thing else while the server is
processing the ask:

The refined distinction in this manner vs. the an identical one above is that after
circle “1” the buyer is silent running. The patron chooses when to provide up
CPU; it’s now now not synchronous with the message.

There are undoubtedly two sub-cases here — one by which the buyer gets loyal
one response, and one other by which the buyer can discover loads of responses. (The
one the place aside the buyer gets zero responses is the “fire and omit” model, which
we discussed earlier.)

Single ask, single response

The one response case is the closest to the synchronous model: the buyer
sends a message, and at last, the server replies. You’d use this model
in preference to multi-threading, as an illustration, while you know that the buyer would be
doing vital work while expecting the server‘s reply.

Single ask, loads of response

The loads of response case might well also fair furthermore be passe in a “subscription” model. The patron’s
message “primes” the server, as an illustration, inquiring for notification at any time when
one thing occurs.

The patron then goes about its alternate.

Some time later, the server notices that the condition that the buyer is
drawn to has took space, and thus sends the buyer a message. From a shopper /
server level of look, this message is a “reply”, with the buyer receiving it
asynchronously to its ask.

There is no reason why the server couldn’t ship one other message when one other
occasion of hobby occurs; here is the “loads of response” version of the model.
Cowl that the second (and subsequent) responses are sent without the buyer
sending any extra messages.

Cowl that the buyer does now not need to appear forward to the server to ship it a
message. In the way above, we showed the buyer in the blocked divulge
sooner than circle “3” — the buyer might well loyal to boot had been running.

Server sends to shopper, without shopper asking for recordsdata

This model is furthermore identified as the “occasion” model.

In it, a shopper prepares to receive messages from a server, however does now not know
when to question them — the messages are now now not easiest asynchronous to the
shopper, however are furthermore (from a shopper / server level of look) “unsolicited”, in
that the buyer did now not explicitly ask them (relish it did in the old
model, above).

The patron designates a purpose (the “occasion coping with purpose”) to be known as
when messages arrive from the server, however otherwise continues about its
alternate.

At the server‘s discretion (circles “1” and “2” in the way above), messages
are sent asynchronously to the buyer, and handled by the buyer’s designated
purpose.

Cowl that the buyer might well also fair already be running when a message is sent (as in circle
“1”), or the buyer might well also fair relish nothing to lift out and be expecting a message to be
sent (as in circle “2”).

It’s now now not a requirement that the buyer be expecting a message.

Asynchronous messaging complexity

Breaking up asynchronous messaging into the above (considerably arbitrary)
categories is supposed to existing customary utilization patterns, however is now now not undoubtedly supposed to be
exhaustive.

In the most extraordinary case of asynchronous messaging, you furthermore might can fair relish zero or more shopper
messages loosely related with zero or more server replies. Or now now not it’s this “loose
association” that adds the complexity when it comes to your impression route of.

IPC gadgets in FIDL

Now that we now relish got an concept of the IPC gadgets and how they work at the side of
FIDL’s asynchronous messaging, let’s relish a look at how they’re outlined.

We are going to add the slightly a couple of gadgets (fire and omit, and async call or occasion) to the protocol
definition file:

1   library fidl.examples.echo;
2
3   @discoverable
4   protocol Echo {
5       EchoString(struct {
6           fee string:now now not mandatory;
7       }) -> (struct {
8           response string:now now not mandatory;
9       });
10
11      SendString(struct { fee string:now now not mandatory; });
12
13      ->ReceiveString(struct { response string:now now not mandatory; });
14  };

Lines 5-9 are the EchoString capacity that we discussed above — it’s some distance a
primitive purpose call message, the place aside the buyer calls EchoString with an
now now not mandatory string, and then blocks, expecting the server to reply with one other
now now not mandatory string.

Line 11 is the SendString capacity. It does now now not relish the -> return
declaration — that makes it into a “fire and omit” model (ship easiest),
because we now relish suggested the FIDL compiler that this explicit capacity does now now not relish a
return related with it.

Cowl that it’s now now not the shortcoming of return parameters, however slightly the shortcoming of
return declaration that is the major here — putting “-> ()” after
SendString would change the that components from declaring a fireplace-and-omit model
capacity to declaring a purpose call model capacity that does now not relish any return
arguments.

Line 13 is the ReceiveString capacity. Or now now not it’s some distance a limited slightly a couple of — it
does now not relish the capacity title in the principle segment, however slightly it’s given after the
-> operator. This tells the FIDL compiler that here is an “async call” or
“occasion” model declaration.

FIDL Bindings

The FIDL toolchain takes in FIDL protocol and form definitions, relish the
examples shown above, and generates code in every target language that can well “talk”
these protocols. This generated code is assumed as the FIDL bindings, which
are available in in varied flavors reckoning on the language:

• Native bindings: designed for highly snug contexts corresponding to machine
  drivers and excessive-throughput servers, leverage in-space entry, care for some distance off from memory
  allocation, however might well also fair require considerably more awareness of the constraints of
  the protocol on the segment of the developer.
• Idiomatic bindings: designed to be more developer-good by copying
  recordsdata from the wire format into more straightforward to use recordsdata forms (corresponding to heap-backed
  strings or vectors), however correspondingly considerably less efficient as a
  result.

Bindings supply loads of more than a couple of programs of invoking protocol programs reckoning on
the language:

• Send/receive: read or write messages on to a channel, no built-in
  wait loop (C)
• Callback-based fully: got messages are dispatched asynchronously as
  callbacks on an occasion loop (C++, Fling)
• Port-based fully: got messages are delivered to a port or future (Rust)
• Synchronous call: waits for reply and return it (Lumber, C++ unit tests)

Bindings provide some or all of the following major operations:

• Encode: in-space transform native recordsdata structures into the wire format
  (coupled with validation)
• Decode: in-space transform wire format recordsdata into native recordsdata structures
  (coupled with validation)
• Reproduction/Switch To Idiomatic Compose: reproduction contents of native recordsdata structures
  into idiomatic recordsdata structures, handles are moved
• Reproduction/Switch To Native Compose: reproduction contents of idiomatic recordsdata structures
  into native recordsdata structures, handles are moved
• Clone: reproduction native or idiomatic recordsdata structures (that lift out now now not relish
  transfer-easiest forms)
• Name: invoke protocol capacity

Consumer implementation

No subject the target language, the fidlc FIDL compiler generates shopper
code that has the following extraordinary structure.

The principle segment includes the administration and background coping with, and
includes:

1. some components of connecting to the server is offered
2. an asynchronous (“background”) message coping with loop is started
3. async call model and occasion model programs, if any, are sure to the message
   loop

The second segment includes implementations of the primitive purpose call or
fire and omit model programs, as appropriate for the target language.
On the total speaking, this includes:

1. developing a callable API and declarations
2. generating code for every API that marshals the info from the choice into a FIDL
   formatted buffer loyal for transmission to the server
3. generating code to transmit the info to the server
4. in the case of purpose call model calls, generating code to:
   1. look forward to the response from the server
   2. unmarshal the info from the FIDL formatted buffer, and
   3. return the info through the API purpose.

Obviously, the actual steps might well also fair vary attributable to language implementation differences,
however that is the extraordinary account for.

Server implementation

The fidlc FIDL compiler furthermore generates server code for a given target
language. Factual relish the buyer code, this code has a extraordinary structure regardless
of the target language. The code:

1. creates an object that clients can join to,
2. begins a major processing loop, which:
   1. waits for messages
   2. processes messages by calling out to the implementation capabilities
   3. if specified, components an asynchronous call support to the buyer to advance support
      the output

In the subsequent chapters, we will see the particulars of every language’s implementation of
the buyer and server code.

Why Expend FIDL?

Fuchsia extensively relies on IPC since most functionality is implemented in
person predicament exterior of the kernel, including privileged components corresponding to machine
drivers. In consequence the IPC mechanism wants to be efficient, deterministic,
sturdy, and simple to use:

IPC efficiency pertains to the computational overhead required to generate,
transfer, and direct messages between processes. IPC can fret with all
functions of machine operation so it wants to be efficient. The FIDL compiler must
generate tight code without excess indirection or hidden costs. It must be at
least as loyal as hand-rolled code would be the place aside it matters most.

IPC determinism pertains to the flexibility to electrify transactions inner a
identified resource envelope. IPC can be passe extensively by excessive machine
providers and products corresponding to filesystems, which assist many clients and must impression in
predictable programs. The FIDL wire format must supply solid static guarantees such
as making sure that structure size and format is invariant thereby alleviating the
need for dynamic memory allocation or advanced validation guidelines.

IPC robustness pertains to the must steal into myth IPC as an very fundamental segment of
the working machine’s ABI. Preserving binary balance is famous. Mechanisms
for protocol evolution wants to be designed conservatively in expose now now not to violate the
invariants of existing providers and products and their clients, particularly when the necessity
for determinism is furthermore concept to be. The FIDL bindings must impression efficient,
light-weight, and strict validation.

IPC ease of use pertains to the truth that IPC protocols are an very fundamental
segment of the working machine’s API. It is excessive to produce loyal developer
ergonomics for having access to providers and products through IPC. The FIDL code generator removes the
burden of writing IPC bindings by hand. Moreover, the FIDL code generator can
invent slightly a couple of bindings to suit the wants of slightly a couple of audiences and their
idioms.

Targets

FIDL is designed particularly to optimize for these for characteristics. In
explicit, the impression of FIDL aims to fulfill the following needs:

Specificity

• Portray recordsdata structures and protocols passe by IPC on Zircon.
• Optimized for interprocess communication. Despite the truth that FIDL is furthermore passe for
  persisting to disk and for network transfer, its impression is now now not optimized for
  these secondary use cases.
• Efficiently transport messages consisting of recordsdata (bytes) and capabilities
  (handles) over Zircon channels between processes running on the an identical machine.
• Designed particularly to facilitate efficient use of Zircon primitives.
  Despite the truth that FIDL is passe on slightly a couple of platforms (e.g. through ffx), its impression puts
  Fuchsia first.
• Offers handy APIs for developing, sending, receiving, and involving
  messages.
• Establish ample validation to care for up protocol invariants (however no more
  than that).

Effectivity

• Factual as efficient (speed and memory) as utilizing hand-rolled recordsdata structures
  would be.
• Wire format makes use of uncompressed native datatypes with limited-endianness and
  staunch alignment to enhance in-space entry of message contents.
• No dynamic memory allocation is required to invent or to direct messages
  when their size is statically identified or bounded.
• Explicitly tackle ownership with transfer-easiest semantics.
• Data structure packing expose is canonical, unambiguous, and has minimum
  padding.
• Support some distance off from support-patching pointers.
• Support some distance off from costly validation.
• Support some distance off from calculations that can overflow.
• Leverage pipelining of protocol requests for asynchronous operation.
• Constructions are fastened size; variable-size recordsdata is kept out-of-line.
• Constructions are now now not self-described; FIDL recordsdata picture their contents.
• No versioning of structures, however protocols might well also fair furthermore be extended with novel programs
  for evolution.

Ergonomics

• Programming language bindings maintained by Fuchsia team:
  • C, Low-Diploma C++, High-Diploma C++, Fling, Lumber, Rust
• Preserving in thoughts we might well desire to enhance slightly a couple of languages in due route, such
  as:
  • Java, JavaScript, and numerous others.
• The bindings and generated code are available in in native or idiomatic flavors
  reckoning on the supposed software program.
• Expend assemble-time code skills to optimize message serialization,
  deserialization, and validation.
• FIDL syntax is familiar, without effort accessible, and programming language
  agnostic.
• FIDL presents a library machine to simplify deployment and use by slightly a couple of
  builders.
• FIDL expresses the most customary recordsdata forms wished for machine APIs; it does
  now now not inquire of to produce a entire one-to-one mapping of all kinds offered
  by all programming languages.

Workflow

This section recaps the workflow of authors, publishers, and patrons of IPC
protocols described utilizing FIDL.

Authoring FIDL

The creator of a FIDL based fully protocol creates one or more *.fidl recordsdata to
picture their recordsdata structures, protocols, and programs.

FIDL recordsdata are grouped into one or more FIDL libraries by the creator. Every
library represents a community of logically related functionality with a honorable
library title. FIDL recordsdata contained in the an identical library implicitly relish entry to all
slightly a couple of declarations contained in the an identical library. The expose of declarations contained in the
FIDL recordsdata that construct up a library is now now not major.

FIDL recordsdata of one library can entry declarations inner one other FIDL library by
importing the slightly a couple of FIDL module. Importing slightly a couple of FIDL libraries makes their
symbols available to be used thereby enabling the construction of protocols derived
from them. Imported symbols wants to be certified by the library title or by an alias
to prevent namespace collisions.

Publishing FIDL

The publisher of a FIDL based fully protocol is liable for making FIDL libraries
available to patrons. As an instance, the creator might well also fair disseminate FIDL libraries
in a public supply repository or distribute them as segment of an SDK.

Consumers need easiest level the FIDL compiler on the directory that comprises the
FIDL recordsdata for a library (and its dependencies) to generate code for that
library. The explicit particulars for the model here is performed will generally be addressed by
the user’s invent machine.

Spirited FIDL

The user of a FIDL based fully protocol makes use of the FIDL compiler to generate code
loyal to be used with their language runtime explicit bindings. For optimistic
language runtimes, the user might well also fair relish a series of a couple of slightly a couple of flavors of
generated code all of which might well maybe be interoperable on the wire format stage however
in all likelihood now now not on the supply stage.

In the Fuchsia world invent environment, generating code from FIDL libraries will
be performed mechanically for all related languages by particular person FIDL invent
targets for every library.

In the Fuchsia SDK environment, generating code from FIDL libraries can be performed
as segment of compiling the purposes that use them.

Getting Started

Must you like to be taught more about utilizing FIDL, the Guides section has a series of
developer guides and tutorials that you
can try. Must you would be growing on Fuchsia and would relish to be taught about
use bindings for an existing FIDL API, you furthermore might can focus on with the FIDL bindings
reference. At last, in expose so that you can be taught more about FIDL or
would relish to make contributions, take a look at out the FIDL language
reference, or the contributing doc.