1 IPDL: Inter-Thread and Inter-Process Message Passing
2 ====================================================
7 **IPDL**, the "Inter-[thread|process] Protocol Definition Language", is the
8 Mozilla-specific language that allows code to communicate between system
9 threads or processes in a standardized, efficient, safe, secure and
10 platform-agnostic way. IPDL communications take place between *parent* and
11 *child* objects called *actors*. The architecture is inspired by the `actor
12 model <https://en.wikipedia.org/wiki/Actor_model>`_.
15 IPDL actors differ from the actor model in one significant way -- all
16 IPDL communications are *only* between a parent and its only child.
18 The actors that constitute a parent/child pair are called **peers**. Peer
19 actors communicate through an **endpoint**, which is an end of a message pipe.
20 An actor is explicitly bound to its endpoint, which in turn is bound to a
21 particular thread soon after it is constructed. An actor never changes its
22 endpoint and may only send and receive predeclared **messages** from/to that
23 endpoint, on that thread. Violations result in runtime errors. A thread may
24 be bound to many otherwise unrelated actors but an endpoint supports
25 **top-level** actors and any actors they **manage** (see below).
28 More precisely, endpoints can be bound to any ``nsISerialEventTarget``,
29 which are themselves associated with a specific thread. By default,
30 IPDL will bind to the current thread's "main" serial event target,
31 which, if it exists, is retrieved with ``GetCurrentSerialEventTarget``.
32 For the sake of clarity, this document will frequently refer to actors
33 as bound to threads, although the more precise interpretation of serial
34 event targets is also always valid.
37 Internally, we use the "Ports" component of the `Chromium Mojo`_ library
38 to *multiplex* multiple endpoints (and, therefore, multiple top-level
39 actors). This means that the endpoints communicate over the same native
40 pipe, which conserves limited OS resources. The implications of this are
41 discussed in `IPDL Best Practices`_.
43 Parent and child actors may be bound to threads in different processes, in
44 different threads in the same process, or even in the same thread in the same
45 process. That last option may seem unreasonable but actors are versatile and
46 their layout can be established at run-time so this could theoretically arise
47 as the result of run-time choices. One large example of this versatility is
48 ``PCompositorBridge`` actors, which in different cases connect endpoints in the
49 main process and the GPU process (for UI rendering on Windows), in a content
50 process and the GPU process (for content rendering on Windows), in the main
51 process and the content process (for content rendering on Mac, where there is
52 no GPU process), or between threads on the main process (UI rendering on Mac).
53 For the most part, this does not require elaborate or redundant coding; it
54 just needs endpoints to be bound judiciously at runtime. The example in
55 :ref:`Connecting With Other Processes` shows one way this can be done. It
56 also shows that, without proper plain-language documentation of *all* of the
57 ways endpoints are configured, this can quickly lead to unmaintainable code.
58 Be sure to document your endpoint bindings throroughly!!!
60 .. _Chromium Mojo: https://chromium.googlesource.com/chromium/src/+/refs/heads/main/mojo/core/README.md#Port
65 The actor framework will schedule tasks to run on its associated event target,
66 in response to messages it receives. Messages are specified in an IPDL
67 **protocol** file and the response handler tasks are defined per-message by C++
68 methods. As actors only communicate in pairs, and each is bound to one thread,
69 sending is always done sequentially, never concurrently (same for receiving).
70 This means that it can, and does, guarantee that an actor will always receive
71 messages in the same order they were sent by its related actor -- and that this
72 order is well defined since the related actor can only send from one thread.
75 There are a few (rare) exceptions to the message order guarantee. They
76 include `synchronous nested`_ messages, `interrupt`_ messages, and
77 messages with a ``[Priority]`` or ``[Compress]`` annotation.
79 An IPDL protocol file specifies the messages that may be sent between parent
80 and child actors, as well as the direction and payload of those messages.
81 Messages look like function calls but, from the standpoint of their caller,
82 they may start and end at any time in the future -- they are *asynchronous*,
83 so they won't block their sending actors or any other components that may be
84 running in the actor's thread's ``MessageLoop``.
87 Not all IPDL messages are asynchronous. Again, we run into exceptions for
88 messages that are synchronous, `synchronous nested`_ or `interrupt`_. Use
89 of synchronous and nested messages is strongly discouraged but may not
90 always be avoidable. They will be defined later, along with superior
91 alternatives to both that should work in nearly all cases. Interrupt
92 messages were prone to misuse and are deprecated, with removal expected in
94 (`Bug 1729044 <https://bugzilla.mozilla.org/show_bug.cgi?id=1729044>`_).
96 Protocol files are compiled by the *IPDL compiler* in an early stage of the
97 build process. The compiler generates C++ code that reflects the protocol.
98 Specifically, it creates one C++ class that represents the parent actor and one
99 that represents the child. The generated files are then automatically included
100 in the C++ build process. The generated classes contain public methods for
101 sending the protocol messages, which client code will use as the entry-point to
102 IPC communication. The generated methods are built atop our IPC framework,
103 defined in `/ipc <https://searchfox.org/mozilla-central/source/ipc>`_, that
104 standardizes the safe and secure use of sockets, pipes, shared memory, etc on
105 all supported platforms. See `Using The IPDL compiler`_ for more on
106 integration with the build process.
108 Client code must be written that subclasses these generated classes, in order
109 to add handlers for the tasks generated to respond to each message. It must
110 also add routines (``ParamTraits``) that define serialization and
111 deserialization for any types used in the payload of a message that aren't
112 already known to the IPDL system. Primitive types, and a bunch of Mozilla
113 types, have predefined ``ParamTraits`` (`here
114 <https://searchfox.org/mozilla-central/source/ipc/glue/IPCMessageUtils.h>`__
116 <https://searchfox.org/mozilla-central/source/ipc/glue/IPCMessageUtilsSpecializations.h>`__).
119 Among other things, client code that uses the generated code must include
120 ``chromium-config.mozbuild`` in its ``moz.build`` file. See `Using The
121 IPDL compiler`_ for a complete list of required build changes.
123 .. _interrupt: `The Old Ways`_
124 .. _synchronous nested: `The Rest`_
126 The Steps To Making A New Actor
127 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
129 #. Decide what folder you will work in and create:
131 #. An IPDL protocol file, named for your actor (e.g. ``PMyActor.ipdl`` --
132 actor protocols must begin with a ``P``). See `The Protocol Language`_.
133 #. Properly-named source files for your actor's parent and child
134 implementations (e.g. ``MyActorParent.h``, ``MyActorChild.h`` and,
135 optionally, adjacent .cpp files). See `The C++ Interface`_.
136 #. IPDL-specific updates to the ``moz.build`` file. See `Using The IPDL
138 #. Write your actor protocol (.ipdl) file:
140 #. Decide whether you need a top-level actor or a managed actor. See
142 #. Find/write the IPDL and C++ data types you will use in communication.
143 Write ``ParamTraits`` for C++ data types that don't have them. See
144 `Generating IPDL-Aware C++ Data Types: IPDL Structs and Unions`_ for IPDL
145 structures. See `Referencing Externally Defined Data Types: IPDL
146 Includes`_ and `ParamTraits`_ for C++ data types.
147 #. Write your actor and its messages. See `Defining Actors`_.
148 #. Write C++ code to create and destroy instances of your actor at runtime.
150 * For managed actors, see `Actor Lifetimes in C++`_.
151 * For top-level actors, see `Creating Top Level Actors From Other Actors`_.
152 The first actor in a process is a very special exception -- see `Creating
153 First Top Level Actors`_.
154 #. Write handlers for your actor's messages. See `Actors and Messages in
156 #. Start sending messages through your actors! Again, see `Actors and Messages
159 The Protocol Language
160 ---------------------
162 This document will follow the integration of two actors into Firefox --
163 ``PMyManager`` and ``PMyManaged``. ``PMyManager`` will manage ``PMyManaged``.
164 A good place to start is with the IPDL actor definitions. These are files
165 that are named for the actor (e.g. ``PMyManager.ipdl``) and that declare the
166 messages that a protocol understands. These actors are for demonstration
167 purposes and involve quite a bit of functionality. Most actors will use a very
168 small fraction of these features.
170 .. literalinclude:: _static/PMyManager.ipdl
172 :name: PMyManager.ipdl
174 .. literalinclude:: _static/PMyManaged.ipdl
176 :name: PMyManaged.ipdl
178 These files reference three additional files. ``MyTypes.ipdlh`` is an "IPDL
179 header" that can be included into ``.ipdl`` files as if it were inline, except
180 that it also needs to include any external actors and data types it uses:
182 .. literalinclude:: _static/MyTypes.ipdlh
186 ``MyActorUtils.h`` and ``MyDataTypes.h`` are normal C++ header files that
187 contain definitions for types passed by these messages, as well as instructions
188 for serializing them. They will be covered in `The C++ Interface`_.
190 Using The IPDL compiler
191 ~~~~~~~~~~~~~~~~~~~~~~~
193 To build IPDL files, list them (alphabetically sorted) in a ``moz.build`` file.
194 In this example, the ``.ipdl`` and ``.ipdlh`` files would be alongside a
195 ``moz.build`` containing:
206 "MyManagedChild.cpp",
207 "MyManagedParent.cpp",
208 "MyManagerChild.cpp",
209 "MyManagerParent.cpp",
212 include("/ipc/chromium/chromium-config.mozbuild")
214 ``chromium-config.mozbuild`` sets up paths so that generated IPDL header files
215 are in the proper scope. If it isn't included, the build will fail with
216 ``#include`` errors in both your actor code and some internal ipc headers. For
221 c:/mozilla-src/mozilla-unified/obj-64/dist/include\ipc/IPCMessageUtils.h(13,10): fatal error: 'build/build_config.h' file not found
223 ``.ipdl`` files are compiled to C++ files as one of the earliest post-configure
224 build steps. Those files are, in turn, referenced throughout the source code
225 and build process. From ``PMyManager.ipdl`` the compiler generates two header
226 files added to the build context and exported globally:
227 ``mozilla/myns/PMyManagerParent.h`` and ``mozilla/myns/PMyManagerChild.h``, as
228 discussed in `Namespaces`_ below. These files contain the base classes for the
229 actors. It also makes several other files, including C++ source files and
230 another header, that are automatically included into the build and should not
233 C++ definions of the actors are required for IPDL. They define the actions
234 that are taken in response to messages -- without this, they would have no
235 value. There will be much more on this when we discuss `Actors and Messages in
236 C++`_ but note here that C++ header files named for the actor are required by
237 the IPDL `compiler`. The example would expect
238 ``mozilla/myns/MyManagedChild.h``, ``mozilla/myns/MyManagedParent.h``,
239 ``mozilla/myns/MyManagerChild.h`` and ``mozilla/myns/MyManagerParent.h`` and
240 will not build without them.
242 Referencing Externally Defined Data Types: IPDL Includes
243 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
245 Let's begin with ``PMyManager.ipdl``. It starts by including types that it
246 will need from other places:
250 include protocol PMyManaged;
251 include MyTypes; // for MyActorPair
253 using MyActorEnum from "mozilla/myns/MyActorUtils.h";
254 using struct mozilla::myns::MyData from "mozilla/MyDataTypes.h";
255 [MoveOnly] using mozilla::myns::MyOtherData from "mozilla/MyDataTypes.h";
256 [RefCounted] using class mozilla::myns::MyThirdData from "mozilla/MyDataTypes.h";
258 The first line includes a protocol that PMyManager will manage. That protocol
259 is defined in its own ``.ipdl`` file. Cyclic references are expected and pose
262 The second line includes the file ``MyTypes.ipdlh``, which defines types like
263 structs and unions, but in IPDL, which means they have behavior that goes
264 beyond the similar C++ concepts. Details can be found in `Generating
265 IPDL-Aware C++ Data Types: IPDL Structs and Unions`_.
267 The final lines include types from C++ headers. Additionally, the [RefCounted]
268 and [MoveOnly] attributes tell IPDL that the types have special functionality
269 that is important to operations. These are the data type attributes currently
272 ================ ==============================================================
273 ``[RefCounted]`` Type ``T`` is reference counted (by ``AddRef``/``Release``).
274 As a parameter to a message or as a type in IPDL
275 structs/unions, it is referenced as a ``RefPtr<T>``.
276 ``[MoveOnly]`` The type ``T`` is treated as uncopyable. When used as a
277 parameter in a message or an IPDL struct/union, it is as an
279 ================ ==============================================================
281 Finally, note that ``using``, ``using class`` and ``using struct`` are all
282 valid syntax. The ``class`` and ``struct`` keywords are optional.
294 // ... data type and actor definitions ...
297 } // namespace mozilla
300 Namespaces work similar to the way they do in C++. They also mimic the
301 notation, in an attempt to make them comfortable to use. When IPDL actors are
302 compiled into C++ actors, the namespace scoping is carried over. As previously
303 noted, when C++ types are included into IPDL files, the same is true. The most
304 important way in which they differ is that IPDL also uses the namespace to
305 establish the path to the generated files. So, the example defines the IPDL
306 data type ``mozilla::myns::MyUnion`` and the actors
307 ``mozilla::myns::PMyManagerParent`` and ``mozilla::myns::PMyManagerChild``,
308 which can be included from ``mozilla/myns/PMyManagerParent.h``,
309 ``mozilla/myns/PMyManagerParent.h`` and ``mozilla/myns/PMyManagerChild.h``,
310 respectively. The namespace becomes part of the path.
312 Generating IPDL-Aware C++ Data Types: IPDL Structs and Unions
313 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
315 ``PMyManager.ipdl`` and ``MyTypes.ipdlh`` define:
319 [Comparable] union MyUnion {
326 nullable PMyManaged actor2;
329 From these descriptions, IPDL generates C++ classes that approximate the
330 behavior of C++ structs and unions but that come with pre-defined
331 ``ParamTraits`` implementations. These objects can also be used as usual
332 outside of IPDL, although the lack of control over the generated code means
333 they are sometimes poorly suited to use as plain data. See `ParamTraits`_ for
336 The ``[Comparable]`` attribute tells IPDL to generate ``operator==`` and
337 ``operator!=`` for the new type. In order for it to do that, the fields inside
338 the new type need to define both of those operators.
340 Finally, the ``nullable`` keyword indicates that, when serialized, the actor
341 may be null. It is intended to help users avoid null-object dereference
342 errors. It only applies to actor types and may also be attached to parameters
343 in message declarations.
348 The real point of any ``.ipdl`` file is that each defines exactly one actor
349 protocol. The definition always matches the ``.ipdl`` filename. Repeating the
350 one in ``PMyManager.ipdl``:
354 sync protocol PMyManager {
358 // ... more message declarations ...
362 A form of reference counting is `always` used internally by IPDL to make
363 sure that it and its clients never address an actor the other component
364 deleted but this becomes fragile, and sometimes fails, when the client code
365 does not respect the reference count. For example, when IPDL detects that
366 a connection died due to a crashed remote process, deleting the actor could
367 leave dangling pointers, so IPDL `cannot` delete it. On the other hand,
368 there are many cases where IPDL is the only entity to have references to
369 some actors (this is very common for one side of a managed actor) so IPDL
370 `must` delete it. If all of those objects were reference counted then
371 there would be no complexity here. Indeed, new actors using
372 ``[ManualDealloc]`` should not be approved without a very compelling
373 reason. New ``[ManualDealloc]`` actors may soon be forbidden.
375 The ``sync`` keyword tells IPDL that the actor contains messages that block the
376 sender using ``sync`` blocking, so the sending thread waits for a response to
377 the message. There is more on what it and the other blocking modes mean in
378 `IPDL messages`_. For now, just know that this is redundant information whose
379 value is primarily in making it easy for other developers to know that there
380 are ``sync`` messages defined here. This list gives preliminary definitions of
381 the options for the actor-blocking policy of messages:
383 ======================= =======================================================
384 ``async`` Actor may contain only asynchronous messages.
385 ``sync`` Actor has ``async`` capabilities and adds ``sync``
386 messages. ``sync`` messages
387 can only be sent from the child actor to the parent.
388 ``intr`` (deprecated) Actor has ``sync`` capabilities and adds ``intr``
389 messages. Some messages can be received while an actor
390 waits for an ``intr`` response. This type will be
392 ======================= =======================================================
394 Beyond these protocol blocking strategies, IPDL supports annotations that
395 indicate the actor has messages that may be received in an order other than
396 the one they were sent in. These orderings attempt to handle messages in
397 "message thread" order (as in e.g. mailing lists). These behaviors can be
398 difficult to design for. Their use is discouraged but is sometimes warranted.
399 They will be discussed further in `Nested messages`_.
401 ============================== ================================================
402 ``[NestedUpTo=inside_sync]`` Actor has high priority messages that can be
403 handled while waiting for a ``sync`` response.
404 ``[NestedUpTo=inside_cpow]`` Actor has the highest priority messages that
405 can be handled while waiting for a ``sync``
407 ============================== ================================================
409 The ``manages`` clause tells IPDL that ``PMyManager`` manages the
410 ``PMyManaged`` actor that was previously ``include`` d. As with any managed
411 protocol, it must also be the case that ``PMyManaged.ipdl`` includes
412 ``PMyManager`` and declares that ``PMyManaged`` is ``managed`` by
413 ``PMyManager``. Recalling the code:
418 include protocol PMyManager;
421 protocol PMyManaged {
426 An actor has a ``manager`` (e.g. ``PMyManaged``) or else it is a top-level
427 actor (e.g. ``PMyManager``). An actor protocol may be managed by more than one
428 actor type. For example, ``PMyManaged`` could have also been managed by some
429 ``PMyOtherManager`` not shown here. In that case, ``manager`` s are presented
430 in a list, separated by ``or`` -- e.g. ``manager PMyManager or
431 PMyOtherManager``. Of course, an **instance** of a managed actor type has only
432 one manager actor (and is therefore managed by only one of the types of
433 manager). The manager of an instance of a managee is always the actor that
434 constructed that managee.
436 Finally, there is the message declaration ``async PMyManaged()``. This message
437 is a constructor for ``MyManaged`` actors; unlike C++ classes, it is found in
438 ``MyManager``. Every manager will need to expose constructors to create its
439 managed types. These constructors are the only way to create an actor that is
440 managed. They can take parameters and return results, like normal messages.
441 The implementation of IPDL constructors are discussed in `Actor Lifetimes in
444 We haven't discussed a way to construct new top level actors. This is a more
445 advanced topic and is covered separately in `Top Level Actors`_.
447 .. _IPDL messages: `Declaring IPDL Messages`_
449 Declaring IPDL Messages
450 ~~~~~~~~~~~~~~~~~~~~~~~
452 The final part of the actor definition is the declaration of messages:
456 sync protocol PMyManager {
459 async __delete__(nsString aNote);
460 sync SomeMsg(MyActorPair? aActors, MyData[] aMyData)
461 returns (int32_t x, int32_t y, MyUnion aUnion);
464 [Tainted] async AnotherMsg(MyActorEnum aEnum, int32_t aNumber)
465 returns (MyOtherData aOtherData);
468 The messages are grouped into blocks by ``parent:``, ``child:`` and ``both:``.
469 These labels work the way ``public:`` and ``private:`` work in C++ -- messages
470 after these descriptors are sent/received (only) in the direction specified.
473 As a mnemonic to remember which direction they indicate, remember to put
474 the word "to" in front of them. So, for example, ``parent:`` precedes
475 ``__delete__``, meaning ``__delete__`` is sent from the child **to** the
476 parent, and ``both:`` states that ``AnotherMsg`` can be sent **to** either
479 IPDL messages support the following annotations:
481 ======================== ======================================================
482 ``[Compress]`` Indicates repeated messages of this type will
484 ``[Tainted]`` Parameters are required to be validated before using
486 ``[Priority=Foo]`` Priority of ``MessageTask`` that runs the C++ message
487 handler. ``Foo`` is one of: ``normal``, ``input``,
488 ``vsync``, ``mediumhigh``, or ``control``.
489 See the ``IPC::Message::PriorityValue`` enum.
490 ``[Nested=inside_sync]`` Indicates that the message can sometimes be handled
491 while a sync message waits for a response.
492 ``[Nested=inside_cpow]`` Indicates that the message can sometimes be handled
493 while a sync message waits for a response.
494 ``[LazySend]`` Messages with this annotation will be queued up to be
495 sent together either immediately before a non-LazySend
496 message, or from a direct task.
497 ======================== ======================================================
499 ``[Compress]`` provides crude protection against spamming with a flood of
500 messages. When messages of type ``M`` are compressed, the queue of unprocessed
501 messages between actors will never contain an ``M`` beside another one; they
502 will always be separated by a message of a different type. This is achieved by
503 throwing out the older of the two messages if sending the new one would break
504 the rule. This has been used to throttle pointer events between the main and
507 ``[Compress=all]`` is similar but applies whether or not the messages are
508 adjacent in the message queue.
510 ``[Tainted]`` is a C++ mechanism designed to encourage paying attentiton to
511 parameter security. The values of tainted parameters cannot be used until you
512 vouch for their safety. They are discussed in `Actors and Messages in C++`_.
514 The ``Nested`` annotations are deeply related to the message's blocking policy
515 that follows it and which was briefly discussed in `Defining Actors`_. See
516 `Nested messages`_ for details.
518 ``[LazySend]`` indicates the message doesn't need to be sent immediately, and
519 can be sent later, from a direct task. Worker threads which do not support
520 direct task dispatch will ignore this attribute. Messages with this annotation
521 will still be delivered in-order with other messages, meaning that if a normal
522 message is sent, any queued ``[LazySend]`` messages will be sent first. The
523 attribute allows the transport layer to combine messages to be sent together,
524 potentially reducing thread wake-ups for I/O and receiving threads.
526 The following is a complete list of the available blocking policies. It
527 resembles the list in `Defining Actors`_:
529 ====================== ========================================================
530 ``async`` Actor may contain only asynchronous messages.
531 ``sync`` Actor has ``async`` capabilities and adds ``sync``
532 messages. ``sync`` messages can only be sent from the
533 child actor to the parent.
534 ``intr`` (deprecated) Actor has ``sync`` capabilities and adds ``intr``
535 messages. This type will be removed soon.
536 ====================== ========================================================
538 The policy defines whether an actor will wait for a response when it sends a
539 certain type of message. A ``sync`` actor will wait immediately after sending
540 a ``sync`` message, stalling its thread, until a response is received. This is
541 an easy source of browser stalls. It is rarely required that a message be
542 synchronous. New ``sync`` messages are therefore required to get approval from
543 an IPC peer. The IPDL compiler will require such messages to be listed in the
544 file ``sync-messages.ini``.
546 The notion that only child actors can send ``sync`` messages was introduced to
547 avoid potential deadlocks. It relies on the belief that a cycle (deadlock) of
548 sync messages is impossible because they all point in one direction. This is
549 no longer the case because any endpoint can be a child `or` parent and some,
550 like the main process, sometimes serve as both. This means that sync messages
551 should be used with extreme care.
554 The notion of sync messages flowing in one direction is still the main
555 mechanism IPDL uses to avoid deadlock. New actors should avoid violating
556 this rule as the consequences are severe (and complex). Actors that break
557 these rules should not be approved without **extreme** extenuating
558 circumstances. If you think you need this, check with the IPC team on
559 Element first (#ipc).
561 An ``async`` actor will not wait. An ``async`` response is essentially
562 identical to sending another ``async`` message back. It may be handled
563 whenever received messages are handled. The value over an ``async`` response
564 message comes in the ergonomics -- async responses are usually handled by C++
565 lambda functions that are more like continuations than methods. This makes
566 them easier to write and to read. Additionally, they allow a response to
567 return message failure, while there would be no such response if we were
568 expecting to send a new async message back, and it failed.
570 Following synchronization is the name of the message and its parameter list.
571 The message ``__delete__`` stands out as strange -- indeed, it terminates the
572 actor's connection. `It does not delete any actor objects itself!` It severs
573 the connections of the actor `and any actors it manages` at both endpoints. An
574 actor will never send or receive any messages after it sends or receives a
575 ``__delete__``. Note that all sends and receives have to happen on a specific
576 *worker* thread for any actor tree so the send/receive order is well defined.
577 Anything sent after the actor processes ``__delete__`` is ignored (send returns
578 an error, messages yet to be received fail their delivery). In other words,
579 some future operations may fail but no unexpected behavior is possible.
581 In our example, the child can break the connection by sending ``__delete__`` to
582 the parent. The only thing the parent can do to sever the connection is to
583 fail, such as by crashing. This sort of unidirectional control is both common
586 ``PMyManaged()`` is a managed actor constructor. Note the asymmetry -- an
587 actor contains its managed actor's constructors but its own destructor.
589 The list of parameters to a message is fairly straight-forward. Parameters
590 can be any type that has a C++ ``ParamTraits`` specialization and is imported
591 by a directive. That said, there are some surprises in the list of messages:
593 ================= =============================================================
594 ``int32_t``,... The standard primitive types are included. See `builtin.py`_
595 for a list. Pointer types are, unsurprisingly, forbidden.
596 ``?`` When following a type T, the parameter is translated into
598 ``[]`` When following a type T, the parameter is translated into
599 ``nsTArray<T>`` in C++.
600 ================= =============================================================
602 Finally, the returns list declares the information sent in response, also as a
603 tuple of typed parameters. As previously mentioned, even ``async`` messages
604 can receive responses. A ``sync`` message will always wait for a response but
605 an ``async`` message will not get one unless it has a ``returns`` clause.
607 This concludes our tour of the IPDL example file. The connection to C++ is
608 discussed in the next chapter; messages in particular are covered in `Actors
609 and Messages in C++`_. For suggestions on best practices when designing your
610 IPDL actor approach, see `IPDL Best Practices`_.
612 .. _builtin.py: https://searchfox.org/mozilla-central/source/ipc/ipdl/ipdl/builtin.py
614 IPDL Syntax Quick Reference
615 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
617 The following is a list of the keywords and operators that have been introduced
618 for use in IPDL files:
620 ============================= =================================================
621 ``include`` Include a C++ header (quoted file name) or
622 ``.ipdlh`` file (unquoted with no file suffix).
623 ``using (class|struct) from`` Similar to ``include`` but imports only a
625 ``include protocol`` Include another actor for use in management
626 statements, IPDL data types or as parameters to
628 ``[RefCounted]`` Indicates that the imported C++ data types are
629 reference counted. Refcounted types require a
630 different ``ParamTraits`` interface than
631 non-reference-counted types.
632 ``[ManualDealloc]`` Indicates that the IPDL interface uses the legacy
633 manual allocation/deallocation interface, rather
634 than modern reference counting.
635 ``[MoveOnly]`` Indicates that an imported C++ data type should
636 not be copied. IPDL code will move it instead.
637 ``namespace`` Specifies the namespace for IPDL generated code.
638 ``union`` An IPDL union definition.
639 ``struct`` An IPDL struct definition.
640 ``[Comparable]`` Indicates that IPDL should generate
641 ``operator==`` and ``operator!=`` for the given
643 ``nullable`` Indicates that an actor reference in an IPDL type
644 may be null when sent over IPC.
645 ``protocol`` An IPDL protocol (actor) definition.
646 ``sync/async`` These are used in two cases: (1) to indicate
647 whether a message blocks as it waits for a result
648 and (2) because an actor that contains ``sync``
649 messages must itself be labeled ``sync`` or
651 ``[NestedUpTo=inside_sync]`` Indicates that an actor contains
652 [Nested=inside_sync] messages, in addition to
654 ``[NestedUpTo=inside_cpow]`` Indicates that an actor contains
655 [Nested=inside_cpow] messages, in addition to
657 ``intr`` Used to indicate either that (1) an actor
658 contains ``sync``, ``async`` and (deprecated)
659 ``intr`` messages, or (2) a message is ``intr``
661 ``[Nested=inside_sync]`` Indicates that the message can be handled while
662 waiting for lower-priority, or in-message-thread,
664 ``[Nested=inside_cpow]`` Indicates that the message can be handled while
665 waiting for lower-priority, or in-message-thread,
666 sync responses. Cannot be sent by the parent
668 ``manager`` Used in a protocol definition to indicate that
669 this actor manages another one.
670 ``manages`` Used in a protocol definition to indicate that
671 this actor is managed by another one.
672 ``or`` Used in a ``manager`` clause for actors that have
673 multiple potential managers.
674 ``parent: / child: / both:`` Indicates direction of subsequent actor messages.
675 As a mnemonic to remember which direction they
676 indicate, put the word "to" in front of them.
677 ``returns`` Defines return values for messages. All types
678 of message, including ``async``, support
680 ``__delete__`` A special message that destroys the related
681 actors at both endpoints when sent.
682 ``Recv__delete__`` and ``ActorDestroy`` are
683 called before destroying the actor at the other
684 endpoint, to allow for cleanup.
685 ``int32_t``,... The standard primitive types are included.
686 ``String`` Translated into ``nsString`` in C++.
687 ``?`` When following a type T in an IPDL data structure
688 or message parameter,
689 the parameter is translated into ``Maybe<T>`` in
691 ``[]`` When following a type T in an IPDL data structure
692 or message parameter,
693 the parameter is translated into ``nsTArray<T>``
695 ``[Tainted]`` Used to indicate that a message's handler should
696 receive parameters that it is required to
697 manually validate. Parameters of type ``T``
698 become ``Tainted<T>`` in C++.
699 ``[Compress]`` Indicates repeated messages of this type will
700 consolidate. When two messages of this type are
701 sent and end up side-by-side in the message queue
702 then the older message is discarded (not sent).
703 ``[Compress=all]`` Like ``[Compress]`` but discards the older
704 message regardless of whether they are adjacent
705 in the message queue.
706 ``[Priority=Foo]`` Priority of ``MessageTask`` that runs the C++
707 message handler. ``Foo`` is one of: ``normal``,
708 ``input``, ``vsync``, ``mediumhigh``, or
710 ``[LazySend]`` Messages with this annotation will be queued up to
711 be sent together immediately before a non-LazySend
712 message, or from a direct task.
713 ``[ChildImpl="RemoteFoo"]`` Indicates that the child side implementation of
714 the actor is a class named ``RemoteFoo``, and the
715 definition is included by one of the
716 ``include "...";`` statements in the file.
717 *New uses of this attribute are discouraged.*
718 ``[ParentImpl="FooImpl"]`` Indicates that the parent side implementation of
719 the actor is a class named ``FooImpl``, and the
720 definition is included by one of the
721 ``include "...";`` statements in the file.
722 *New uses of this attribute are discouraged.*
723 ``[ChildImpl=virtual]`` Indicates that the child side implementation of
724 the actor is not exported by a header, so virtual
725 ``Recv`` methods should be used instead of direct
726 function calls. *New uses of this attribute are
728 ``[ParentImpl=virtual]`` Indicates that the parent side implementation of
729 the actor is not exported by a header, so virtual
730 ``Recv`` methods should be used instead of direct
731 function calls. *New uses of this attribute are
733 ============================= =================================================
742 Before discussing how C++ represents actors and messages, we look at how IPDL
743 connects to the imported C++ data types. In order for any C++ type to be
744 (de)serialized, it needs an implementation of the ``ParamTraits`` C++ type
745 class. ``ParamTraits`` is how your code tells IPDL what bytes to write to
746 serialize your objects for sending, and how to convert those bytes back to
747 objects at the other endpoint. Since ``ParamTraits`` need to be reachable by
748 IPDL code, they need to be declared in a C++ header and imported by your
749 protocol file. Failure to do so will result in a build error.
751 Most basic types and many essential Mozilla types are always available for use
752 without inclusion. An incomplete list includes: C++ primitives, strings
753 (``std`` and ``mozilla``), vectors (``std`` and ``mozilla``), ``RefPtr<T>``
754 (for serializable ``T``), ``UniquePtr<T>``, ``nsCOMPtr<T>``, ``nsTArray<T>``,
755 ``std::unordered_map<T>``, ``nsresult``, etc. See `builtin.py
756 <https://searchfox.org/mozilla-central/source/ipc/ipdl/ipdl/builtin.py>`_,
758 <https://searchfox.org/mozilla-central/source/ipc/chromium/src/chrome/common/ipc_message_utils.h>`_
759 and `IPCMessageUtilsSpecializations.h
760 <https://searchfox.org/mozilla-central/source/ipc/glue/IPCMessageUtilsSpecializations.h>`_.
762 ``ParamTraits`` typically bootstrap with the ``ParamTraits`` of more basic
763 types, until they hit bedrock (e.g. one of the basic types above). In the most
764 extreme cases, a ``ParamTraits`` author may have to resort to designing a
765 binary data format for a type. Both options are available.
767 We haven't seen any of this C++ yet. Let's look at the data types included
768 from ``MyDataTypes.h``:
773 namespace mozilla::myns {
777 MyData(); // IPDL requires the default constructor to be public
780 struct MoveonlyData {
782 MoveonlyData& operator=(const MoveonlyData&) = delete;
784 MoveonlyData(MoveonlyData&& m);
785 MoveonlyData& operator=(MoveonlyData&& m);
788 typedef MoveonlyData MyOtherData;
792 NS_INLINE_DECL_REFCOUNTING(MyUnusedData)
800 struct ParamTraits<mozilla::myns::MyData> {
801 typedef mozilla::myns::MyData paramType;
802 static void Write(MessageWriter* m, const paramType& in);
803 static bool Read(MessageReader* m, paramType* out);
808 struct ParamTraits<mozilla::myns::MyOtherData> {
809 typedef mozilla::myns::MyOtherData paramType;
810 static void Write(MessageWriter* m, const paramType& in);
811 static bool Read(MessageReader* m, paramType* out);
816 struct ParamTraits<mozilla::myns::MyUnusedData*> {
817 typedef mozilla::myns::MyUnusedData paramType;
818 static void Write(MessageWriter* m, paramType* in);
819 static bool Read(MessageReader* m, RefPtr<paramType>* out);
823 MyData is a struct and MyOtherData is a typedef. IPDL is fine with both.
824 Additionally, MyOtherData is not copyable, matching its IPDL ``[MoveOnly]``
827 ``ParamTraits`` are required to be defined in the ``IPC`` namespace. They must
828 contain a ``Write`` method with the proper signature that is used for
829 serialization and a ``Read`` method, again with the correct signature, for
832 Here we have three examples of declarations: one for an unannotated type, one
833 for ``[MoveOnly]`` and a ``[RefCounted]`` one. Notice the difference in the
834 ``[RefCounted]`` type's method signatures. The only difference that may not be
835 clear from the function types is that, in the non-reference-counted case, a
836 default-constructed object is supplied to ``Read`` but, in the
837 reference-counted case, ``Read`` is given an empty ``RefPtr<MyUnusedData>`` and
838 should only allocate a ``MyUnusedData`` to return if it so desires.
840 These are straight-forward implementations of the ``ParamTraits`` methods for
845 /* static */ void IPC::ParamTraits<MyData>::Write(MessageWriter* m, const paramType& in) {
847 m->WriteBytes(in.bytes, sizeof(in.bytes));
849 /* static */ bool IPC::ParamTraits<MyData>::Read(MessageReader* m, paramType* out) {
850 return ReadParam(m, &out->s) &&
851 m->ReadBytesInto(out->bytes, sizeof(out->bytes));
854 ``WriteParam`` and ``ReadParam`` call the ``ParamTraits`` for the data you pass
855 them, determined using the type of the object as supplied. ``WriteBytes`` and
856 ``ReadBytesInto`` work on raw, contiguous bytes as expected. ``MessageWriter``
857 and ``MessageReader`` are IPDL internal objects which hold the incoming/outgoing
858 message as a stream of bytes and the current spot in the stream. It is *very*
859 rare for client code to need to create or manipulate these objects. Their
860 advanced use is beyond the scope of this document.
863 Potential failures in ``Read`` include everyday C++ failures like
864 out-of-memory conditions, which can be handled as usual. But ``Read`` can
865 also fail due to things like data validation errors. ``ParamTraits`` read
866 data that is considered insecure. It is important that they catch
867 corruption and properly handle it. Returning false from ``Read`` will
868 usually result in crashing the process (everywhere except in the main
869 process). This is the right behavior as the browser would be in an
870 unexpected state, even if the serialization failure was not malicious
871 (since it cannot process the message). Other responses, such as failing
872 with a crashing assertion, are inferior. IPDL fuzzing relies on
873 ``ParamTraits`` not crashing due to corruption failures.
874 Occasionally, validation will require access to state that ``ParamTraits``
875 can't easily reach. (Only) in those cases, validation can be reasonably
876 done in the message handler. Such cases are a good use of the ``Tainted``
877 annotation. See `Actors and Messages in C++`_ for more.
880 In the past, it was required to specialize ``mozilla::ipc::IPDLParamTraits<T>``
881 instead of ``IPC::ParamTraits<T>`` if you needed the actor object itself during
882 serialization or deserialization. These days the actor can be fetched using
883 ``IPC::Message{Reader,Writer}::GetActor()`` in ``IPC::ParamTraits``, so that
884 trait should be used for all new serializations.
886 A special case worth mentioning is that of enums. Enums are a common source of
887 security holes since code is rarely safe with enum values that are not valid.
888 Since data obtained through IPDL messages should be considered tainted, enums
889 are of principal concern. ``ContiguousEnumSerializer`` and
890 ``ContiguousEnumSerializerInclusive`` safely implement ``ParamTraits`` for
891 enums that are only valid for a contiguous set of values, which is most of
892 them. The generated ``ParamTraits`` confirm that the enum is in valid range;
893 ``Read`` will return false otherwise. As an example, here is the
894 ``MyActorEnum`` included from ``MyActorUtils.h``:
898 enum MyActorEnum { e1, e2, e3, e4, e5 };
901 struct ParamTraits<MyActorEnum>
902 : public ContiguousEnumSerializerInclusive<MyActorEnum, MyActorEnum::e1, MyActorEnum::e5> {};
904 IPDL Structs and Unions in C++
905 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
907 IPDL structs and unions become C++ classes that provide interfaces that are
908 fairly self-explanatory. Recalling ``MyUnion`` and ``MyActorPair`` from
909 `IPDL Structs and Unions`_ :
920 nullable PMyManaged actor2;
928 enum Type { Tfloat, TMyOtherData };
931 MyUnion(MyOtherData&& aOD);
932 MyUnion& operator=(float f);
933 MyUnion& operator=(MyOtherData&& aOD);
935 operator MyOtherData&();
939 MyActorPair(PMyManagedParent* actor1Parent, PMyManagedChild* actor1Child,
940 PMyManagedParent* actor2Parent, PMyManagedChild* actor2Child);
941 // Exactly one of { actor1Parent(), actor1Child() } must be non-null.
942 PMyManagedParent*& actor1Parent();
943 PMyManagedChild*& actor1Child();
944 // As nullable, zero or one of { actor2Parent(), actor2Child() } will be non-null.
945 PMyManagedParent*& actor2Parent();
946 PMyManagedChild*& actor2Child();
949 The generated ``ParamTraits`` use the ``ParamTraits`` for the types referenced
950 by the IPDL struct or union. Fields respect any annotations for their type
951 (see `IPDL Includes`_). For example, a ``[RefCounted]`` type ``T`` generates
952 ``RefPtr<T>`` fields.
954 Note that actor members result in members of both the parent and child actor
955 types, as seen in ``MyActorPair``. When actors are used to bridge processes,
956 only one of those could ever be used at a given endpoint. IPDL makes sure
957 that, when you send one type (say, ``PMyManagedChild``), the adjacent actor of
958 the other type (``PMyManagedParent``) is received. This is not only true for
959 message parameters and IPDL structs/unions but also for custom ``ParamTraits``
960 implementations. If you ``Write`` a ``PFooParent*`` then you must ``Read`` a
961 ``PFooChild*``. This is hard to confuse in message handlers since they are
962 members of a class named for the side they operate on, but this cannot be
963 enforced by the compiler. If you are writing
964 ``MyManagerParent::RecvSomeMsg(Maybe<MyActorPair>&& aActors, nsTArray<MyData>&& aMyData)``
965 then the ``actor1Child`` and ``actor2Child`` fields cannot be valid since the
966 child (usually) exists in another process.
968 .. _IPDL Structs and Unions: `Generating IPDL-Aware C++ Data Types: IPDL Structs and Unions`_
969 .. _IPDL Includes: `Referencing Externally Defined Data Types: IPDL Includes`_
971 Actors and Messages in C++
972 ~~~~~~~~~~~~~~~~~~~~~~~~~~
974 As mentioned in `Using The IPDL compiler`_, the IPDL compiler generates two
975 header files for the protocol ``PMyManager``: ``PMyManagerParent.h`` and
976 ``PMyManagerChild.h``, which declare the actor's base classes. There, we
977 discussed how the headers are visible to C++ components that include
978 ``chromium-config.mozbuild``. We, in turn, always need to define two files
979 that declare our actor implementation subclasses (``MyManagerParent.h`` and
980 ``MyManagerChild.h``). The IPDL file looked like this:
982 .. literalinclude:: _static/PMyManager.ipdl
984 :name: PMyManager.ipdl
986 So ``MyManagerParent.h`` looks like this:
990 #include "PMyManagerParent.h"
995 class MyManagerParent : public PMyManagerParent {
996 NS_INLINE_DECL_REFCOUNTING(MyManagerParent, override)
998 IPCResult Recv__delete__(const nsString& aNote);
999 IPCResult RecvSomeMsg(const Maybe<MyActorPair>& aActors, const nsTArray<MyData>& aMyData,
1000 int32_t* x, int32_t* y, MyUnion* aUnion);
1001 IPCResult RecvAnotherMsg(const Tainted<MyActorEnum>& aEnum, const Tainted<int32_t>& aNumber,
1002 AnotherMsgResolver&& aResolver);
1004 already_AddRefed<PMyManagerParent> AllocPMyManagedParent();
1005 IPCResult RecvPMyManagedConstructor(PMyManagedConstructor* aActor);
1011 } // namespace mozilla
1013 All messages that can be sent to the actor must be handled by ``Recv`` methods
1014 in the proper actor subclass. They should return ``IPC_OK()`` on success and
1015 ``IPC_FAIL(actor, reason)`` if an error occurred (where ``actor`` is ``this``
1016 and ``reason`` is a human text explanation) that should be considered a failure
1017 to process the message. The handling of such a failure is specific to the
1020 ``Recv`` methods are called by IPDL by enqueueing a task to run them on the
1021 ``MessageLoop`` for the thread on which they are bound. This thread is the
1022 actor's *worker thread*. All actors in a managed actor tree have the same
1023 worker thread -- in other words, actors inherit the worker thread from their
1024 managers. Top level actors establish their worker thread when they are
1025 *bound*. More information on threads can be found in `Top Level Actors`_. For
1026 the most part, client code will never engage with an IPDL actor outside of its
1029 Received parameters become stack variables that are ``std::move``-d into the
1030 ``Recv`` method. They can be received as a const l-value reference,
1031 rvalue-reference, or by value (type-permitting). ``[MoveOnly]`` types should
1032 not be received as const l-values. Return values for sync messages are
1033 assigned by writing to non-const (pointer) parameters. Return values for async
1034 messages are handled differently -- they are passed to a resolver function. In
1035 our example, ``AnotherMsgResolver`` would be a ``std::function<>`` and
1036 ``aResolver`` would be given the value to return by passing it a reference to a
1037 ``MyOtherData`` object.
1039 ``MyManagerParent`` is also capable of ``sending`` an async message that
1040 returns a value: ``AnotherMsg``. This is done with ``SendAnotherMsg``, which
1041 is defined automatically by IPDL in the base class ``PMyManagerParent``. There
1042 are two signatures for ``Send`` and they look like this:
1046 // Return a Promise that IPDL will resolve with the response or reject.
1047 RefPtr<MozPromise<MyOtherData, ResponseRejectReason, true>>
1048 SendAnotherMsg(const MyActorEnum& aEnum, int32_t aNumber);
1050 // Provide callbacks to process response / reject. The callbacks are just
1052 void SendAnotherMsg(const MyActorEnum& aEnum, int32_t aNumber,
1053 ResolveCallback<MyOtherData>&& aResolve, RejectCallback&& aReject);
1055 The response is usually handled by lambda functions defined at the site of the
1056 ``Send`` call, either by attaching them to the returned promise with e.g.
1057 ``MozPromise::Then``, or by passing them as callback parameters. See docs on
1058 ``MozPromise`` for more on its use. The promise itself is either resolved or
1059 rejected by IPDL when a valid reply is received or when the endpoint determines
1060 that the communication failed. ``ResponseRejectReason`` is an enum IPDL
1061 provides to explain failures.
1063 Additionally, the ``AnotherMsg`` handler has ``Tainted`` parameters, as a
1064 result of the [Tainted] annotation in the protocol file. Recall that
1065 ``Tainted`` is used to force explicit validation of parameters in the message
1066 handler before their values can be used (as opposed to validation in
1067 ``ParamTraits``). They therefore have access to any state that the message
1068 handler does. Their APIs, along with a list of macros that are used to
1069 validate them, are detailed `here
1070 <https://searchfox.org/mozilla-central/source/mfbt/Tainting.h>`__.
1072 Send methods that are not for async messages with return values follow a
1073 simpler form; they return a ``bool`` indicating success or failure and return
1074 response values in non-const parameters, as the ``Recv`` methods do. For
1075 example, ``PMyManagerChild`` defines this to send the sync message ``SomeMsg``:
1079 // generated in PMyManagerChild
1080 bool SendSomeMsg(const Maybe<MyActorPair>& aActors, const nsTArray<MyData>& aMyData,
1081 int32_t& x, int32_t& y, MyUnion& aUnion);
1083 Since it is sync, this method will not return to its caller until the response
1084 is received or an error is detected.
1086 All calls to ``Send`` methods, like all messages handler ``Recv`` methods, must
1087 only be called on the worker thread for the actor.
1089 Constructors, like the one for ``MyManaged``, are clearly an exception to these
1090 rules. They are discussed in the next section.
1092 .. _Actor Lifetimes in C++:
1094 Actor Lifetimes in C++
1095 ~~~~~~~~~~~~~~~~~~~~~~
1097 The constructor message for ``MyManaged`` becomes *two* methods at the
1098 receiving end. ``AllocPMyManagedParent`` constructs the managed actor, then
1099 ``RecvPMyManagedConstructor`` is called to update the new actor. The following
1100 diagram shows the construction of the ``MyManaged`` actor pair:
1104 :caption: A ``MyManaged`` actor pair being created by some ``Driver``
1105 object. Internal IPC objects in the parent and child processes
1106 are combined for compactness. Connected **par** blocks run
1107 concurrently. This shows that messages can be safely sent while
1108 the parent is still being constructed.
1110 %%{init: {'sequence': {'boxMargin': 4, 'actorMargin': 10} }}%%
1112 participant d as Driver
1113 participant mgdc as MyManagedChild
1114 participant mgrc as MyManagerChild
1115 participant ipc as IPC Child/Parent
1116 participant mgrp as MyManagerParent
1117 participant mgdp as MyManagedParent
1119 mgdc->>d: [mgd_child]
1120 d->>mgrc: SendPMyManagedConstructor<br/>[mgd_child, params]
1121 mgrc->>ipc: Form actor pair<br/>[mgd_child, params]
1123 mgdc->>ipc: early PMyManaged messages
1125 ipc->>mgrp: AllocPMyManagedParent<br/>[params]
1127 mgdp->>mgrp: [mgd_parent]
1128 ipc->>mgrp: RecvPMyManagedConstructor<br/>[mgd_parent, params]
1129 mgrp->>mgdp: initialization
1130 ipc->>mgdp: early PMyManaged messages
1132 Note over mgdc,mgdp: Bi-directional sending and receiving will now happen concurrently.
1134 The next diagram shows the destruction of the ``MyManaged`` actor pair, as
1135 initiated by a call to ``Send__delete__``. ``__delete__`` is sent from the
1136 child process because that is the only side that can call it, as declared in
1137 the IPDL protocol file.
1141 :caption: A ``MyManaged`` actor pair being disconnected due to some
1142 ``Driver`` object in the child process sending ``__delete__``.
1144 %%{init: {'sequence': {'boxMargin': 4, 'actorMargin': 10} }}%%
1146 participant d as Driver
1147 participant mgdc as MyManagedChild
1148 participant ipc as IPC Child/Parent
1149 participant mgdp as MyManagedParent
1150 d->>mgdc: Send__delete__
1151 mgdc->>ipc: Disconnect<br/>actor pair
1153 ipc->>mgdc: ActorDestroy
1156 ipc->>mgdp: Recv__delete__
1157 ipc->>mgdp: ActorDestroy
1161 Finally, let's take a look at the behavior of an actor whose peer has been lost
1162 (e.g. due to a crashed process).
1166 :caption: A ``MyManaged`` actor pair being disconnected when its peer is
1167 lost due to a fatal error. Note that ``Recv__delete__`` is not
1170 %%{init: {'sequence': {'boxMargin': 4, 'actorMargin': 10} }}%%
1172 participant mgdc as MyManagedChild
1173 participant ipc as IPC Child/Parent
1174 participant mgdp as MyManagedParent
1175 Note over mgdc: CRASH!!!
1176 ipc->>ipc: Notice fatal error.
1177 ipc->>mgdp: ActorDestroy
1180 The ``Alloc`` and ``Recv...Constructor`` methods are somewhat mirrored by
1181 ``Recv__delete__`` and ``ActorDestroy`` but there are a few differences.
1182 First, the ``Alloc`` method really does create the actor but the
1183 ``ActorDestroy`` method does not delete it. Additionally, ``ActorDestroy``
1184 is run at *both* endpoints, during ``Send__delete__`` or after
1185 ``Recv__delete__``. Finally and most importantly, ``Recv__delete__`` is only
1186 called if the ``__delete__`` message is received but it may not be if, for
1187 example, the remote process crashes. ``ActorDestroy``, on the other hand, is
1188 guaranteed to run for *every* actor unless the process terminates uncleanly.
1189 For this reason, ``ActorDestroy`` is the right place for most actor shutdown
1190 code. ``Recv__delete__`` is rarely useful, although it is occasionally
1191 beneficial to have it receive some final data.
1193 The relevant part of the parent class looks like this:
1197 class MyManagerParent : public PMyManagerParent {
1198 already_AddRefed<PMyManagedParent> AllocPMyManagedParent();
1199 IPCResult RecvPMyManagedConstructor(PMyManagedParent* aActor);
1201 IPCResult Recv__delete__(const nsString& aNote);
1202 void ActorDestroy(ActorDestroyReason why);
1207 The ``Alloc`` method is required for managed actors that are constructed by
1208 IPDL receiving a ``Send`` message. It is not required for the actor at the
1209 endpoint that calls ``Send``. The ``Recv...Constructor`` message is not
1210 required -- it has a base implementation that does nothing.
1212 If the constructor message has parameters, they are sent to both methods.
1213 Parameters are given to the ``Alloc`` method by const reference but are moved
1214 into the ``Recv`` method. They differ in that messages can be sent from the
1215 ``Recv`` method but, in ``Alloc``, the newly created actor is not yet
1218 The ``Send`` method for a constructor is similarly different from other
1219 ``Send`` methods. In the child actor, ours looks like this:
1223 IPCResult SendPMyManagedConstructor(PMyManagedChild* aActor);
1225 The method expects a ``PMyManagedChild`` that the caller will have constructed,
1226 presumably using ``new`` (this is why it does not require an ``Alloc`` method).
1227 Once ``Send...Constructor`` is called, the actor can be used to send and
1228 receive messages. It does not matter that the remote actor may not have been
1229 created yet due to asynchronicity.
1231 The destruction of actors is as unusual as their construction. Unlike
1232 construction, it is the same for managed and top-level actors. Avoiding
1233 ``[ManualDealloc]`` actors removes a lot of the complexity but there is still
1234 a process to understand. Actor destruction begins when an ``__delete__``
1235 message is sent. In ``PMyManager``, this message is declared from child to
1236 parent. The actor calling ``Send__delete__`` is no longer connected to
1237 anything when the method returns. Future calls to ``Send`` return an error
1238 and no future messages will be received. This is also the case for an actor
1239 that has run ``Recv__delete__``; it is no longer connected to the other
1243 Since ``Send__delete__`` may release the final reference to itself, it
1244 cannot safely be a class instance method. Instead, unlike other ``Send``
1245 methods, it's a ``static`` class method and takes the actor as a parameter:
1249 static IPCResult Send__delete__(PMyManagerChild* aToDelete);
1251 Additionally, the ``__delete__`` message tells IPDL to disconnect both the
1252 given actor *and all of its managed actors*. So it is really deleting the
1253 actor subtree, although ``Recv__delete__`` is only called for the actor it
1256 During the call to ``Send__delete__``, or after the call to ``Recv__delete__``,
1257 the actor's ``ActorDestroy`` method is called. This method gives client code a
1258 chance to do any teardown that must happen in `all` circumstances were it is
1259 possible -- both expected and unexpected. This means that ``ActorDestroy``
1260 will also be called when, for example, IPDL detects that the other endpoint has
1261 terminated unexpectedly, so it is releasing its reference to the actor, or
1262 because an ancestral manager (manager or manager's manager...) received a
1263 ``__delete__``. The only way for an actor to avoid ``ActorDestroy`` is for its
1264 process to crash first. ``ActorDestroy`` is always run after its actor is
1265 disconnected so it is pointless to try to send messages from it.
1267 Why use ``ActorDestroy`` instead of the actor's destructor? ``ActorDestroy``
1268 gives a chance to clean up things that are only used for communication and
1269 therefore don't need to live for however long the actor's (reference-counted)
1270 object does. For example, you might have references to shared memory (Shmems)
1271 that are no longer valid. Or perhaps the actor can now release a cache of data
1272 that was only needed for processing messages. It is cleaner to deal with
1273 communication-related objects in ``ActorDestroy``, where they become invalid,
1274 than to leave them in limbo until the destructor is run.
1276 Consider actors to be like normal reference-counted objects, but where IPDL
1277 holds a reference while the connection will or does exist. One common
1278 architecture has IPDL holding the `only` reference to an actor. This is common
1279 with actors created by sending constructor messages but the idea is available to
1280 any actor. That only reference is then released when the ``__delete__``
1281 message is sent or received.
1283 The dual of IPDL holding the only reference is to have client code hold the
1284 only reference. A common pattern to achieve this has been to override the
1285 actor's ``AddRef`` to have it send ``__delete__`` only when it's count is down
1286 to one reference (which must be IPDL if ``actor.CanSend()`` is true). A better
1287 approach would be to create a reference-counted delegate for your actor that
1288 can send ``__delete__`` from its destructor. IPDL does not guarantee that it
1289 will not hold more than one reference to your actor.
1291 .. _Top Level Actors:
1296 Recall that top level actors are actors that have no manager. They are at the
1297 root of every actor tree. There are two settings in which we use top-level
1298 actors that differ pretty dramatically. The first type are top-level actors
1299 that are created and maintained in a way that resembles managed actors, but
1300 with some important differences we will cover in this section. The second type
1301 of top-level actors are the very first actors in a new process -- these actors
1302 are created through different means and closing them (usually) terminates the
1303 process. The `new process example
1304 <https://phabricator.services.mozilla.com/D119038>`_ demonstrates both of
1305 these. It is discussed in detail in :ref:`Adding a New Type of Process`.
1307 Value of Top Level Actors
1308 ~~~~~~~~~~~~~~~~~~~~~~~~~
1310 Top-level actors are harder to create and destroy than normal actors. They
1311 used to be more heavyweight than managed actors but this has recently been
1312 dramatically reduced.
1315 Top-level actors previously required a dedicated *message channel*, which
1316 are limited OS resources. This is no longer the case -- message channels
1317 are now shared by actors that connect the same two processes. This
1318 *message interleaving* can affect message delivery latency but profiling
1319 suggests that the change was basically inconsequential.
1321 So why use a new top level actor?
1323 * The most dramatic property distinguishing top-level actors is the ability to
1324 *bind* to whatever ``EventTarget`` they choose. This means that any thread
1325 that runs a ``MessageLoop`` can use the event target for that loop as the
1326 place to send incoming messages. In other words, ``Recv`` methods would be
1327 run by that message loop, on that thread. The IPDL apparatus will
1328 asynchronously dispatch messages to these event targets, meaning that
1329 multiple threads can be handling incoming messages at the same time. The
1330 `PBackground`_ approach was born of a desire to make it easier to exploit
1331 this, although it has some complications, detailed in that section, that
1333 * Top level actors suggest modularity. Actor protocols are tough to debug, as
1334 is just about anything that spans process boundaries. Modularity can give
1335 other developers a clue as to what they need to know (and what they don't)
1336 when reading an actor's code. The alternative is proverbial *dumpster
1337 classes* that are as critical to operations (because they do so much) as they
1338 are difficult to learn (because they do so much).
1339 * Top level actors are required to connect two processes, regardless of whether
1340 the actors are the first in the process or not. As said above, the first
1341 actor is created through special means but other actors are created through
1342 messages. In Gecko, apart from the launcher and main processes, all new
1343 processes X are created with their first actor being between X and the main
1344 process. To create a connection between X and, say, a content process, the
1345 main process has to send connected ``Endpoints`` to X and to the content
1346 process, which in turn use those endpoints to create new top level actors
1347 that form an actor pair. This is discussed at length in :ref:`Connecting
1348 With Other Processes`.
1350 Top-level actors are not as frictionless as desired but they are probably
1351 under-utilized relative to their power. In cases where it is supported,
1352 ``PBackground`` is sometimes a simpler alternative to achieve the same goals.
1354 Creating Top Level Actors From Other Actors
1355 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1357 The most common way to create new top level actors is by creating a pair of
1358 connected Endpoints and sending one to the other actor. This is done exactly
1359 the way it sounds. For example:
1363 bool MyPreexistingActorParent::MakeMyActor() {
1364 Endpoint<PMyActorParent> parentEnd;
1365 Endpoint<PMyActorChild> childEnd;
1366 if (NS_WARN_IF(NS_FAILED(PMyActor::CreateEndpoints(
1367 base::GetCurrentProcId(), OtherPid(), &parentEnd, &childEnd)))) {
1368 // ... handle failure ...
1371 RefPtr<MyActorParent> parent = new MyActorParent;
1372 if (!parentEnd.Bind(parent)) {
1373 // ... handle failure ...
1377 // Do this second so we skip child if parent failed to connect properly.
1378 if (!SendCreateMyActorChild(std::move(childEnd))) {
1379 // ... assume an IPDL error will destroy parent. Handle failure beyond that ...
1385 Here ``MyPreexistingActorParent`` is used to send a child endpoint for the new
1386 top level actor to ``MyPreexistingActorChild``, after it hooks up the parent
1387 end. In this example, we bind our new actor to the same thread we are running
1388 on -- which must be the same thread ``MyPreexistingActorParent`` is bound to
1389 since we are sending ``CreateMyActorChild`` from it. We could have bound on a
1392 At this point, messages can be sent on the parent. Eventually, it will start
1393 receiving them as well.
1395 ``MyPreexistingActorChild`` still has to receive the create message. The code
1396 for that handler is pretty similar:
1400 IPCResult MyPreexistingActorChild::RecvCreateMyActorChild(Endpoint<PMyActorChild>&& childEnd) {
1401 RefPtr<MyActorChild> child = new MyActorChild;
1402 if (!childEnd.Bind(child)) {
1403 // ... handle failure and return ok, assuming a related IPDL error will alert the other side to failure ...
1409 Like the parent, the child is ready to send as soon as ``Bind`` is complete.
1410 It will start receiving messages soon afterward on the event target for the
1411 thread on which it is bound.
1413 Creating First Top Level Actors
1414 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1416 The first actor in a process is an advanced topic that is covered in
1417 :ref:`the documentation for adding a new process<Adding a New Type of Process>`.
1422 Developed as a convenient alternative to top level actors, ``PBackground`` is
1423 an IPDL protocol whose managees choose their worker threads in the child
1424 process and share a thread dedicated solely to them in the parent process.
1425 When an actor (parent or child) should run without hogging the main thread,
1426 making that actor a managee of ``PBackground`` (aka a *background actor*) is an
1430 Background actors can be difficult to use correctly, as spelled out in this
1431 section. It is recommended that other options -- namely, top-level actors
1432 -- be adopted instead.
1434 Background actors can only be used in limited circumstances:
1436 * ``PBackground`` only supports the following process connections (where
1437 ordering is parent <-> child): main <-> main, main <-> content,
1438 main <-> socket and socket <-> content.
1442 Socket process ``PBackground`` actor support was added after the other
1443 options. It has some rough edges that aren't easy to anticipate. In the
1444 future, their support may be broken out into a different actor or removed
1445 altogether. You are strongly encouraged to use new `Top Level Actors`_
1446 instead of ``PBackground`` actor when communicating with socket process
1449 * Background actor creation is always initiated by the child. Of course, a
1450 request to create one can be sent to the child by any other means.
1451 * All parent background actors run in the same thread. This thread is
1452 dedicated to serving as the worker for parent background actors. While it
1453 has no other functions, it should remain responsive to all connected
1454 background actors. For this reason, it is a bad idea to conduct long
1455 operations in parent background actors. For such cases, create a top level
1456 actor and an independent thread on the parent side instead.
1457 * Background actors are currently *not* reference-counted. IPDL's ownership
1458 has to be carefully respected and the (de-)allocators for the new actors have
1459 to be defined. See `The Old Ways`_ for details.
1461 A hypothetical layout of ``PBackground`` threads, demonstrating some of the
1462 process-type limitations, is shown in the diagram below.
1466 :caption: Hypothetical ``PBackground`` thread setup. Arrow direction
1467 indicates child-to-parent ``PBackground``-managee relationships.
1468 Parents always share a thread and may be connected to multiple
1469 processes. Child threads can be any thread, including main.
1488 st1[background parent /\nworker #1]
1494 mt1[background parent]
1497 %% PBackground connections
1516 Creating background actors is done a bit differently than normal managees. The
1517 new managed type and constructor are still added to ``PBackground.ipdl`` as
1518 with normal managees but, instead of ``new``-ing the child actor and then
1519 passing it in a ``SendFooConstructor`` call, background actors issue the send
1520 call to the ``BackgroundChild`` manager, which returns the new child:
1524 // Bind our new PMyBackgroundActorChild to the current thread.
1525 PBackgroundChild* bc = BackgroundChild::GetOrCreateForCurrentThread();
1529 PMyBackgroundActorChild* pmyBac = bac->SendMyBackgroundActor(constructorParameters);
1533 auto myBac = static_cast<MyBackgroundActorChild*>(pmyBac);
1536 ``PBackgroundParent`` still needs a ``RecvMyBackgroundActorConstructor``
1537 handler, as usual. This must be done in the ``ParentImpl`` class.
1538 ``ParentImpl`` is the non-standard name used for the implementation of
1539 ``PBackgroundParent``.
1541 To summarize, ``PBackground`` attempts to simplify a common desire in Gecko:
1542 to run tasks that communicate between the main and content processes but avoid
1543 having much to do with the main thread of either. Unfortunately, it can be
1544 complicated to use correctly and has missed on some favorable IPDL
1545 improvements, like reference counting. While top level actors are always a
1546 complete option for independent jobs that need a lot of resources,
1547 ``PBackground`` offers a compromise for some cases.
1552 IPC performance is affected by a lot of factors. Many of them are out of our
1553 control, like the influence of the system thread scheduler on latency or
1554 messages whose travel internally requires multiple legs for security reasons.
1555 On the other hand, some things we can and should control for:
1557 * Messages incur inherent performance overhead for a number of reasons: IPDL
1558 internal thread latency (e.g. the I/O thread), parameter (de-)serialization,
1559 etc. While not usually dramatic, this cost can add up. What's more, each
1560 message generates a fair amount of C++ code. For these reasons, it is wise
1561 to reduce the number of messages being sent as far as is reasonable. This
1562 can be as simple as consolidating two asynchronous messages that are always
1563 in succession. Or it can be more complex, like consolidating two
1564 somewhat-overlapping messages by merging their parameter lists and marking
1565 parameters that may not be needed as optional. It is easy to go too far down
1566 this path but careful message optimization can show big gains.
1567 * Even ``[moveonly]`` parameters are "copied" in the sense that they are
1568 serialized. The pipes that transmit the data are limited in size and require
1569 allocation. So understand that the performance of your transmission will be
1570 inversely proportional to the size of your content. Filter out data you
1571 won't need. For complex reasons related to Linux pipe write atomicity, it is
1572 highly desirable to keep message sizes below 4K (including a small amount for
1574 * On the flip side, very large messages are not permitted by IPDL and will
1575 result in a runtime error. The limit is currently 256M but message failures
1576 frequently arise even with slightly smaller messages.
1577 * Parameters to messages are C++ types and therefore can be very complex in the
1578 sense that they generally represent a tree (or graph) of objects. If this
1579 tree has a lot of objects in it, and each of them is serialized by
1580 ``ParamTraits``, then we will find that serialization is allocating and
1581 constructing a lot of objects, which will stress the allocator and cause
1582 memory fragmentation. Avoid this by using larger objects or by sharing this
1583 kind of data through careful use of shared memory.
1584 * As it is with everything, concurrency is critical to the performance of IPDL.
1585 For actors, this mostly manifests in the choice of bound thread. While
1586 adding a managed actor to an existing actor tree may be a quick
1587 implementation, this new actor will be bound to the same thread as the old
1588 one. This contention may be undesirable. Other times it may be necessary
1589 since message handlers may need to use data that isn't thread safe or may
1590 need a guarantee that the two actors' messages are received in order. Plan
1591 up front for your actor hierarchy and its thread model. Recognize when you
1592 are better off with a new top level actor or ``PBackground`` managee that
1593 facilitates processing messages simultaneously.
1594 * Remember that latency will slow your entire thread, including any other
1595 actors/messages on that thread. If you have messages that will need a long
1596 time to be processed but can run concurrently then they should use actors
1597 that run on a separate thread.
1598 * Top-level actors decide a lot of properties for their managees. Probably the
1599 most important are the process layout of the actor (including which process
1600 is "Parent" and which is "Child") and the thread. Every top-level actor
1601 should clearly document this, ideally in their .ipdl file.
1619 The ``Nested`` message annotations indicate the nesting type of the message.
1620 They attempt to process messages in the nested order of the "conversation
1621 thread", as found in e.g. a mailing-list client. This is an advanced concept
1622 that should be considered to be discouraged, legacy functionality.
1623 Essentially, ``Nested`` messages can make other ``sync`` messages break the
1624 policy of blocking their thread -- nested messages are allowed to be received
1625 while a sync messagee is waiting for a response. The rules for when a nested
1626 message can be handled are somewhat complex but they try to safely allow a
1627 ``sync`` message ``M`` to handle and respond to some special (nested) messages
1628 that may be needed for the other endpoint to finish processing ``M``. There is
1629 a `comment in MessageChannel`_ with info on how the decision to handle nested
1630 messages is made. For sync nested messages, note that this implies a relay
1631 between the endpoints, which could dramatically affect their throughput.
1633 Declaring messages to nest requires an annotation on the actor and one on the
1634 message itself. The nesting annotations were listed in `Defining Actors`_ and
1635 `Declaring IPDL Messages`_. We repeat them here. The actor annotations
1636 specify the maximum priority level of messages in the actor. It is validated
1637 by the IPDL compiler. The annotations are:
1639 ============================== ================================================
1640 ``[NestedUpTo=inside_sync]`` Indicates that an actor contains messages of
1641 priority [Nested=inside_sync] or lower.
1642 ``[NestedUpTo=inside_cpow]`` Indicates that an actor contains messages of
1643 priority [Nested=inside_cpow] or lower.
1644 ============================== ================================================
1648 The order of the nesting priorities is:
1649 (no nesting priority) < ``inside_sync`` < ``inside_cpow``.
1651 The message annotations are:
1653 ========================== ====================================================
1654 ``[Nested=inside_sync]`` Indicates that the message can be handled while
1655 waiting for lower-priority, or in-message-thread,
1657 ``[Nested=inside_cpow]`` Indicates that the message can be handled while
1658 waiting for lower-priority, or in-message-thread,
1659 sync responses. Cannot be sent by the parent actor.
1660 ========================== ====================================================
1664 ``[Nested=inside_sync]`` messages must be sync (this is enforced by the
1665 IPDL compiler) but ``[Nested=inside_cpow]`` may be async.
1667 Nested messages are obviously only interesting when sent to an actor that is
1668 performing a synchronous wait. Therefore, we will assume we are in such a
1669 state. Say ``actorX`` is waiting for a sync reply from ``actorY`` for message
1670 ``m1`` when ``actorY`` sends ``actorX`` a message ``m2``. We distinguish two
1671 cases here: (1) when ``m2`` is sent while processing ``m1`` (so ``m2`` is sent
1672 by the ``RecvM1()`` method -- this is what we mean when we say "nested") and
1673 (2) when ``m2`` is unrelated to ``m1``. Case (2) is easy; ``m2`` is only
1674 dispatched while ``m1`` waits if
1675 ``priority(m2) > priority(m1) > (no priority)`` and the message is being
1676 received by the parent, or if ``priority(m2) >= priority(m1) > (no priority)``
1677 and the message is being received by the child. Case (1) is less
1680 To analyze case (1), we again distinguish the two possible ways we can end up
1681 in the nested case: (A) ``m1`` is sent by the parent to the child and ``m2``
1682 is sent by the child to the parent, or (B) where the directions are reversed.
1683 The following tables explain what happens in all cases:
1685 .. |strike| raw:: html
1689 .. |endstrike| raw:: html
1697 .. table :: Case (A): Child sends message to a parent that is awaiting a sync response
1700 ============================== ======================== ========================================================
1701 sync ``m1`` type (from parent) ``m2`` type (from child) ``m2`` handled or rejected
1702 ============================== ======================== ========================================================
1703 sync (no priority) \* IPDL compiler error: parent cannot send sync (no priority)
1704 sync inside_sync async (no priority) |strike| ``m2`` delayed until after ``m1`` completes |endstrike| |br|
1705 Currently ``m2`` is handled during the sync wait (bug?)
1706 sync inside_sync sync (no priority) |strike| ``m2`` send fails: lower priority than ``m1`` |endstrike| |br|
1707 Currently ``m2`` is handled during the sync wait (bug?)
1708 sync inside_sync sync inside_sync ``m2`` handled during ``m1`` sync wait: same message thread and same priority
1709 sync inside_sync async inside_cpow ``m2`` handled during ``m1`` sync wait: higher priority
1710 sync inside_sync sync inside_cpow ``m2`` handled during ``m1`` sync wait: higher priority
1711 sync inside_cpow \* IPDL compiler error: parent cannot use inside_cpow priority
1712 ============================== ======================== ========================================================
1714 .. table :: Case (B): Parent sends message to a child that is awaiting a sync response
1717 ============================= ========================= ========================================================
1718 sync ``m1`` type (from child) ``m2`` type (from parent) ``m2`` handled or rejected
1719 ============================= ========================= ========================================================
1720 \* async (no priority) ``m2`` delayed until after ``m1`` completes
1721 \* sync (no priority) IPDL compiler error: parent cannot send sync (no priority)
1722 sync (no priority) sync inside_sync ``m2`` send fails: no-priority sync messages cannot handle
1723 incoming messages during wait
1724 sync inside_sync sync inside_sync ``m2`` handled during ``m1`` sync wait: same message thread and same priority
1725 sync inside_cpow sync inside_sync ``m2`` send fails: lower priority than ``m1``
1726 \* async inside_cpow IPDL compiler error: parent cannot use inside_cpow priority
1727 \* sync inside_cpow IPDL compiler error: parent cannot use inside_cpow priority
1728 ============================= ========================= ========================================================
1730 We haven't seen rule #2 from the `comment in MessageChannel`_ in action but, as
1731 the comment mentions, it is needed to break deadlocks in cases where both the
1732 parent and child are initiating message-threads simultaneously. It
1733 accomplishes this by favoring the parent's sent messages over the child's when
1734 deciding which message-thread to pursue first (and blocks the other until the
1735 first completes). Since this distinction is entirely thread-timing based,
1736 client code needs only to be aware that IPDL internals will not deadlock
1737 because of this type of race, and that this protection is limited to a single
1738 actor tree -- the parent/child messages are only well-ordered when under the
1739 same top-level actor so simultaneous sync messages across trees are still
1740 capable of deadlock.
1742 Clearly, tight control over these types of protocols is required to predict how
1743 they will coordinate within themselves and with the rest of the application
1744 objects. Control flow, and hence state, can be very difficult to predict and
1745 are just as hard to maintain. This is one of the key reasons why we have
1746 stressed that message priorities should be avoided whenever possible.
1748 .. _comment in MessageChannel: https://searchfox.org/mozilla-central/rev/077501b34cca91763ae04f4633a42fddd919fdbd/ipc/glue/MessageChannel.cpp#54-118
1750 .. _Message Logging:
1755 The environment variable ``MOZ_IPC_MESSAGE_LOG`` controls the logging of IPC
1756 messages. It logs details about the transmission and reception of messages.
1757 This isn't controlled by ``MOZ_LOG`` -- it is a separate system. Set this
1758 variable to ``1`` to log information on all IPDL messages, or specify a
1759 comma-separated list of **top-level** protocols to log (e.g.
1760 ``MOZ_IPC_MESSAGE_LOG="PMyManagerChild,PMyManagedParent,PMyManagedChild"``).
1761 :ref:`Debugging with IPDL Logging` has an example where IPDL logging is useful
1762 in tracking down a bug.
1765 The preceding ``P`` and the ``Parent`` or ``Child`` suffix are required
1766 when listing individual protocols in ``MOZ_IPC_MESSAGE_LOG``.