summaryrefslogtreecommitdiffstats
path: root/ipc/docs/ipdl.rst
blob: 3e8ace542beb4f05b7c851beac4dbe9908aa2d66 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
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 throroughly!!!

.. _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, `interrupt`_ 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, `synchronous nested`_ or `interrupt`_.  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.  Interrupt
    messages were prone to misuse and are deprecated, with removal expected in
    the near future
    (`Bug 1729044 <https://bugzilla.mozilla.org/show_bug.cgi?id=1729044>`_).

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.

.. _interrupt: `The Old Ways`_
.. _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:: c++

    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++

    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:: c++

    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:: c++

    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:: c++

    [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:: c++

    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.
``intr`` (deprecated)   Actor has ``sync`` capabilities and adds ``intr``
                        messages.  Some messages can be received while an actor
                        waits for an ``intr`` response.  This type will be
                        removed soon.
======================= =======================================================

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.
============================== ================================================

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:: c++

    // 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:: c++

    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 aNumber)
            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.
``intr`` (deprecated)  Actor has ``sync`` capabilities and adds ``intr``
                       messages.  This type will be removed soon.
====================== ========================================================

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`` or
                              ``intr``.
``[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.
``intr``                      Used to indicate either that (1) an actor
                              contains ``sync``, ``async`` and (deprecated)
                              ``intr`` messages, or (2) a message is ``intr``
                              type.
``[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.*
============================= =================================================


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:: c++

    // 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:: c++

    /* 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:: c++

    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:: c++

    union MyUnion {
        float;
        MyOtherData;
    };

    struct MyActorPair {
        PMyManaged actor1;
        nullable PMyManaged actor2;
    };

These compile to:

.. code-block:: c++

    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:: c++

    #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>& aNumber,
                                 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:: c++

    // Return a Promise that IPDL will resolve with the response or reject.
    RefPtr<MozPromise<MyOtherData, ResponseRejectReason, true>>
    SendAnotherMsg(const MyActorEnum& aEnum, int32_t aNumber);

    // Provide callbacks to process response / reject.  The callbacks are just
    // std::functions.
    void SendAnotherMsg(const MyActorEnum& aEnum, int32_t aNumber,
        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:: c++

    // 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:: c++

    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:: c++

    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:: c++

        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
therefore don't need to live for however long the actor's (reference-counted)
object does.  For example, you might have references to shared memory (Shmems)
that are no longer valid.  Or perhaps the actor can now release a cache of data
that was only needed for processing messages.  It is cleaner to deal with
communication-related objects in ``ActorDestroy``, where they become invalid,
than to leave them in limbo until the destructor is run.

Consider actors to be like normal reference-counted objects, but where IPDL
holds a reference while the connection will or does exist.  One common
architecture has IPDL holding the `only` reference to an actor.  This is common
with actors created by sending constructor messages but the idea is available to
any actor.  That only reference is then released when the ``__delete__``
message is sent or received.

The dual of IPDL holding the only reference is to have client code hold the
only reference.  A common pattern to achieve this has been to override the
actor's ``AddRef`` to have it send ``__delete__`` only when it's count is down
to one reference (which must be IPDL if ``actor.CanSend()`` is true).  A better
approach would be to create a reference-counted delegate for your actor that
can send ``__delete__`` from its destructor.  IPDL does not guarantee that it
will not hold more than one reference to your actor.

.. _Top Level Actors:

Top Level Actors
----------------

Recall that top level actors are actors that have no manager.  They are at the
root of every actor tree.  There are two settings in which we use top-level
actors that differ pretty dramatically.  The first type are top-level actors
that are created and maintained in a way that resembles managed actors, but
with some important differences we will cover in this section.  The second type
of top-level actors are the very first actors in a new process -- these actors
are created through different means and closing them (usually) terminates the
process.  The `new process example
<https://phabricator.services.mozilla.com/D119038>`_ demonstrates both of
these.  It is discussed in detail in :ref:`Adding a New Type of Process`.

Value of Top Level Actors
~~~~~~~~~~~~~~~~~~~~~~~~~

Top-level actors are harder to create and destroy than normal actors.  They
used to be more heavyweight than managed actors but this has recently been
dramatically reduced.

.. note::
    Top-level actors previously required a dedicated *message channel*, which
    are limited OS resources.  This is no longer the case -- message channels
    are now shared by actors that connect the same two processes.  This
    *message interleaving* can affect message delivery latency but profiling
    suggests that the change was basically inconsequential.

So why use a new top level actor?

* The most dramatic property distinguishing top-level actors is the ability to
  *bind* to whatever ``EventTarget`` they choose.  This means that any thread
  that runs a ``MessageLoop`` can use the event target for that loop as the
  place to send incoming messages.  In other words, ``Recv`` methods would be
  run by that message loop, on that thread.  The IPDL apparatus will
  asynchronously dispatch messages to these event targets, meaning that
  multiple threads can be handling incoming messages at the same time.  The
  `PBackground`_ approach was born of a desire to make it easier to exploit
  this, although it has some complications, detailed in that section, that
  limit its value.
* Top level actors suggest modularity.  Actor protocols are tough to debug, as
  is just about anything that spans process boundaries.  Modularity can give
  other developers a clue as to what they need to know (and what they don't)
  when reading an actor's code.  The alternative is proverbial *dumpster
  classes* that are as critical to operations (because they do so much) as they
  are difficult to learn (because they do so much).
* Top level actors are required to connect two processes, regardless of whether
  the actors are the first in the process or not.  As said above, the first
  actor is created through special means but other actors are created through
  messages.  In Gecko, apart from the launcher and main processes, all new
  processes X are created with their first actor being between X and the main
  process.  To create a connection between X and, say, a content process, the
  main process has to send connected ``Endpoints`` to X and to the content
  process, which in turn use those endpoints to create new top level actors
  that form an actor pair.  This is discussed at length in :ref:`Connecting
  With Other Processes`.

Top-level actors are not as frictionless as desired but they are probably
under-utilized relative to their power.  In cases where it is supported,
``PBackground`` is sometimes a simpler alternative to achieve the same goals.

Creating Top Level Actors From Other Actors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The most common way to create new top level actors is by creating a pair of
connected Endpoints and sending one to the other actor.  This is done exactly
the way it sounds.  For example:

.. code-block:: c++

    bool MyPreexistingActorParent::MakeMyActor() {
        Endpoint<PMyActorParent> parentEnd;
        Endpoint<PMyActorChild> childEnd;
        if (NS_WARN_IF(NS_FAILED(PMyActor::CreateEndpoints(
              base::GetCurrentProcId(), OtherPid(), &parentEnd, &childEnd)))) {
            // ... handle failure ...
            return false;
        }
        RefPtr<MyActorParent> parent = new MyActorParent;
        if (!parentEnd.Bind(parent)) {
            // ... handle failure ...
            delete parent;
            return false;
        }
        // Do this second so we skip child if parent failed to connect properly.
        if (!SendCreateMyActorChild(std::move(childEnd))) {
            // ... assume an IPDL error will destroy parent.  Handle failure beyond that ...
            return false;
        }
        return true;
    }

Here ``MyPreexistingActorParent`` is used to send a child endpoint for the new
top level actor to ``MyPreexistingActorChild``, after it hooks up the parent
end.  In this example, we bind our new actor to the same thread we are running
on -- which must be the same thread ``MyPreexistingActorParent`` is bound to
since we are sending ``CreateMyActorChild`` from it.  We could have bound on a
different thread.

At this point, messages can be sent on the parent.  Eventually, it will start
receiving them as well.

``MyPreexistingActorChild`` still has to receive the create message.  The code
for that handler is pretty similar:

.. code-block:: c++

    IPCResult MyPreexistingActorChild::RecvCreateMyActorChild(Endpoint<PMyActorChild>&& childEnd) {
        RefPtr<MyActorChild> child = new MyActorChild;
        if (!childEnd.Bind(child)) {
            // ... handle failure and return ok, assuming a related IPDL error will alert the other side to failure ...
            return IPC_OK();
        }
        return IPC_OK();
    }

Like the parent, the child is ready to send as soon as ``Bind`` is complete.
It will start receiving messages soon afterward on the event target for the
thread on which it is bound.

Creating First Top Level Actors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The first actor in a process is an advanced topic that is covered in
:ref:`the documentation for adding a new process<Adding a New Type of Process>`.

PBackground
-----------

Developed as a convenient alternative to top level actors, ``PBackground`` is
an IPDL protocol whose managees choose their worker threads in the child
process and share a thread dedicated solely to them in the parent process.
When an actor (parent or child) should run without hogging the main thread,
making that actor a managee of ``PBackground`` (aka a *background actor*) is an
option.

.. warning::
    Background actors can be difficult to use correctly, as spelled out in this
    section.  It is recommended that other options -- namely, top-level actors
    -- be adopted instead.

Background actors can only be used in limited circumstances:

* ``PBackground`` only supports the following process connections (where
  ordering is parent <-> child): main <-> main, main <-> content,
  main <-> socket and socket <-> content.

.. important::

    Socket process ``PBackground`` actor support was added after the other
    options.  It has some rough edges that aren't easy to anticipate.  In the
    future, their support may be broken out into a different actor or removed
    altogether.  You are strongly encouraged to use new `Top Level Actors`_
    instead of ``PBackground`` actor when communicating with socket process
    worker threads.

* Background actor creation is always initiated by the child.  Of course, a
  request to create one can be sent to the child by any other means.
* All parent background actors run in the same thread.  This thread is
  dedicated to serving as the worker for parent background actors.  While it
  has no other functions, it should remain responsive to all connected
  background actors.  For this reason, it is a bad idea to conduct long
  operations in parent background actors.  For such cases, create a top level
  actor and an independent thread on the parent side instead.
* Background actors are currently *not* reference-counted.  IPDL's ownership
  has to be carefully respected and the (de-)allocators for the new actors have
  to be defined.  See `The Old Ways`_ for details.

A hypothetical layout of ``PBackground`` threads, demonstrating some of the
process-type limitations, is shown in the diagram below.

.. mermaid::
    :align: center
    :caption: Hypothetical ``PBackground`` thread setup.  Arrow direction
              indicates child-to-parent ``PBackground``-managee relationships.
              Parents always share a thread and may be connected to multiple
              processes.  Child threads can be any thread, including main.

    flowchart LR
        subgraph content #1
            direction TB
            c1tm[main]
            c1t1[worker #1]
            c1t2[worker #2]
            c1t3[worker #3]
        end
        subgraph content #2
            direction TB
            c2tm[main]
            c2t1[worker #1]
            c2t2[worker #2]
        end
        subgraph socket
            direction TB
            stm[main]
            st1[background parent /\nworker #1]
            st2[worker #2]
        end
        subgraph main
            direction TB
            mtm[main]
            mt1[background parent]
        end

        %% PBackground connections
        c1tm --> mt1
        c1t1 --> mt1
        c1t2 --> mt1

        c1t3 --> mt1
        c1t3 --> st1

        c2t1 --> st1
        c2t1 --> mt1

        c2t2 --> mt1

        c2tm --> st1

        stm --> mt1
        st1 --> mt1
        st2 --> mt1

Creating background actors is done a bit differently than normal managees.  The
new managed type and constructor are still added to ``PBackground.ipdl`` as
with normal managees but, instead of ``new``-ing the child actor and then
passing it in a ``SendFooConstructor`` call, background actors issue the send
call to the ``BackgroundChild`` manager, which returns the new child:

.. code-block:: c++

    // Bind our new PMyBackgroundActorChild to the current thread.
    PBackgroundChild* bc = BackgroundChild::GetOrCreateForCurrentThread();
    if (!bc) {
        return false;
    }
    PMyBackgroundActorChild* pmyBac = bac->SendMyBackgroundActor(constructorParameters);
    if (!pmyBac) {
        return false;
    }
    auto myBac = static_cast<MyBackgroundActorChild*>(pmyBac);

.. note::
    ``PBackgroundParent`` still needs a ``RecvMyBackgroundActorConstructor``
    handler, as usual.  This must be done in the ``ParentImpl`` class.
    ``ParentImpl`` is the non-standard name used for the implementation of
    ``PBackgroundParent``.

To summarize, ``PBackground`` attempts to simplify a common desire in Gecko:
to run tasks that communicate between the main and content processes but avoid
having much to do with the main thread of either.  Unfortunately, it can be
complicated to use correctly and has missed on some favorable IPDL
improvements, like reference counting.  While top level actors are always a
complete option for independent jobs that need a lot of resources,
``PBackground`` offers a compromise for some cases.

IPDL Best Practices
-------------------

IPC performance is affected by a lot of factors.  Many of them are out of our
control, like the influence of the system thread scheduler on latency or
messages whose travel internally requires multiple legs for security reasons.
On the other hand, some things we can and should control for:

* Messages incur inherent performance overhead for a number of reasons: IPDL
  internal thread latency (e.g. the I/O thread), parameter (de-)serialization,
  etc.  While not usually dramatic, this cost can add up.  What's more, each
  message generates a fair amount of C++ code.  For these reasons, it is wise
  to reduce the number of messages being sent as far as is reasonable.  This
  can be as simple as consolidating two asynchronous messages that are always
  in succession.  Or it can be more complex, like consolidating two
  somewhat-overlapping messages by merging their parameter lists and marking
  parameters that may not be needed as optional.  It is easy to go too far down
  this path but careful message optimization can show big gains.
* Even ``[moveonly]`` parameters are "copied" in the sense that they are
  serialized.  The pipes that transmit the data are limited in size and require
  allocation.  So understand that the performance of your transmission will be
  inversely proportional to the size of your content.  Filter out data you
  won't need.  For complex reasons related to Linux pipe write atomicity, it is
  highly desirable to keep message sizes below 4K (including a small amount for
  message metadata).
* On the flip side, very large messages are not permitted by IPDL and will
  result in a runtime error.  The limit is currently 256M but message failures
  frequently arise even with slightly smaller messages.
* Parameters to messages are C++ types and therefore can be very complex in the
  sense that they generally represent a tree (or graph) of objects.  If this
  tree has a lot of objects in it, and each of them is serialized by
  ``ParamTraits``, then we will find that serialization is allocating and
  constructing a lot of objects, which will stress the allocator and cause
  memory fragmentation.  Avoid this by using larger objects or by sharing this
  kind of data through careful use of shared memory.
* As it is with everything, concurrency is critical to the performance of IPDL.
  For actors, this mostly manifests in the choice of bound thread.  While
  adding a managed actor to an existing actor tree may be a quick
  implementation, this new actor will be bound to the same thread as the old
  one.  This contention may be undesirable.  Other times it may be necessary
  since message handlers may need to use data that isn't thread safe or may
  need a guarantee that the two actors' messages are received in order.  Plan
  up front for your actor hierarchy and its thread model.  Recognize when you
  are better off with a new top level actor or ``PBackground`` managee that
  facilitates processing messages simultaneously.
* Remember that latency will slow your entire thread, including any other
  actors/messages on that thread.  If you have messages that will need a long
  time to be processed but can run concurrently then they should use actors
  that run on a separate thread.
* Top-level actors decide a lot of properties for their managees.  Probably the
  most important are the process layout of the actor (including which process
  is "Parent" and which is "Child") and the thread.  Every top-level actor
  should clearly document this, ideally in their .ipdl file.

The Old Ways
------------

TODO:

The FUD
-------

TODO:

The Rest
--------

Nested messages
~~~~~~~~~~~~~~~

The ``Nested`` message annotations indicate the nesting type of the message.
They attempt to process messages in the nested order of the "conversation
thread", as found in e.g. a mailing-list client.  This is an advanced concept
that should be considered to be discouraged, legacy functionality.
Essentially, ``Nested`` messages can make other ``sync`` messages break the
policy of blocking their thread -- nested messages are allowed to be received
while a sync messagee is waiting for a response.  The rules for when a nested
message can be handled are somewhat complex but they try to safely allow a
``sync`` message ``M`` to handle and respond to some special (nested) messages
that may be needed for the other endpoint to finish processing ``M``.  There is
a `comment in MessageChannel`_ with info on how the decision to handle nested
messages is made.  For sync nested messages, note that this implies a relay
between the endpoints, which could dramatically affect their throughput.

Declaring messages to nest requires an annotation on the actor and one on the
message itself.  The nesting annotations were listed in `Defining Actors`_ and
`Declaring IPDL Messages`_.  We repeat them here.  The actor annotations
specify the maximum priority level of messages in the actor.  It is validated
by the IPDL compiler.  The annotations are:

============================== ================================================
``[NestedUpTo=inside_sync]``   Indicates that an actor contains messages of
                               priority [Nested=inside_sync] or lower.
``[NestedUpTo=inside_cpow]``   Indicates that an actor contains messages of
                               priority [Nested=inside_cpow] or lower.
============================== ================================================

.. note::

    The order of the nesting priorities is:
    (no nesting priority) < ``inside_sync`` < ``inside_cpow``.

The message annotations are:

========================== ====================================================
``[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.
========================== ====================================================

.. note::

    ``[Nested=inside_sync]`` messages must be sync (this is enforced by the
    IPDL compiler) but ``[Nested=inside_cpow]`` may be async.

Nested messages are obviously only interesting when sent to an actor that is
performing a synchronous wait.  Therefore, we will assume we are in such a
state.  Say ``actorX`` is waiting for a sync reply from ``actorY`` for message
``m1`` when ``actorY`` sends ``actorX`` a message ``m2``.  We distinguish two
cases here: (1) when ``m2`` is sent while processing ``m1`` (so ``m2`` is sent
by the ``RecvM1()`` method -- this is what we mean when we say "nested") and
(2) when ``m2`` is unrelated to ``m1``.  Case (2) is easy; ``m2`` is only
dispatched while ``m1`` waits if
``priority(m2) > priority(m1) > (no priority)`` and the message is being
received by the parent, or if ``priority(m2) >= priority(m1) > (no priority)``
and the message is being received by the child.  Case (1) is less
straightforward.

To analyze case (1), we again distinguish the two possible ways we can end up
in the nested case: (A) ``m1`` is sent by the parent to the child and ``m2``
is sent by the child to the parent, or (B) where the directions are reversed.
The following tables explain what happens in all cases:

.. |strike| raw:: html

   <strike>

.. |endstrike| raw:: html

   </strike>

.. |br| raw:: html

   <br/>

.. table :: Case (A): Child sends message to a parent that is awaiting a sync response
    :align: center

    ==============================     ========================      ========================================================
    sync ``m1`` type (from parent)     ``m2`` type (from child)      ``m2`` handled or rejected
    ==============================     ========================      ========================================================
    sync (no priority)                 \*                            IPDL compiler error: parent cannot send sync (no priority)
    sync inside_sync                   async (no priority)           |strike| ``m2`` delayed until after ``m1`` completes |endstrike| |br|
                                                                     Currently ``m2`` is handled during the sync wait (bug?)
    sync inside_sync                   sync (no priority)            |strike| ``m2`` send fails: lower priority than ``m1`` |endstrike| |br|
                                                                     Currently ``m2`` is handled during the sync wait (bug?)
    sync inside_sync                   sync inside_sync              ``m2`` handled during ``m1`` sync wait: same message thread and same priority
    sync inside_sync                   async inside_cpow             ``m2`` handled during ``m1`` sync wait: higher priority
    sync inside_sync                   sync inside_cpow              ``m2`` handled during ``m1`` sync wait: higher priority
    sync inside_cpow                   \*                            IPDL compiler error: parent cannot use inside_cpow priority
    ==============================     ========================      ========================================================

.. table :: Case (B): Parent sends message to a child that is awaiting a sync response
    :align: center

    =============================      =========================      ========================================================
    sync ``m1`` type (from child)      ``m2`` type (from parent)      ``m2`` handled or rejected
    =============================      =========================      ========================================================
    \*                                 async (no priority)            ``m2`` delayed until after ``m1`` completes
    \*                                 sync (no priority)             IPDL compiler error: parent cannot send sync (no priority)
    sync (no priority)                 sync inside_sync               ``m2`` send fails: no-priority sync messages cannot handle
                                                                      incoming messages during wait
    sync inside_sync                   sync inside_sync               ``m2`` handled during ``m1`` sync wait: same message thread and same priority
    sync inside_cpow                   sync inside_sync               ``m2`` send fails: lower priority than ``m1``
    \*                                 async inside_cpow              IPDL compiler error: parent cannot use inside_cpow priority
    \*                                 sync inside_cpow               IPDL compiler error: parent cannot use inside_cpow priority
    =============================      =========================      ========================================================

We haven't seen rule #2 from the `comment in MessageChannel`_ in action but, as
the comment mentions, it is needed to break deadlocks in cases where both the
parent and child are initiating message-threads simultaneously.  It
accomplishes this by favoring the parent's sent messages over the child's when
deciding which message-thread to pursue first (and blocks the other until the
first completes).  Since this distinction is entirely thread-timing based,
client code needs only to be aware that IPDL internals will not deadlock
because of this type of race, and that this protection is limited to a single
actor tree -- the parent/child messages are only well-ordered when under the
same top-level actor so simultaneous sync messages across trees are still
capable of deadlock.

Clearly, tight control over these types of protocols is required to predict how
they will coordinate within themselves and with the rest of the application
objects.  Control flow, and hence state, can be very difficult to predict and
are just as hard to maintain.  This is one of the key reasons why we have
stressed that message priorities should be avoided whenever possible.

.. _comment in MessageChannel: https://searchfox.org/mozilla-central/rev/077501b34cca91763ae04f4633a42fddd919fdbd/ipc/glue/MessageChannel.cpp#54-118

.. _Message Logging:

Message Logging
~~~~~~~~~~~~~~~

The environment variable ``MOZ_IPC_MESSAGE_LOG`` controls the logging of IPC
messages.  It logs details about the transmission and reception of messages.
This isn't controlled by ``MOZ_LOG`` -- it is a separate system.  Set this
variable to ``1`` to log information on all IPDL messages, or specify a
comma-separated list of **top-level** protocols to log (e.g.
``MOZ_IPC_MESSAGE_LOG="PMyManagerChild,PMyManagedParent,PMyManagedChild"``).
:ref:`Debugging with IPDL Logging` has an example where IPDL logging is useful
in tracking down a bug.

.. important::
    The preceding ``P`` and the ``Parent`` or ``Child`` suffix are required
    when listing individual protocols in ``MOZ_IPC_MESSAGE_LOG``.