IPDL: Inter-Thread and Inter-Process Message Passing
====================================================
The Idea
--------
**IPDL**, the "Inter-[thread|process] Protocol Definition Language", is the
Mozilla-specific language that allows code to communicate between system
threads or processes in a standardized, efficient, safe, secure and
platform-agnostic way. IPDL communications take place between *parent* and
*child* objects called *actors*. The architecture is inspired by the `actor
model <
https://en.wikipedia.org/wiki/Actor_model>`_.
.. note::
IPDL actors differ from the actor model in one significant way -- all
IPDL communications are *only* between a parent and its only child.
The actors that constitute a parent/child pair are called **peers**. Peer
actors communicate through an **endpoint**, which is an end of a message pipe.
An actor is explicitly bound to its endpoint, which in turn is bound to a
particular thread soon after it is constructed. An actor never changes its
endpoint and may only send and receive predeclared **messages** from/to that
endpoint, on that thread. Violations result in runtime errors. A thread may
be bound to many otherwise unrelated actors but an endpoint supports
**top-level** actors and any actors they **manage** (see below).
.. note::
More precisely, endpoints can be bound to any ``nsISerialEventTarget``,
which are themselves associated with a specific thread. By default,
IPDL will bind to the current thread's "main" serial event target,
which, if it exists, is retrieved with ``GetCurrentSerialEventTarget``.
For the sake of clarity, this document will frequently refer to actors
as bound to threads, although the more precise interpretation of serial
event targets is also always valid.
.. note::
Internally, we use the "Ports" component of the `Chromium Mojo`_ library
to *multiplex* multiple endpoints (and, therefore, multiple top-level
actors). This means that the endpoints communicate over the same native
pipe, which conserves limited OS resources. The implications of this are
discussed in `IPDL Best Practices`_.
Parent and child actors may be bound to threads in different processes, in
different threads in the same process, or even in the same thread in the same
process. That last option may seem unreasonable but actors are versatile and
their layout can be established at run-time so this could theoretically arise
as the result of run-time choices. One large example of this versatility is
``PCompositorBridge`` actors, which in different cases connect endpoints in the
main process and the GPU process (for UI rendering on Windows), in a content
process and the GPU process (for content rendering on Windows), in the main
process and the content process (for content rendering on Mac, where there is
no GPU process), or between threads on the main process (UI rendering on Mac).
For the most part, this does not require elaborate or redundant coding; it
just needs endpoints to be bound judiciously at runtime. The example in
:ref:`Connecting With Other Processes` shows one way this can be done. It
also shows that, without proper plain-language documentation of *all* of the
ways endpoints are configured, this can quickly lead to unmaintainable code.
Be sure to document your endpoint bindings thoroughly!!!
.. _Chromium Mojo:
https://chromium.googlesource.com/chromium/src/+/refs/heads/main/mojo/core/README.md#Port
The Approach
------------
The actor framework will schedule tasks to run on its associated event target,
in response to messages it receives. Messages are specified in an IPDL
**protocol** file and the response handler tasks are defined per-message by C++
methods. As actors only communicate in pairs, and each is bound to one thread,
sending is always done sequentially, never concurrently (same for receiving).
This means that it can, and does, guarantee that an actor will always receive
messages in the same order they were sent by its related actor -- and that this
order is well defined since the related actor can only send from one thread.
.. warning::
There are a few (rare) exceptions to the message order guarantee. They
include `synchronous nested`_ messages and messages with a ``[Priority]``
or ``[Compress]`` annotation.
An IPDL protocol file specifies the messages that may be sent between parent
and child actors, as well as the direction and payload of those messages.
Messages look like function calls but, from the standpoint of their caller,
they may start and end at any time in the future -- they are *asynchronous*,
so they won't block their sending actors or any other components that may be
running in the actor's thread's ``MessageLoop``.
.. note::
Not all IPDL messages are asynchronous. Again, we run into exceptions for
messages that are synchronous or `synchronous nested`_. Use of synchronous
and nested messages is strongly discouraged but may not always be avoidable.
They will be defined later, along with superior alternatives to both that
should work in nearly all cases.
Protocol files are compiled by the *IPDL compiler* in an early stage of the
build process. The compiler generates C++ code that reflects the protocol.
Specifically, it creates one C++ class that represents the parent actor and one
that represents the child. The generated files are then automatically included
in the C++ build process. The generated classes contain public methods for
sending the protocol messages, which client code will use as the entry-point to
IPC communication. The generated methods are built atop our IPC framework,
defined in `/ipc <
https://searchfox.org/mozilla-central/source/ipc>`_, that
standardizes the safe and secure use of sockets, pipes, shared memory, etc on
all supported platforms. See `Using The IPDL compiler`_ for more on
integration with the build process.
Client code must be written that subclasses these generated classes, in order
to add handlers for the tasks generated to respond to each message. It must
also add routines (``ParamTraits``) that define serialization and
deserialization for any types used in the payload of a message that aren't
already known to the IPDL system. Primitive types, and a bunch of Mozilla
types, have predefined ``ParamTraits`` (`here
<
https://searchfox.org/mozilla-central/source/ipc/glue/IPCMessageUtils.h>`__
and `here
<
https://searchfox.org/mozilla-central/source/ipc/glue/IPCMessageUtilsSpecializations.h>`__).
.. note::
Among other things, client code that uses the generated code must include
``chromium-config.mozbuild`` in its ``moz.build`` file. See `Using The
IPDL compiler`_ for a complete list of required build changes.
.. _synchronous nested: `The Rest`_
The Steps To Making A New Actor
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. Decide what folder you will work in and create:
#. An IPDL protocol file, named for your actor (e.g. ``PMyActor.ipdl`` --
actor protocols must begin with a ``P``). See `The Protocol Language`_.
#. Properly-named source files for your actor's parent and child
implementations (e.g. ``MyActorParent.h``, ``MyActorChild.h`` and,
optionally, adjacent .cpp files). See `The C++ Interface`_.
#. IPDL-specific updates to the ``moz.build`` file. See `Using The IPDL
compiler`_.
#. Write your actor protocol (.ipdl) file:
#. Decide whether you need a top-level actor or a managed actor. See
`Top Level Actors`_.
#. Find/write the IPDL and C++ data types you will use in communication.
Write ``ParamTraits`` for C++ data types that don't have them. See
`Generating IPDL-Aware C++ Data Types: IPDL Structs and Unions`_ for IPDL
structures. See `Referencing Externally Defined Data Types: IPDL
Includes`_ and `ParamTraits`_ for C++ data types.
#. Write your actor and its messages. See `Defining Actors`_.
#. Write C++ code to create and destroy instances of your actor at runtime.
* For managed actors, see `Actor Lifetimes in C++`_.
* For top-level actors, see `Creating Top Level Actors From Other Actors`_.
The first actor in a process is a very special exception -- see `Creating
First Top Level Actors`_.
#. Write handlers for your actor's messages. See `Actors and Messages in
C++`_.
#. Start sending messages through your actors! Again, see `Actors and Messages
in C++`_.
The Protocol Language
---------------------
This document will follow the integration of two actors into Firefox --
``PMyManager`` and ``PMyManaged``. ``PMyManager`` will manage ``PMyManaged``.
A good place to start is with the IPDL actor definitions. These are files
that are named for the actor (e.g. ``PMyManager.ipdl``) and that declare the
messages that a protocol understands. These actors are for demonstration
purposes and involve quite a bit of functionality. Most actors will use a very
small fraction of these features.
.. literalinclude:: _static/PMyManager.ipdl
:language: c++
:name: PMyManager.ipdl
.. literalinclude:: _static/PMyManaged.ipdl
:language: c++
:name: PMyManaged.ipdl
These files reference three additional files. ``MyTypes.ipdlh`` is an "IPDL
header" that can be included into ``.ipdl`` files as if it were inline, except
that it also needs to include any external actors and data types it uses:
.. literalinclude:: _static/MyTypes.ipdlh
:language: c++
:name: MyTypes.ipdlh
``MyActorUtils.h`` and ``MyDataTypes.h`` are normal C++ header files that
contain definitions for types passed by these messages, as well as instructions
for serializing them. They will be covered in `The C++ Interface`_.
Using The IPDL compiler
~~~~~~~~~~~~~~~~~~~~~~~
To build IPDL files, list them (alphabetically sorted) in a ``moz.build`` file.
In this example, the ``.ipdl`` and ``.ipdlh`` files would be alongside a
``moz.build`` containing:
.. code-block:: python
IPDL_SOURCES += [
"MyTypes.ipdlh",
"PMyManaged.ipdl",
"PMyManager.ipdl",
]
UNIFIED_SOURCES += [
"MyManagedChild.cpp",
"MyManagedParent.cpp",
"MyManagerChild.cpp",
"MyManagerParent.cpp",
]
include("/ipc/chromium/chromium-config.mozbuild")
``chromium-config.mozbuild`` sets up paths so that generated IPDL header files
are in the proper scope. If it isn't included, the build will fail with
``#include`` errors in both your actor code and some internal ipc headers. For
example:
.. code-block::
c:/mozilla-src/mozilla-unified/obj-64/dist/include\ipc/IPCMessageUtils.h(13,10):
fatal error: 'build/build_config.h' file not found
``.ipdl`` files are compiled to C++ files as one of the earliest post-configure
build steps. Those files are, in turn, referenced throughout the source code
and build process. From ``PMyManager.ipdl`` the compiler generates two header
files added to the build context and exported globally:
``mozilla/myns/PMyManagerParent.h`` and ``mozilla/myns/PMyManagerChild.h``, as
discussed in `Namespaces`_ below. These files contain the base classes for the
actors. It also makes several other files, including C++ source files and
another header, that are automatically included into the build and should not
require attention.
C++ definions of the actors are required for IPDL. They define the actions
that are taken in response to messages -- without this, they would have no
value. There will be much more on this when we discuss `Actors and Messages in
C++`_ but note here that C++ header files named for the actor are required by
the IPDL `compiler`. The example would expect
``mozilla/myns/MyManagedChild.h``, ``mozilla/myns/MyManagedParent.h``,
``mozilla/myns/MyManagerChild.h`` and ``mozilla/myns/MyManagerParent.h`` and
will not build without them.
Referencing Externally Defined Data Types: IPDL Includes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Let's begin with ``PMyManager.ipdl``. It starts by including types that it
will need from other places:
.. code-block:: cpp
include protocol PMyManaged;
include MyTypes; // for MyActorPair
using MyActorEnum from "mozilla/myns/MyActorUtils.h";
using struct mozilla::myns::MyData from "mozilla/MyDataTypes.h";
[MoveOnly] using mozilla::myns::MyOtherData from "mozilla/MyDataTypes.h";
[RefCounted] using class mozilla::myns::MyThirdData from "mozilla/MyDataTypes.h";
The first line includes a protocol that PMyManager will manage. That protocol
is defined in its own ``.ipdl`` file. Cyclic references are expected and pose
no concern.
The second line includes the file ``MyTypes.ipdlh``, which defines types like
structs and unions, but in IPDL, which means they have behavior that goes
beyond the similar C++ concepts. Details can be found in `Generating
IPDL-Aware C++ Data Types: IPDL Structs and Unions`_.
The final lines include types from C++ headers. Additionally, the [RefCounted]
and [MoveOnly] attributes tell IPDL that the types have special functionality
that is important to operations. These are the data type attributes currently
understood by IPDL:
================ ==============================================================
``[RefCounted]`` Type ``T`` is reference counted (by ``AddRef``/``Release``).
As a parameter to a message or as a type in IPDL
structs/unions, it is referenced as a ``RefPtr<T>``.
``[MoveOnly]`` The type ``T`` is treated as uncopyable. When used as a
parameter in a message or an IPDL struct/union, it is as an
r-value ``T&&``.
================ ==============================================================
Finally, note that ``using``, ``using class`` and ``using struct`` are all
valid syntax. The ``class`` and ``struct`` keywords are optional.
Namespaces
~~~~~~~~~~
From the IPDL file:
.. code-block:: cpp
namespace mozilla {
namespace myns {
// ... data type and actor definitions ...
} // namespace myns
} // namespace mozilla
Namespaces work similar to the way they do in C++. They also mimic the
notation, in an attempt to make them comfortable to use. When IPDL actors are
compiled into C++ actors, the namespace scoping is carried over. As previously
noted, when C++ types are included into IPDL files, the same is true. The most
important way in which they differ is that IPDL also uses the namespace to
establish the path to the generated files. So, the example defines the IPDL
data type ``mozilla::myns::MyUnion`` and the actors
``mozilla::myns::PMyManagerParent`` and ``mozilla::myns::PMyManagerChild``,
which can be included from ``mozilla/myns/PMyManagerParent.h``,
``mozilla/myns/PMyManagerParent.h`` and ``mozilla/myns/PMyManagerChild.h``,
respectively. The namespace becomes part of the path.
Generating IPDL-Aware C++ Data Types: IPDL Structs and Unions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
``PMyManager.ipdl`` and ``MyTypes.ipdlh`` define:
.. code-block:: cpp
[Comparable] union MyUnion {
float;
MyOtherData;
};
struct MyActorPair {
PMyManaged actor1;
nullable PMyManaged actor2;
};
From these descriptions, IPDL generates C++ classes that approximate the
behavior of C++ structs and unions but that come with pre-defined
``ParamTraits`` implementations. These objects can also be used as usual
outside of IPDL, although the lack of control over the generated code means
they are sometimes poorly suited to use as plain data. See `ParamTraits`_ for
details.
The ``[Comparable]`` attribute tells IPDL to generate ``operator==`` and
``operator!=`` for the new type. In order for it to do that, the fields inside
the new type need to define both of those operators.
Finally, the ``nullable`` keyword indicates that, when serialized, the actor
may be null. It is intended to help users avoid null-object dereference
errors. It only applies to actor types and may also be attached to parameters
in message declarations.
Defining Actors
~~~~~~~~~~~~~~~
The real point of any ``.ipdl`` file is that each defines exactly one actor
protocol. The definition always matches the ``.ipdl`` filename. Repeating the
one in ``PMyManager.ipdl``:
.. code-block:: cpp
[ChildProc=Content]
sync protocol PMyManager {
manages PMyManaged;
async PMyManaged();
// ... more message declarations ...
};
.. important::
A form of reference counting is `always` used internally by IPDL to make
sure that it and its clients never address an actor the other component
deleted but this becomes fragile, and sometimes fails, when the client code
does not respect the reference count. For example, when IPDL detects that
a connection died due to a crashed remote process, deleting the actor could
leave dangling pointers, so IPDL `cannot` delete it. On the other hand,
there are many cases where IPDL is the only entity to have references to
some actors (this is very common for one side of a managed actor) so IPDL
`must` delete it. If all of those objects were reference counted then
there would be no complexity here. Indeed, new actors using
``[ManualDealloc]`` should not be approved without a very compelling
reason. New ``[ManualDealloc]`` actors may soon be forbidden.
The ``sync`` keyword tells IPDL that the actor contains messages that block the
sender using ``sync`` blocking, so the sending thread waits for a response to
the message. There is more on what it and the other blocking modes mean in
`IPDL messages`_. For now, just know that this is redundant information whose
value is primarily in making it easy for other developers to know that there
are ``sync`` messages defined here. This list gives preliminary definitions of
the options for the actor-blocking policy of messages:
======================= =======================================================
``async`` Actor may contain only asynchronous messages.
``sync`` Actor has ``async`` capabilities and adds ``sync``
messages. ``sync`` messages
can only be sent from the child actor to the parent.
======================= =======================================================
Beyond these protocol blocking strategies, IPDL supports annotations that
indicate the actor has messages that may be received in an order other than
the one they were sent in. These orderings attempt to handle messages in
"message thread" order (as in e.g. mailing lists). These behaviors can be
difficult to design for. Their use is discouraged but is sometimes warranted.
They will be discussed further in `Nested messages`_.
============================== ================================================
``[NestedUpTo=inside_sync]`` Actor has high priority messages that can be
handled while waiting for a ``sync`` response.
``[NestedUpTo=inside_cpow]`` Actor has the highest priority messages that
can be handled while waiting for a ``sync``
response.
============================== ================================================
In addition, top-level protocols are annotated with which processes each side
should be bound into using the ``[ParentProc=*]`` and ``[ChildProc=*]``
attributes. The ``[ParentProc]`` attribute is optional, and defaults to the
``Parent`` process. The ``[ChildProc]`` attribute is required. See `Process
Type Attributes`_ for possible values.
The ``manages`` clause tells IPDL that ``PMyManager`` manages the
``PMyManaged`` actor that was previously ``include`` d. As with any managed
protocol, it must also be the case that ``PMyManaged.ipdl`` includes
``PMyManager`` and declares that ``PMyManaged`` is ``managed`` by
``PMyManager``. Recalling the code:
.. code-block:: cpp
// PMyManaged.ipdl
include protocol PMyManager;
// ...
protocol PMyManaged {
manager PMyManager;
// ...
};
An actor has a ``manager`` (e.g. ``PMyManaged``) or else it is a top-level
actor (e.g. ``PMyManager``). An actor protocol may be managed by more than one
actor type. For example, ``PMyManaged`` could have also been managed by some
``PMyOtherManager`` not shown here. In that case, ``manager`` s are presented
in a list, separated by ``or`` -- e.g. ``manager PMyManager or
PMyOtherManager``. Of course, an **instance** of a managed actor type has only
one manager actor (and is therefore managed by only one of the types of
manager). The manager of an instance of a managee is always the actor that
constructed that managee.
Finally, there is the message declaration ``async PMyManaged()``. This message
is a constructor for ``MyManaged`` actors; unlike C++ classes, it is found in
``MyManager``. Every manager will need to expose constructors to create its
managed types. These constructors are the only way to create an actor that is
managed. They can take parameters and return results, like normal messages.
The implementation of IPDL constructors are discussed in `Actor Lifetimes in
C++`_.
We haven't discussed a way to construct new top level actors. This is a more
advanced topic and is covered separately in `Top Level Actors`_.
.. _IPDL messages: `Declaring IPDL Messages`_
Declaring IPDL Messages
~~~~~~~~~~~~~~~~~~~~~~~
The final part of the actor definition is the declaration of messages:
.. code-block:: cpp
sync protocol PMyManager {
// ...
parent:
async __delete__(nsString aNote);
sync SomeMsg(MyActorPair? aActors, MyData[] aMyData)
returns (int32_t x, int32_t y, MyUnion aUnion);
async PMyManaged();
both:
[Tainted] async AnotherMsg(MyActorEnum aEnum, int32_t a number)
returns (MyOtherData aOtherData);
};
The messages are grouped into blocks by ``parent:``, ``child:`` and ``both:``.
These labels work the way ``public:`` and ``private:`` work in C++ -- messages
after these descriptors are sent/received (only) in the direction specified.
.. note::
As a mnemonic to remember which direction they indicate, remember to put
the word "to" in front of them. So, for example, ``parent:`` precedes
``__delete__``, meaning ``__delete__`` is sent from the child **to** the
parent, and ``both:`` states that ``AnotherMsg`` can be sent **to** either
endpoint.
IPDL messages support the following annotations:
======================== ======================================================
``[Compress]`` Indicates repeated messages of this type will
consolidate.
``[Tainted]`` Parameters are required to be validated before using
them.
``[Priority=Foo]`` Priority of ``MessageTask`` that runs the C++ message
handler. ``Foo`` is one of: ``normal``, ``input``,
``vsync``, ``mediumhigh``, or ``control``.
See the ``IPC::Message::PriorityValue`` enum.
``[Nested=inside_sync]`` Indicates that the message can sometimes be handled
while a sync message waits for a response.
``[Nested=inside_cpow]`` Indicates that the message can sometimes be handled
while a sync message waits for a response.
``[LazySend]`` Messages with this annotation will be queued up to be
sent together either immediately before a non-LazySend
message, or from a direct task.
======================== ======================================================
``[Compress]`` provides crude protection against spamming with a flood of
messages. When messages of type ``M`` are compressed, the queue of unprocessed
messages between actors will never contain an ``M`` beside another one; they
will always be separated by a message of a different type. This is achieved by
throwing out the older of the two messages if sending the new one would break
the rule. This has been used to throttle pointer events between the main and
content processes.
``[Compress=all]`` is similar but applies whether or not the messages are
adjacent in the message queue.
``[Tainted]`` is a C++ mechanism designed to encourage paying attentiton to
parameter security. The values of tainted parameters cannot be used until you
vouch for their safety. They are discussed in `Actors and Messages in C++`_.
The ``Nested`` annotations are deeply related to the message's blocking policy
that follows it and which was briefly discussed in `Defining Actors`_. See
`Nested messages`_ for details.
``[LazySend]`` indicates the message doesn't need to be sent immediately, and
can be sent later, from a direct task. Worker threads which do not support
direct task dispatch will ignore this attribute. Messages with this annotation
will still be delivered in-order with other messages, meaning that if a normal
message is sent, any queued ``[LazySend]`` messages will be sent first. The
attribute allows the transport layer to combine messages to be sent together,
potentially reducing thread wake-ups for I/O and receiving threads.
The following is a complete list of the available blocking policies. It
resembles the list in `Defining Actors`_:
====================== ========================================================
``async`` Actor may contain only asynchronous messages.
``sync`` Actor has ``async`` capabilities and adds ``sync``
messages. ``sync`` messages can only be sent from the
child actor to the parent.
====================== ========================================================
The policy defines whether an actor will wait for a response when it sends a
certain type of message. A ``sync`` actor will wait immediately after sending
a ``sync`` message, stalling its thread, until a response is received. This is
an easy source of browser stalls. It is rarely required that a message be
synchronous. New ``sync`` messages are therefore required to get approval from
an IPC peer. The IPDL compiler will require such messages to be listed in the
file ``sync-messages.ini``.
The notion that only child actors can send ``sync`` messages was introduced to
avoid potential deadlocks. It relies on the belief that a cycle (deadlock) of
sync messages is impossible because they all point in one direction. This is
no longer the case because any endpoint can be a child `or` parent and some,
like the main process, sometimes serve as both. This means that sync messages
should be used with extreme care.
.. note::
The notion of sync messages flowing in one direction is still the main
mechanism IPDL uses to avoid deadlock. New actors should avoid violating
this rule as the consequences are severe (and complex). Actors that break
these rules should not be approved without **extreme** extenuating
circumstances. If you think you need this, check with the IPC team on
Element first (#ipc).
An ``async`` actor will not wait. An ``async`` response is essentially
identical to sending another ``async`` message back. It may be handled
whenever received messages are handled. The value over an ``async`` response
message comes in the ergonomics -- async responses are usually handled by C++
lambda functions that are more like continuations than methods. This makes
them easier to write and to read. Additionally, they allow a response to
return message failure, while there would be no such response if we were
expecting to send a new async message back, and it failed.
Following synchronization is the name of the message and its parameter list.
The message ``__delete__`` stands out as strange -- indeed, it terminates the
actor's connection. `It does not delete any actor objects itself!` It severs
the connections of the actor `and any actors it manages` at both endpoints. An
actor will never send or receive any messages after it sends or receives a
``__delete__``. Note that all sends and receives have to happen on a specific
*worker* thread for any actor tree so the send/receive order is well defined.
Anything sent after the actor processes ``__delete__`` is ignored (send returns
an error, messages yet to be received fail their delivery). In other words,
some future operations may fail but no unexpected behavior is possible.
In our example, the child can break the connection by sending ``__delete__`` to
the parent. The only thing the parent can do to sever the connection is to
fail, such as by crashing. This sort of unidirectional control is both common
and desirable.
``PMyManaged()`` is a managed actor constructor. Note the asymmetry -- an
actor contains its managed actor's constructors but its own destructor.
The list of parameters to a message is fairly straight-forward. Parameters
can be any type that has a C++ ``ParamTraits`` specialization and is imported
by a directive. That said, there are some surprises in the list of messages:
================= =============================================================
``int32_t``,... The standard primitive types are included. See `builtin.py`_
for a list. Pointer types are, unsurprisingly, forbidden.
``?`` When following a type T, the parameter is translated into
``Maybe<T>`` in C++.
``[]`` When following a type T, the parameter is translated into
``nsTArray<T>`` in C++.
================= =============================================================
Finally, the returns list declares the information sent in response, also as a
tuple of typed parameters. As previously mentioned, even ``async`` messages
can receive responses. A ``sync`` message will always wait for a response but
an ``async`` message will not get one unless it has a ``returns`` clause.
This concludes our tour of the IPDL example file. The connection to C++ is
discussed in the next chapter; messages in particular are covered in `Actors
and Messages in C++`_. For suggestions on best practices when designing your
IPDL actor approach, see `IPDL Best Practices`_.
.. _builtin.py: https://searchfox.org/mozilla-central/source/ipc/ipdl/ipdl/builtin.py
IPDL Syntax Quick Reference
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following is a list of the keywords and operators that have been introduced
for use in IPDL files:
============================= =================================================
``include`` Include a C++ header (quoted file name) or
``.ipdlh`` file (unquoted with no file suffix).
``using (class|struct) from`` Similar to ``include`` but imports only a
specific data type.
``include protocol`` Include another actor for use in management
statements, IPDL data types or as parameters to
messages.
``[RefCounted]`` Indicates that the imported C++ data types are
reference counted. Refcounted types require a
different ``ParamTraits`` interface than
non-reference-counted types.
``[ManualDealloc]`` Indicates that the IPDL interface uses the legacy
manual allocation/deallocation interface, rather
than modern reference counting.
``[MoveOnly]`` Indicates that an imported C++ data type should
not be copied. IPDL code will move it instead.
``namespace`` Specifies the namespace for IPDL generated code.
``union`` An IPDL union definition.
``struct`` An IPDL struct definition.
``[Comparable]`` Indicates that IPDL should generate
``operator==`` and ``operator!=`` for the given
IPDL struct/union.
``nullable`` Indicates that an actor reference in an IPDL type
may be null when sent over IPC.
``protocol`` An IPDL protocol (actor) definition.
``sync/async`` These are used in two cases: (1) to indicate
whether a message blocks as it waits for a result
and (2) because an actor that contains ``sync``
messages must itself be labeled ``sync``.
``[NestedUpTo=inside_sync]`` Indicates that an actor contains
[Nested=inside_sync] messages, in addition to
normal messages.
``[NestedUpTo=inside_cpow]`` Indicates that an actor contains
[Nested=inside_cpow] messages, in addition to
normal messages.
``[Nested=inside_sync]`` Indicates that the message can be handled while
waiting for lower-priority, or in-message-thread,
sync responses.
``[Nested=inside_cpow]`` Indicates that the message can be handled while
waiting for lower-priority, or in-message-thread,
sync responses. Cannot be sent by the parent
actor.
``manager`` Used in a protocol definition to indicate that
this actor manages another one.
``manages`` Used in a protocol definition to indicate that
this actor is managed by another one.
``or`` Used in a ``manager`` clause for actors that have
multiple potential managers.
``parent: / child: / both:`` Indicates direction of subsequent actor messages.
As a mnemonic to remember which direction they
indicate, put the word "to" in front of them.
``returns`` Defines return values for messages. All types
of message, including ``async``, support
returning values.
``__delete__`` A special message that destroys the related
actors at both endpoints when sent.
``Recv__delete__`` and ``ActorDestroy`` are
called before destroying the actor at the other
endpoint, to allow for cleanup.
``int32_t``,... The standard primitive types are included.
``String`` Translated into ``nsString`` in C++.
``?`` When following a type T in an IPDL data structure
or message parameter,
the parameter is translated into ``Maybe<T>`` in
C++.
``[]`` When following a type T in an IPDL data structure
or message parameter,
the parameter is translated into ``nsTArray<T>``
in C++.
``[Tainted]`` Used to indicate that a message's handler should
receive parameters that it is required to
manually validate. Parameters of type ``T``
become ``Tainted<T>`` in C++.
``[Compress]`` Indicates repeated messages of this type will
consolidate. When two messages of this type are
sent and end up side-by-side in the message queue
then the older message is discarded (not sent).
``[Compress=all]`` Like ``[Compress]`` but discards the older
message regardless of whether they are adjacent
in the message queue.
``[Priority=Foo]`` Priority of ``MessageTask`` that runs the C++
message handler. ``Foo`` is one of: ``normal``,
``input``, ``vsync``, ``mediumhigh``, or
``control``.
``[LazySend]`` Messages with this annotation will be queued up to
be sent together immediately before a non-LazySend
message, or from a direct task.
``[ChildImpl="RemoteFoo"]`` Indicates that the child side implementation of
the actor is a class named ``RemoteFoo``, and the
definition is included by one of the
``include "...";`` statements in the file.
*New uses of this attribute are discouraged.*
``[ParentImpl="FooImpl"]`` Indicates that the parent side implementation of
the actor is a class named ``FooImpl``, and the
definition is included by one of the
``include "...";`` statements in the file.
*New uses of this attribute are discouraged.*
``[ChildImpl=virtual]`` Indicates that the child side implementation of
the actor is not exported by a header, so virtual
``Recv`` methods should be used instead of direct
function calls. *New uses of this attribute are
discouraged.*
``[ParentImpl=virtual]`` Indicates that the parent side implementation of
the actor is not exported by a header, so virtual
``Recv`` methods should be used instead of direct
function calls. *New uses of this attribute are
discouraged.*
``[ChildProc=...]`` Indicates which process the child side of the actor
is expected to be bound in. This will be release
asserted when creating the actor. Required for
top-level actors. See `Process Type Attributes`_
for possible values.
``[ParentProc=...]`` Indicates which process the parent side of the
actor is expected to be bound in. This will be
release asserted when creating the actor.
Defaults to ``Parent`` for top-level actors. See
`Process Type Attributes`_ for possible values.
============================= =================================================
.. _Process Type Attributes:
Process Type Attributes
^^^^^^^^^^^^^^^^^^^^^^^
The following are valid values for the ``[ChildProc=...]`` and
``[ParentProc=...]`` attributes on protocols, each corresponding to a specific
process type:
============================= =================================================
``Parent`` The primary "parent" or "main" process
``Content`` A content process, such as those used to host web
pages, workers, and extensions
``IPDLUnitTest`` Test-only process used in IPDL gtests
``GMPlugin`` Gecko Media Plugin (GMP) process
``GPU`` GPU process
``VR`` VR process
``RDD`` Remote Data Decoder (RDD) process
``Socket`` Socket/Networking process
``ForkServer`` Fork Server process
``Utility`` Utility process
============================= =================================================
The attributes also support some wildcard values, which can be used when an
actor can be bound in multiple processes. If you are adding an actor which
needs a new wildcard value, please reach out to the IPC team, and we can add one
for your use-case. They are as follows:
============================= =================================================
``any`` Any process. If a more specific value is
applicable, it should be preferred where possible.
``anychild`` Any process other than ``Parent``. Often used for
utility actors which are bound on a per-process
basis, such as profiling.
``compositor`` Either the ``GPU`` or ``Parent`` process. Often
used for actors bound to the compositor thread.
``anydom`` Either the ``Parent`` or a ``Content`` process.
Often used for actors used to implement DOM APIs.
============================= =================================================
Note that these assertions do not provide security guarantees, and are primarily
intended for use when auditing and as documentation for how actors are being
used.
The C++ Interface
-----------------
ParamTraits
~~~~~~~~~~~
Before discussing how C++ represents actors and messages, we look at how IPDL
connects to the imported C++ data types. In order for any C++ type to be
(de)serialized, it needs an implementation of the ``ParamTraits`` C++ type
class. ``ParamTraits`` is how your code tells IPDL what bytes to write to
serialize your objects for sending, and how to convert those bytes back to
objects at the other endpoint. Since ``ParamTraits`` need to be reachable by
IPDL code, they need to be declared in a C++ header and imported by your
protocol file. Failure to do so will result in a build error.
Most basic types and many essential Mozilla types are always available for use
without inclusion. An incomplete list includes: C++ primitives, strings
(``std`` and ``mozilla``), vectors (``std`` and ``mozilla``), ``RefPtr<T>``
(for serializable ``T``), ``UniquePtr<T>``, ``nsCOMPtr<T>``, ``nsTArray<T>``,
``std::unordered_map<T>``, ``nsresult``, etc. See `builtin.py
<https://searchfox.org/mozilla-central/source/ipc/ipdl/ipdl/builtin.py>`_,
`ipc_message_utils.h
<https://searchfox.org/mozilla-central/source/ipc/chromium/src/chrome/common/ipc_message_utils.h>`_
and `IPCMessageUtilsSpecializations.h
<https://searchfox.org/mozilla-central/source/ipc/glue/IPCMessageUtilsSpecializations.h>`_.
``ParamTraits`` typically bootstrap with the ``ParamTraits`` of more basic
types, until they hit bedrock (e.g. one of the basic types above). In the most
extreme cases, a ``ParamTraits`` author may have to resort to designing a
binary data format for a type. Both options are available.
We haven't seen any of this C++ yet. Let's look at the data types included
from ``MyDataTypes.h``:
.. code-block:: cpp
// MyDataTypes.h
namespace mozilla::myns {
struct MyData {
nsCString s;
uint8_t bytes[17];
MyData(); // IPDL requires the default constructor to be public
};
struct MoveonlyData {
MoveonlyData();
MoveonlyData& operator=(const MoveonlyData&) = delete;
MoveonlyData(MoveonlyData&& m);
MoveonlyData& operator=(MoveonlyData&& m);
};
typedef MoveonlyData MyOtherData;
class MyUnusedData {
public:
NS_INLINE_DECL_REFCOUNTING(MyUnusedData)
int x;
};
};
namespace IPC {
// Basic type
template<>
struct ParamTraits<mozilla::myns::MyData> {
typedef mozilla::myns::MyData paramType;
static void Write(MessageWriter* m, const paramType& in);
static bool Read(MessageReader* m, paramType* out);
};
// [MoveOnly] type
template<>
struct ParamTraits<mozilla::myns::MyOtherData> {
typedef mozilla::myns::MyOtherData paramType;
static void Write(MessageWriter* m, const paramType& in);
static bool Read(MessageReader* m, paramType* out);
};
// [RefCounted] type
template<>
struct ParamTraits<mozilla::myns::MyUnusedData*> {
typedef mozilla::myns::MyUnusedData paramType;
static void Write(MessageWriter* m, paramType* in);
static bool Read(MessageReader* m, RefPtr<paramType>* out);
};
}
MyData is a struct and MyOtherData is a typedef. IPDL is fine with both.
Additionally, MyOtherData is not copyable, matching its IPDL ``[MoveOnly]``
annotation.
``ParamTraits`` are required to be defined in the ``IPC`` namespace. They must
contain a ``Write`` method with the proper signature that is used for
serialization and a ``Read`` method, again with the correct signature, for
deserialization.
Here we have three examples of declarations: one for an unannotated type, one
for ``[MoveOnly]`` and a ``[RefCounted]`` one. Notice the difference in the
``[RefCounted]`` type's method signatures. The only difference that may not be
clear from the function types is that, in the non-reference-counted case, a
default-constructed object is supplied to ``Read`` but, in the
reference-counted case, ``Read`` is given an empty ``RefPtr<MyUnusedData>`` and
should only allocate a ``MyUnusedData`` to return if it so desires.
These are straight-forward implementations of the ``ParamTraits`` methods for
``MyData``:
.. code-block:: cpp
/* static */ void IPC::ParamTraits<MyData>::Write(MessageWriter* m, const paramType& in) {
WriteParam(m, in.s);
m->WriteBytes(in.bytes, sizeof(in.bytes));
}
/* static */ bool IPC::ParamTraits<MyData>::Read(MessageReader* m, paramType* out) {
return ReadParam(m, &out->s) &&
m->ReadBytesInto(out->bytes, sizeof(out->bytes));
}
``WriteParam`` and ``ReadParam`` call the ``ParamTraits`` for the data you pass
them, determined using the type of the object as supplied. ``WriteBytes`` and
``ReadBytesInto`` work on raw, contiguous bytes as expected. ``MessageWriter``
and ``MessageReader`` are IPDL internal objects which hold the incoming/outgoing
message as a stream of bytes and the current spot in the stream. It is *very*
rare for client code to need to create or manipulate these objects. Their
advanced use is beyond the scope of this document.
.. important::
Potential failures in ``Read`` include everyday C++ failures like
out-of-memory conditions, which can be handled as usual. But ``Read`` can
also fail due to things like data validation errors. ``ParamTraits`` read
data that is considered insecure. It is important that they catch
corruption and properly handle it. Returning false from ``Read`` will
usually result in crashing the process (everywhere except in the main
process). This is the right behavior as the browser would be in an
unexpected state, even if the serialization failure was not malicious
(since it cannot process the message). Other responses, such as failing
with a crashing assertion, are inferior. IPDL fuzzing relies on
``ParamTraits`` not crashing due to corruption failures.
Occasionally, validation will require access to state that ``ParamTraits``
can't easily reach. (Only) in those cases, validation can be reasonably
done in the message handler. Such cases are a good use of the ``Tainted``
annotation. See `Actors and Messages in C++`_ for more.
.. note::
In the past, it was required to specialize ``mozilla::ipc::IPDLParamTraits<T>``
instead of ``IPC::ParamTraits<T>`` if you needed the actor object itself during
serialization or deserialization. These days the actor can be fetched using
``IPC::Message{Reader,Writer}::GetActor()`` in ``IPC::ParamTraits``, so that
trait should be used for all new serializations.
A special case worth mentioning is that of enums. Enums are a common source of
security holes since code is rarely safe with enum values that are not valid.
Since data obtained through IPDL messages should be considered tainted, enums
are of principal concern. ``ContiguousEnumSerializer`` and
``ContiguousEnumSerializerInclusive`` safely implement ``ParamTraits`` for
enums that are only valid for a contiguous set of values, which is most of
them. The generated ``ParamTraits`` confirm that the enum is in valid range;
``Read`` will return false otherwise. As an example, here is the
``MyActorEnum`` included from ``MyActorUtils.h``:
.. code-block:: cpp
enum MyActorEnum { e1, e2, e3, e4, e5 };
template<>
struct ParamTraits<MyActorEnum>
: public ContiguousEnumSerializerInclusive<MyActorEnum, MyActorEnum::e1, MyActorEnum::e5> {};
IPDL Structs and Unions in C++
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
IPDL structs and unions become C++ classes that provide interfaces that are
fairly self-explanatory. Recalling ``MyUnion`` and ``MyActorPair`` from
`IPDL Structs and Unions`_ :
.. code-block:: cpp
union MyUnion {
float;
MyOtherData;
};
struct MyActorPair {
PMyManaged actor1;
nullable PMyManaged actor2;
};
These compile to:
.. code-block:: cpp
class MyUnion {
enum Type { Tfloat, TMyOtherData };
Type type();
MyUnion(float f);
MyUnion(MyOtherData&& aOD);
MyUnion& operator=(float f);
MyUnion& operator=(MyOtherData&& aOD);
operator float&();
operator MyOtherData&();
};
class MyActorPair {
MyActorPair(PMyManagedParent* actor1Parent, PMyManagedChild* actor1Child,
PMyManagedParent* actor2Parent, PMyManagedChild* actor2Child);
// Exactly one of { actor1Parent(), actor1Child() } must be non-null.
PMyManagedParent*& actor1Parent();
PMyManagedChild*& actor1Child();
// As nullable, zero or one of { actor2Parent(), actor2Child() } will be non-null.
PMyManagedParent*& actor2Parent();
PMyManagedChild*& actor2Child();
}
The generated ``ParamTraits`` use the ``ParamTraits`` for the types referenced
by the IPDL struct or union. Fields respect any annotations for their type
(see `IPDL Includes`_). For example, a ``[RefCounted]`` type ``T`` generates
``RefPtr<T>`` fields.
Note that actor members result in members of both the parent and child actor
types, as seen in ``MyActorPair``. When actors are used to bridge processes,
only one of those could ever be used at a given endpoint. IPDL makes sure
that, when you send one type (say, ``PMyManagedChild``), the adjacent actor of
the other type (``PMyManagedParent``) is received. This is not only true for
message parameters and IPDL structs/unions but also for custom ``ParamTraits``
implementations. If you ``Write`` a ``PFooParent*`` then you must ``Read`` a
``PFooChild*``. This is hard to confuse in message handlers since they are
members of a class named for the side they operate on, but this cannot be
enforced by the compiler. If you are writing
``MyManagerParent::RecvSomeMsg(Maybe<MyActorPair>&& aActors, nsTArray<MyData>&& aMyData)``
then the ``actor1Child`` and ``actor2Child`` fields cannot be valid since the
child (usually) exists in another process.
.. _IPDL Structs and Unions: `Generating IPDL-Aware C++ Data Types: IPDL Structs and Unions`_
.. _IPDL Includes: `Referencing Externally Defined Data Types: IPDL Includes`_
Actors and Messages in C++
~~~~~~~~~~~~~~~~~~~~~~~~~~
As mentioned in `Using The IPDL compiler`_, the IPDL compiler generates two
header files for the protocol ``PMyManager``: ``PMyManagerParent.h`` and
``PMyManagerChild.h``, which declare the actor's base classes. There, we
discussed how the headers are visible to C++ components that include
``chromium-config.mozbuild``. We, in turn, always need to define two files
that declare our actor implementation subclasses (``MyManagerParent.h`` and
``MyManagerChild.h``). The IPDL file looked like this:
.. literalinclude:: _static/PMyManager.ipdl
:language: c++
:name: PMyManager.ipdl
So ``MyManagerParent.h`` looks like this:
.. code-block:: cpp
#include "PMyManagerParent.h"
namespace mozilla {
namespace myns {
class MyManagerParent : public PMyManagerParent {
NS_INLINE_DECL_REFCOUNTING(MyManagerParent, override)
protected:
IPCResult Recv__delete__(const nsString& aNote);
IPCResult RecvSomeMsg(const Maybe<MyActorPair>& aActors, const nsTArray<MyData>& aMyData,
int32_t* x, int32_t* y, MyUnion* aUnion);
IPCResult RecvAnotherMsg(const Tainted<MyActorEnum>& aEnum, const Tainted<int32_t>& a number,
AnotherMsgResolver&& aResolver);
already_AddRefed<PMyManagerParent> AllocPMyManagedParent();
IPCResult RecvPMyManagedConstructor(PMyManagedConstructor* aActor);
// ... etc ...
};
} // namespace myns
} // namespace mozilla
All messages that can be sent to the actor must be handled by ``Recv`` methods
in the proper actor subclass. They should return ``IPC_OK()`` on success and
``IPC_FAIL(actor, reason)`` if an error occurred (where ``actor`` is ``this``
and ``reason`` is a human text explanation) that should be considered a failure
to process the message. The handling of such a failure is specific to the
process type.
``Recv`` methods are called by IPDL by enqueueing a task to run them on the
``MessageLoop`` for the thread on which they are bound. This thread is the
actor's *worker thread*. All actors in a managed actor tree have the same
worker thread -- in other words, actors inherit the worker thread from their
managers. Top level actors establish their worker thread when they are
*bound*. More information on threads can be found in `Top Level Actors`_. For
the most part, client code will never engage with an IPDL actor outside of its
worker thread.
Received parameters become stack variables that are ``std::move``-d into the
``Recv`` method. They can be received as a const l-value reference,
rvalue-reference, or by value (type-permitting). ``[MoveOnly]`` types should
not be received as const l-values. Return values for sync messages are
assigned by writing to non-const (pointer) parameters. Return values for async
messages are handled differently -- they are passed to a resolver function. In
our example, ``AnotherMsgResolver`` would be a ``std::function<>`` and
``aResolver`` would be given the value to return by passing it a reference to a
``MyOtherData`` object.
``MyManagerParent`` is also capable of ``sending`` an async message that
returns a value: ``AnotherMsg``. This is done with ``SendAnotherMsg``, which
is defined automatically by IPDL in the base class ``PMyManagerParent``. There
are two signatures for ``Send`` and they look like this:
.. code-block:: cpp
// Return a Promise that IPDL will resolve with the response or reject.
RefPtr<MozPromise<MyOtherData, ResponseRejectReason, true>>
SendAnotherMsg(const MyActorEnum& aEnum, int32_t a number);
// Provide callbacks to process response / reject. The callbacks are just
// std::functions.
void SendAnotherMsg(const MyActorEnum& aEnum, int32_t a number,
ResolveCallback<MyOtherData>&& aResolve, RejectCallback&& aReject);
The response is usually handled by lambda functions defined at the site of the
``Send`` call, either by attaching them to the returned promise with e.g.
``MozPromise::Then``, or by passing them as callback parameters. See docs on
``MozPromise`` for more on its use. The promise itself is either resolved or
rejected by IPDL when a valid reply is received or when the endpoint determines
that the communication failed. ``ResponseRejectReason`` is an enum IPDL
provides to explain failures.
Additionally, the ``AnotherMsg`` handler has ``Tainted`` parameters, as a
result of the [Tainted] annotation in the protocol file. Recall that
``Tainted`` is used to force explicit validation of parameters in the message
handler before their values can be used (as opposed to validation in
``ParamTraits``). They therefore have access to any state that the message
handler does. Their APIs, along with a list of macros that are used to
validate them, are detailed `here
<https://searchfox.org/mozilla-central/source/mfbt/Tainting.h>`__.
Send methods that are not for async messages with return values follow a
simpler form; they return a ``bool`` indicating success or failure and return
response values in non-const parameters, as the ``Recv`` methods do. For
example, ``PMyManagerChild`` defines this to send the sync message ``SomeMsg``:
.. code-block:: cpp
// generated in PMyManagerChild
bool SendSomeMsg(const Maybe<MyActorPair>& aActors, const nsTArray<MyData>& aMyData,
int32_t& x, int32_t& y, MyUnion& aUnion);
Since it is sync, this method will not return to its caller until the response
is received or an error is detected.
All calls to ``Send`` methods, like all messages handler ``Recv`` methods, must
only be called on the worker thread for the actor.
Constructors, like the one for ``MyManaged``, are clearly an exception to these
rules. They are discussed in the next section.
.. _Actor Lifetimes in C++:
Actor Lifetimes in C++
~~~~~~~~~~~~~~~~~~~~~~
The constructor message for ``MyManaged`` becomes *two* methods at the
receiving end. ``AllocPMyManagedParent`` constructs the managed actor, then
``RecvPMyManagedConstructor`` is called to update the new actor. The following
diagram shows the construction of the ``MyManaged`` actor pair:
.. mermaid::
:align: center
:caption: A ``MyManaged`` actor pair being created by some ``Driver``
object. Internal IPC objects in the parent and child processes
are combined for compactness. Connected **par** blocks run
concurrently. This shows that messages can be safely sent while
the parent is still being constructed.
%%{init: {'sequence': {'boxMargin': 4, 'actorMargin': 10} }}%%
sequenceDiagram
participant d as Driver
participant mgdc as MyManagedChild
participant mgrc as MyManagerChild
participant ipc as IPC Child/Parent
participant mgrp as MyManagerParent
participant mgdp as MyManagedParent
d->>mgdc: new
mgdc->>d: [mgd_child]
d->>mgrc: SendPMyManagedConstructor<br/>[mgd_child, params]
mgrc->>ipc: Form actor pair<br/>[mgd_child, params]
par
mgdc->>ipc: early PMyManaged messages
and
ipc->>mgrp: AllocPMyManagedParent<br/>[params]
mgrp->>mgdp: new
mgdp->>mgrp: [mgd_parent]
ipc->>mgrp: RecvPMyManagedConstructor<br/>[mgd_parent, params]
mgrp->>mgdp: initialization
ipc->>mgdp: early PMyManaged messages
end
Note over mgdc,mgdp: Bi-directional sending and receiving will now happen concurrently.
The next diagram shows the destruction of the ``MyManaged`` actor pair, as
initiated by a call to ``Send__delete__``. ``__delete__`` is sent from the
child process because that is the only side that can call it, as declared in
the IPDL protocol file.
.. mermaid::
:align: center
:caption: A ``MyManaged`` actor pair being disconnected due to some
``Driver`` object in the child process sending ``__delete__``.
%%{init: {'sequence': {'boxMargin': 4, 'actorMargin': 10} }}%%
sequenceDiagram
participant d as Driver
participant mgdc as MyManagedChild
participant ipc as IPC Child/Parent
participant mgdp as MyManagedParent
d->>mgdc: Send__delete__
mgdc->>ipc: Disconnect<br/>actor pair
par
ipc->>mgdc: ActorDestroy
ipc->>mgdc: Release
and
ipc->>mgdp: Recv__delete__
ipc->>mgdp: ActorDestroy
ipc->>mgdp: Release
end
Finally, let's take a look at the behavior of an actor whose peer has been lost
(e.g. due to a crashed process).
.. mermaid::
:align: center
:caption: A ``MyManaged`` actor pair being disconnected when its peer is
lost due to a fatal error. Note that ``Recv__delete__`` is not
called.
%%{init: {'sequence': {'boxMargin': 4, 'actorMargin': 10} }}%%
sequenceDiagram
participant mgdc as MyManagedChild
participant ipc as IPC Child/Parent
participant mgdp as MyManagedParent
Note over mgdc: CRASH!!!
ipc->>ipc: Notice fatal error.
ipc->>mgdp: ActorDestroy
ipc->>mgdp: Release
The ``Alloc`` and ``Recv...Constructor`` methods are somewhat mirrored by
``Recv__delete__`` and ``ActorDestroy`` but there are a few differences.
First, the ``Alloc`` method really does create the actor but the
``ActorDestroy`` method does not delete it. Additionally, ``ActorDestroy``
is run at *both* endpoints, during ``Send__delete__`` or after
``Recv__delete__``. Finally and most importantly, ``Recv__delete__`` is only
called if the ``__delete__`` message is received but it may not be if, for
example, the remote process crashes. ``ActorDestroy``, on the other hand, is
guaranteed to run for *every* actor unless the process terminates uncleanly.
For this reason, ``ActorDestroy`` is the right place for most actor shutdown
code. ``Recv__delete__`` is rarely useful, although it is occasionally
beneficial to have it receive some final data.
The relevant part of the parent class looks like this:
.. code-block:: cpp
class MyManagerParent : public PMyManagerParent {
already_AddRefed<PMyManagedParent> AllocPMyManagedParent();
IPCResult RecvPMyManagedConstructor(PMyManagedParent* aActor);
IPCResult Recv__delete__(const nsString& aNote);
void ActorDestroy(ActorDestroyReason why);
// ... etc ...
};
The ``Alloc`` method is required for managed actors that are constructed by
IPDL receiving a ``Send`` message. It is not required for the actor at the
endpoint that calls ``Send``. The ``Recv...Constructor`` message is not
required -- it has a base implementation that does nothing.
If the constructor message has parameters, they are sent to both methods.
Parameters are given to the ``Alloc`` method by const reference but are moved
into the ``Recv`` method. They differ in that messages can be sent from the
``Recv`` method but, in ``Alloc``, the newly created actor is not yet
operational.
The ``Send`` method for a constructor is similarly different from other
``Send`` methods. In the child actor, ours looks like this:
.. code-block:: cpp
IPCResult SendPMyManagedConstructor(PMyManagedChild* aActor);
The method expects a ``PMyManagedChild`` that the caller will have constructed,
presumably using ``new`` (this is why it does not require an ``Alloc`` method).
Once ``Send...Constructor`` is called, the actor can be used to send and
receive messages. It does not matter that the remote actor may not have been
created yet due to asynchronicity.
The destruction of actors is as unusual as their construction. Unlike
construction, it is the same for managed and top-level actors. Avoiding
``[ManualDealloc]`` actors removes a lot of the complexity but there is still
a process to understand. Actor destruction begins when an ``__delete__``
message is sent. In ``PMyManager``, this message is declared from child to
parent. The actor calling ``Send__delete__`` is no longer connected to
anything when the method returns. Future calls to ``Send`` return an error
and no future messages will be received. This is also the case for an actor
that has run ``Recv__delete__``; it is no longer connected to the other
endpoint.
.. note::
Since ``Send__delete__`` may release the final reference to itself, it
cannot safely be a class instance method. Instead, unlike other ``Send``
methods, it's a ``static`` class method and takes the actor as a parameter:
.. code-block:: cpp
static IPCResult Send__delete__(PMyManagerChild* aToDelete);
Additionally, the ``__delete__`` message tells IPDL to disconnect both the
given actor *and all of its managed actors*. So it is really deleting the
actor subtree, although ``Recv__delete__`` is only called for the actor it
was sent to.
During the call to ``Send__delete__``, or after the call to ``Recv__delete__``,
the actor's ``ActorDestroy`` method is called. This method gives client code a
chance to do any teardown that must happen in `all` circumstances were it is
possible -- both expected and unexpected. This means that ``ActorDestroy``
will also be called when, for example, IPDL detects that the other endpoint has
terminated unexpectedly, so it is releasing its reference to the actor, or
because an ancestral manager (manager or manager's manager...) received a
``__delete__``. The only way for an actor to avoid ``ActorDestroy`` is for its
process to crash first. ``ActorDestroy`` is always run after its actor is
disconnected so it is pointless to try to send messages from it.
Why use ``ActorDestroy`` instead of the actor's destructor? ``ActorDestroy``
gives a chance to clean up things that are only used for communication and
--> --------------------
--> maximum size reached
--> --------------------
