CINXE.COM

<!doctype html> <html class="writer-html5" lang="en" data-content_root="../"> <head> <base href="https://firefox-source-docs.mozilla.org/ipc/ipdl.html"> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>IPDL: Inter-Thread and Inter-Process Message Passing — Firefox Source Docs documentation</title> <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50"> <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=19f00094"> <link rel="stylesheet" type="text/css" href="../_static/graphviz.css?v=fd3f3429"> <link rel="stylesheet" type="text/css" href="../_static/copybutton.css?v=76b2166b"> <link rel="stylesheet" type="text/css" href="../_static/custom_theme.css?v=a7d3e023"> <link rel="stylesheet" type="text/css" href="../_static/design-style.1e8bd061cd6da7fc9cf755528e8ffc24.min.css?v=0a3b3ea7"> <link rel="shortcut icon" href="../_static/firefox.ico"> <script src="../_static/jquery.js?v=5d32c60e"></script> <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script> <script src="../_static/documentation_options.js?v=5929fcd5"></script> <script src="../_static/doctools.js?v=9a2dae69"></script> <script src="../_static/sphinx_highlight.js?v=dc90522c"></script> <script src="../_static/clipboard.min.js?v=a7894cd8"></script> <script src="../_static/copybutton.js?v=30646c52"></script> <script src="../_static/design-tabs.js?v=36754332"></script> <script type="module" src="https://cdn.jsdelivr.net/npm/mermaid@11.2.0/dist/mermaid.esm.min.mjs"></script> <script type="module" src="https://cdn.jsdelivr.net/npm/@mermaid-js/layout-elk@0.1.4/dist/mermaid-layout-elk.esm.min.mjs"></script> <script type="module">import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11.2.0/dist/mermaid.esm.min.mjs";import elkLayouts from "https://cdn.jsdelivr.net/npm/@mermaid-js/layout-elk@0.1.4/dist/mermaid-layout-elk.esm.min.mjs";mermaid.registerLayoutLoaders(elkLayouts);mermaid.initialize({startOnLoad:false});</script> <script src="https://cdn.jsdelivr.net/npm/d3@7.9.0/dist/d3.min.js"></script> <script type="module"> import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11.2.0/dist/mermaid.esm.min.mjs"; window.addEventListener("load", () => mermaid.run()); </script> <script src="../_static/js/theme.js"></script> <link rel="index" title="Index" href="../genindex.html"> <link rel="search" title="Search" href="../search.html"> <link rel="next" title="Gecko Processes" href="processes.html"> <link rel="prev" title="Processes, Threads and IPC" href="index.html"> <meta http-equiv="X-Translated-By" content="Google"> <meta http-equiv="X-Translated-To" content="iw"> <script type="text/javascript" src="https://www.gstatic.com/_/translate_http/_/js/k=translate_http.tr.en_GB.1hbgkFx4Qn8.O/am=DgY/d=1/rs=AN8SPfqlmAPxwfG457BPbRXwNq39oSMGHg/m=corsproxy" data-sourceurl="https://firefox-source-docs.mozilla.org/ipc/ipdl.html"></script> <link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200" rel="stylesheet"> <script type="text/javascript" src="https://www.gstatic.com/_/translate_http/_/js/k=translate_http.tr.en_GB.1hbgkFx4Qn8.O/am=DgY/d=1/exm=corsproxy/ed=1/rs=AN8SPfqlmAPxwfG457BPbRXwNq39oSMGHg/m=phishing_protection" data-phishing-protection-enabled="false" data-forms-warning-enabled="true" data-source-url="https://firefox-source-docs.mozilla.org/ipc/ipdl.html"></script> <meta name="robots" content="none"> </head> <body class="wy-body-for-nav"> <script type="text/javascript" src="https://www.gstatic.com/_/translate_http/_/js/k=translate_http.tr.en_GB.1hbgkFx4Qn8.O/am=DgY/d=1/exm=corsproxy,phishing_protection/ed=1/rs=AN8SPfqlmAPxwfG457BPbRXwNq39oSMGHg/m=navigationui" data-environment="prod" data-proxy-url="https://firefox--source--docs-mozilla-org.translate.goog" data-proxy-full-url="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB" data-source-url="https://firefox-source-docs.mozilla.org/ipc/ipdl.html" data-source-language="pl" data-target-language="iw" data-display-language="en-GB" data-detected-source-language="" data-is-source-untranslated="false" data-source-untranslated-url="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://firefox-source-docs.mozilla.org/ipc/ipdl.html&anno=2" data-client="tr"></script> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search"><a href="https://firefox--source--docs-mozilla-org.translate.goog/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB" class="icon icon-home"> Firefox Source Docs <img src="../_static/firefox-wordmark.svg" class="logo" alt="Logo"> </a> <div> <h3>Quick search</h3> <script> (function () { var cx = "dd12886298f75dbef"; var gcse = document.createElement("script"); gcse.async = true; gcse.src = "https://cse.google.com/cse.js?cx=" + cx; var s = document.getElementsByTagName("script")[0]; s.parentNode.insertBefore(gcse, s); })(); </script><gcse:search></gcse:search> </div> </div> <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> Overview <ul> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/glossary/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">A Glossary of Common Terms</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/overview/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">A Quick Guide to Mozilla Applications</a></li> </ul> Getting Started <ul> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/setup/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Getting Set Up To Work On The Firefox Codebase</a></li> </ul> Working On Firefox <ul> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/contributing/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Working on Firefox</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/bug-mgmt/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Bug Handling</a></li> </ul> Firefox User Guide <ul> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/devtools-user/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Firefox DevTools User Docs</a></li> </ul> Source Code Documentation <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/mots/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Governance</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/browser/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Firefox Front-end</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/dom/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">DOM</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/editor/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Editor</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/layout/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Style system (CSS) & Layout</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/gfx/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Graphics</a></li> <li class="toctree-l1 current"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Processes, Threads and IPC</a> <ul class="current"> <li class="toctree-l2 current"><a class="current reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#">IPDL: Inter-Thread and Inter-Process Message Passing</a> <ul> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#the-idea">The Idea</a></li> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#the-approach">The Approach</a> <ul> <li class="toctree-l4"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#the-steps-to-making-a-new-actor">The Steps To Making A New Actor</a></li> </ul></li> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#the-protocol-language">The Protocol Language</a> <ul> <li class="toctree-l4"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#using-the-ipdl-compiler">Using The IPDL compiler</a></li> <li class="toctree-l4"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#referencing-externally-defined-data-types-ipdl-includes">Referencing Externally Defined Data Types: IPDL Includes</a></li> <li class="toctree-l4"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#namespaces">Namespaces</a></li> <li class="toctree-l4"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#generating-ipdl-aware-c-data-types-ipdl-structs-and-unions">Generating IPDL-Aware C++ Data Types: IPDL Structs and Unions</a></li> <li class="toctree-l4"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#defining-actors">Defining Actors</a></li> <li class="toctree-l4"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#declaring-ipdl-messages">Declaring IPDL Messages</a></li> <li class="toctree-l4"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#ipdl-syntax-quick-reference">IPDL Syntax Quick Reference</a></li> </ul></li> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#the-c-interface">The C++ Interface</a> <ul> <li class="toctree-l4"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#paramtraits">ParamTraits</a></li> <li class="toctree-l4"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#ipdl-structs-and-unions-in-c">IPDL Structs and Unions in C++</a></li> <li class="toctree-l4"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#actors-and-messages-in-c">Actors and Messages in C++</a></li> <li class="toctree-l4"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#actor-lifetimes-in-c">Actor Lifetimes in C++</a></li> </ul></li> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#top-level-actors">Top Level Actors</a> <ul> <li class="toctree-l4"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#value-of-top-level-actors">Value of Top Level Actors</a></li> <li class="toctree-l4"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#creating-top-level-actors-from-other-actors">Creating Top Level Actors From Other Actors</a></li> <li class="toctree-l4"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#creating-first-top-level-actors">Creating First Top Level Actors</a></li> </ul></li> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#pbackground">PBackground</a></li> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#ipdl-best-practices">IPDL Best Practices</a></li> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#the-old-ways">The Old Ways</a></li> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#the-fud">The FUD</a></li> <li class="toctree-l3"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#the-rest">The Rest</a> <ul> <li class="toctree-l4"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#nested-messages">Nested messages</a></li> <li class="toctree-l4"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#message-logging">Message Logging</a></li> </ul></li> </ul></li> <li class="toctree-l2"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/processes.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Gecko Processes</a></li> <li class="toctree-l2"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/utility_process.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Utility Process</a></li> </ul></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/devtools/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Firefox DevTools Contributor Docs</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/toolkit/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Toolkit</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/js/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">SpiderMonkey</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/mobile/android/geckoview/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">GeckoView</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/mobile/android/fenix/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Fenix</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/mobile/android/focus-android/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Focus for Android</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/dom/bindings/webidl/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">WebIDL</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/modules/libpref/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">libpref</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/networking/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Networking</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/remote/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Remote Protocols</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/services/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Services</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/uriloader/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">File Handling</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/widget/cocoa/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Firefox on macOS</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/widget/windows/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Firefox on Windows</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/toolkit/components/ml/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Firefox AI Platform</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/accessible/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Accessibility</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/code-quality/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Code quality</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/writing-rust-code/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Writing Rust Code</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/rust-components/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Rust Components</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/tools/profiler/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Gecko Profiler</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/performance/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Performance</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/storage/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Database bindings (SQLite, KV, …)</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/xpcom/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">XPCOM</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/nspr/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">NSPR</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/security/nss/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Network Security Services (NSS)</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/content-security/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Web Security Checks in Gecko</a></li> </ul> The Firefox Build System <ul> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/mach/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Mach</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/tools/try/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Pushing to Try</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/build/buildsystem/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Build System</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/taskcluster/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Firefox CI and Taskgraph</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/tools/moztreedocs/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Managing Documentation</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/mozbuild/vendor/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Vendoring Third Party Components</a></li> </ul> Testing & Test Infrastructure <ul> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/automated-testing/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Automated Testing</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/treeherder-try/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Understanding Treeherder Results</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/sheriffed-intermittents/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Sheriffed intermittent failures</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/tests-for-new-config/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Turning on Firefox tests for a new configuration</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/intermittent/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Avoiding intermittent tests</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/testing-policy/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Testing Policy</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/ci-configs/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Configuration Changes</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/browser-chrome/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Browser chrome mochitests</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/chrome-tests/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Chrome Tests</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/marionette/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Marionette</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/geckodriver/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">geckodriver</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/test-verification/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Test Verification</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/webrender/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">WebRender Tests</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/mochitest-plain/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Mochitest</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/xpcshell/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">XPCShell tests</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/tps/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">TPS</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/web-platform/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">web-platform-tests</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/gtest/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">GTest</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/tools/fuzzing/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Fuzzing</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/tools/sanitizer/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Sanitizer</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing/perfdocs/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Performance Testing</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/tools/code-coverage/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Code coverage</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/testing-rust-code/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Testing & Debugging Rust Code</a></li> </ul> Releases & Updates <ul> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/update-infrastructure/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Mozilla Update Infrastructure</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/update-infrastructure/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#watershed-updates">Watershed Updates</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/update-infrastructure/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#desupport-updates">Desupport Updates</a></li> </ul> Localization & Internationalization <ul> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/intl/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Internationalization</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/l10n/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Localization</a></li> </ul> Firefox and Python <ul> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/mozbase/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">mozbase</a></li> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/python/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Using third-party Python packages</a></li> </ul> Metrics Collected in Firefox <ul> <li class="toctree-l1"><a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/metrics/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Metrics</a></li> </ul> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"> <nav class="wy-nav-top" aria-label="Mobile navigation menu"> <a href="https://firefox--source--docs-mozilla-org.translate.goog/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Firefox Source Docs</a> </nav> <div class="wy-nav-content"> <div class="rst-content"> <div role="navigation" aria-label="Page navigation"> <ul class="wy-breadcrumbs"> <li><a href="https://firefox--source--docs-mozilla-org.translate.goog/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB" class="icon icon-home" aria-label="Home"></a></li> <li class="breadcrumb-item"><a href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB">Processes, Threads and IPC</a></li> <li class="breadcrumb-item active">IPDL: Inter-Thread and Inter-Process Message Passing</li> <li class="wy-breadcrumbs-aside"><a href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://bugzilla.mozilla.org/enter_bug.cgi?product%3DDeveloper%2BInfrastructure%26component%3DFirefox%2BSource%2BDocs%253A%2BContent%26short_desc%3DDocumentation%2Bissue%2Bon%2Bipc/ipdl%26comment%3DURL%2B%3D%2Bhttps://firefox-source-docs.mozilla.org/ipc/ipdl.html%26bug_file_loc%3Dhttps://firefox-source-docs.mozilla.org/ipc/ipdl.html" rel="nofollow">Report an issue</a> / <a href="https://firefox--source--docs-mozilla-org.translate.goog/_sources/ipc/ipdl.rst.txt?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB" rel="nofollow"> View page source</a></li> </ul> <hr> </div> <div role="main" class="document" itemscope itemtype="http://schema.org/Article"> <div itemprop="articleBody"> <section id="ipdl-inter-thread-and-inter-process-message-passing"> <h1>IPDL: Inter-Thread and Inter-Process Message Passing<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#ipdl-inter-thread-and-inter-process-message-passing" title="Link to this heading">¶</a></h1> <section id="the-idea"> <h2>The Idea<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#the-idea" title="Link to this heading">¶</a></h2> 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 <a class="reference external" href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://en.wikipedia.org/wiki/Actor_model">actor model</a>. <div class="admonition note"> Note IPDL actors differ from the actor model in one significant way – all IPDL communications are only between a parent and its only child. </div> 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). <div class="admonition note"> Note More precisely, endpoints can be bound to any <code class="docutils literal notranslate">nsISerialEventTarget</code>, 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 <code class="docutils literal notranslate">GetCurrentSerialEventTarget</code>. 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. </div> <div class="admonition note"> Note Internally, we use the “Ports” component of the <a class="reference external" href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://chromium.googlesource.com/chromium/src/%2B/refs/heads/main/mojo/core/README.md%23Port">Chromium Mojo</a> 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 <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#ipdl-best-practices">IPDL Best Practices</a>. </div> 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 <code class="docutils literal notranslate">PCompositorBridge</code> 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 <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/processes.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#connecting-with-other-processes">Connecting With Other Processes</a> shows one way this can be done. It also shows that, without proper plain-language documentation of all of the ways endpoints are configured, this can quickly lead to unmaintainable code. Be sure to document your endpoint bindings thoroughly!!! </section> <section id="the-approach"> <h2>The Approach<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#the-approach" title="Link to this heading">¶</a></h2> 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. <div class="admonition warning"> Warning There are a few (rare) exceptions to the message order guarantee. They include <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#the-rest">synchronous nested</a> messages and messages with a <code class="docutils literal notranslate">[Priority]</code> or <code class="docutils literal notranslate">[Compress]</code> annotation. </div> 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 <code class="docutils literal notranslate">MessageLoop</code>. <div class="admonition note"> Note Not all IPDL messages are asynchronous. Again, we run into exceptions for messages that are synchronous or <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#the-rest">synchronous nested</a>. 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. </div> 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 <a class="reference external" href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://searchfox.org/mozilla-central/source/ipc">/ipc</a>, that standardizes the safe and secure use of sockets, pipes, shared memory, etc on all supported platforms. See <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#using-the-ipdl-compiler">Using The IPDL compiler</a> 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 (<code class="docutils literal notranslate">ParamTraits</code>) 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 <code class="docutils literal notranslate">ParamTraits</code> (<a class="reference external" href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://searchfox.org/mozilla-central/source/ipc/glue/IPCMessageUtils.h">here</a> and <a class="reference external" href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://searchfox.org/mozilla-central/source/ipc/glue/IPCMessageUtilsSpecializations.h">here</a>). <div class="admonition note"> Note Among other things, client code that uses the generated code must include <code class="docutils literal notranslate">chromium-config.mozbuild</code> in its <code class="docutils literal notranslate">moz.build</code> file. See <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#using-the-ipdl-compiler">Using The IPDL compiler</a> for a complete list of required build changes. </div> <section id="the-steps-to-making-a-new-actor"> <h3>The Steps To Making A New Actor<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#the-steps-to-making-a-new-actor" title="Link to this heading">¶</a></h3> <ol class="arabic"> <li>Decide what folder you will work in and create: <blockquote> <div> <ol class="arabic simple"> <li>An IPDL protocol file, named for your actor (e.g. <code class="docutils literal notranslate">PMyActor.ipdl</code> – actor protocols must begin with a <code class="docutils literal notranslate">P</code>). See <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#the-protocol-language">The Protocol Language</a>.</li> <li>Properly-named source files for your actor’s parent and child implementations (e.g. <code class="docutils literal notranslate">MyActorParent.h</code>, <code class="docutils literal notranslate">MyActorChild.h</code> and, optionally, adjacent .cpp files). See <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#the-c-interface">The C++ Interface</a>.</li> <li>IPDL-specific updates to the <code class="docutils literal notranslate">moz.build</code> file. See <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#using-the-ipdl-compiler">Using The IPDL compiler</a>.</li> </ol> </div> </blockquote></li> <li>Write your actor protocol (.ipdl) file: <blockquote> <div> <ol class="arabic simple"> <li>Decide whether you need a top-level actor or a managed actor. See <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#top-level-actors">Top Level Actors</a>.</li> <li>Find/write the IPDL and C++ data types you will use in communication. Write <code class="docutils literal notranslate">ParamTraits</code> for C++ data types that don’t have them. See <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#generating-ipdl-aware-c-data-types-ipdl-structs-and-unions">Generating IPDL-Aware C++ Data Types: IPDL Structs and Unions</a> for IPDL structures. See <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#referencing-externally-defined-data-types-ipdl-includes">Referencing Externally Defined Data Types: IPDL Includes</a> and <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#paramtraits">ParamTraits</a> for C++ data types.</li> <li>Write your actor and its messages. See <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#defining-actors">Defining Actors</a>.</li> </ol> </div> </blockquote></li> <li>Write C++ code to create and destroy instances of your actor at runtime. <blockquote> <div> <ul class="simple"> <li>For managed actors, see <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#actor-lifetimes-in-c">Actor Lifetimes in C++</a>.</li> <li>For top-level actors, see <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#creating-top-level-actors-from-other-actors">Creating Top Level Actors From Other Actors</a>. The first actor in a process is a very special exception – see <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#creating-first-top-level-actors">Creating First Top Level Actors</a>.</li> </ul> </div> </blockquote></li> <li>Write handlers for your actor’s messages. See <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#actors-and-messages-in-c">Actors and Messages in C++</a>.</li> <li>Start sending messages through your actors! Again, see <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#actors-and-messages-in-c">Actors and Messages in C++</a>.</li> </ol> </section> </section> <section id="the-protocol-language"> <h2>The Protocol Language<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#the-protocol-language" title="Link to this heading">¶</a></h2> This document will follow the integration of two actors into Firefox – <code class="docutils literal notranslate">PMyManager</code> and <code class="docutils literal notranslate">PMyManaged</code>. <code class="docutils literal notranslate">PMyManager</code> will manage <code class="docutils literal notranslate">PMyManaged</code>. A good place to start is with the IPDL actor definitions. These are files that are named for the actor (e.g. <code class="docutils literal notranslate">PMyManager.ipdl</code>) 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. <div class="highlight-c++ notranslate" id="pmymanager-ipdl"> <div class="highlight"> <pre>include protocol PMyManaged; include MyTypes; // for MyActorPair using MyActorEnum from "mozilla/myns/MyActorUtils.h"; using mozilla::myns::MyData from "mozilla/MyDataTypes.h"; [MoveOnly] using class mozilla::myns::MyOtherData from "mozilla/MyDataTypes.h"; [RefCounted] using class mozilla::myns::MyThirdData from "mozilla/MyDataTypes.h"; namespace mozilla { namespace myns { [Comparable] union MyUnion { float; MyOtherData; }; [ChildProc=any] sync protocol PMyManager { manages PMyManaged; 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); }; } // namespace myns } // namespace mozilla </pre> </div> </div> <div class="highlight-c++ notranslate" id="pmymanaged-ipdl"> <div class="highlight"> <pre>include protocol PMyManager; namespace mozilla { namespace myns { protocol PMyManaged { manager PMyManager; child: async __delete__(Shmem aShmem); }; } // namespace myns } // namespace mozilla </pre> </div> </div> These files reference three additional files. <code class="docutils literal notranslate">MyTypes.ipdlh</code> is an “IPDL header” that can be included into <code class="docutils literal notranslate">.ipdl</code> files as if it were inline, except that it also needs to include any external actors and data types it uses: <div class="highlight-c++ notranslate" id="mytypes-ipdlh"> <div class="highlight"> <pre>include protocol PMyManaged; struct MyActorPair { PMyManaged actor1; nullable PMyManaged actor2; }; </pre> </div> </div> <code class="docutils literal notranslate">MyActorUtils.h</code> and <code class="docutils literal notranslate">MyDataTypes.h</code> 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 <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#the-c-interface">The C++ Interface</a>. <section id="using-the-ipdl-compiler"> <h3>Using The IPDL compiler<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#using-the-ipdl-compiler" title="Link to this heading">¶</a></h3> To build IPDL files, list them (alphabetically sorted) in a <code class="docutils literal notranslate">moz.build</code> file. In this example, the <code class="docutils literal notranslate">.ipdl</code> and <code class="docutils literal notranslate">.ipdlh</code> files would be alongside a <code class="docutils literal notranslate">moz.build</code> containing: <div class="highlight-python notranslate"> <div class="highlight"> <pre>IPDL_SOURCES += [ "MyTypes.ipdlh", "PMyManaged.ipdl", "PMyManager.ipdl", ] UNIFIED_SOURCES += [ "MyManagedChild.cpp", "MyManagedParent.cpp", "MyManagerChild.cpp", "MyManagerParent.cpp", ] include("/ipc/chromium/chromium-config.mozbuild") </pre> </div> </div> <code class="docutils literal notranslate">chromium-config.mozbuild</code> sets up paths so that generated IPDL header files are in the proper scope. If it isn’t included, the build will fail with <code class="docutils literal notranslate">#include</code> errors in both your actor code and some internal ipc headers. For example: <div class="highlight-default notranslate"> <div class="highlight"> <pre>c:/mozilla-src/mozilla-unified/obj-64/dist/include\ipc/IPCMessageUtils.h(13,10): fatal error: 'build/build_config.h' file not found </pre> </div> </div> <code class="docutils literal notranslate">.ipdl</code> 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 <code class="docutils literal notranslate">PMyManager.ipdl</code> the compiler generates two header files added to the build context and exported globally: <code class="docutils literal notranslate">mozilla/myns/PMyManagerParent.h</code> and <code class="docutils literal notranslate">mozilla/myns/PMyManagerChild.h</code>, as discussed in <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#namespaces">Namespaces</a> 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 <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#actors-and-messages-in-c">Actors and Messages in C++</a> but note here that C++ header files named for the actor are required by the IPDL <cite>compiler</cite>. The example would expect <code class="docutils literal notranslate">mozilla/myns/MyManagedChild.h</code>, <code class="docutils literal notranslate">mozilla/myns/MyManagedParent.h</code>, <code class="docutils literal notranslate">mozilla/myns/MyManagerChild.h</code> and <code class="docutils literal notranslate">mozilla/myns/MyManagerParent.h</code> and will not build without them. </section> <section id="referencing-externally-defined-data-types-ipdl-includes"> <h3>Referencing Externally Defined Data Types: IPDL Includes<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#referencing-externally-defined-data-types-ipdl-includes" title="Link to this heading">¶</a></h3> Let’s begin with <code class="docutils literal notranslate">PMyManager.ipdl</code>. It starts by including types that it will need from other places: <div class="highlight-cpp notranslate"> <div class="highlight"> <pre>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"; </pre> </div> </div> The first line includes a protocol that PMyManager will manage. That protocol is defined in its own <code class="docutils literal notranslate">.ipdl</code> file. Cyclic references are expected and pose no concern. The second line includes the file <code class="docutils literal notranslate">MyTypes.ipdlh</code>, 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 <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#generating-ipdl-aware-c-data-types-ipdl-structs-and-unions">Generating IPDL-Aware C++ Data Types: IPDL Structs and Unions</a>. 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: <table class="docutils align-default"> <tbody> <tr class="row-odd"> <td><code class="docutils literal notranslate">[RefCounted]</code></td> <td>Type <code class="docutils literal notranslate">T</code> is reference counted (by <code class="docutils literal notranslate">AddRef</code>/<code class="docutils literal notranslate">Release</code>). As a parameter to a message or as a type in IPDL structs/unions, it is referenced as a <code class="docutils literal notranslate">RefPtr<T></code>.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">[MoveOnly]</code></td> <td>The type <code class="docutils literal notranslate">T</code> is treated as uncopyable. When used as a parameter in a message or an IPDL struct/union, it is as an r-value <code class="docutils literal notranslate">T&&</code>.</td> </tr> </tbody> </table> Finally, note that <code class="docutils literal notranslate">using</code>, <code class="docutils literal notranslate">using class</code> and <code class="docutils literal notranslate">using struct</code> are all valid syntax. The <code class="docutils literal notranslate">class</code> and <code class="docutils literal notranslate">struct</code> keywords are optional. </section> <section id="namespaces"> <h3>Namespaces<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#namespaces" title="Link to this heading">¶</a></h3> From the IPDL file: <div class="highlight-cpp notranslate"> <div class="highlight"> <pre>namespace mozilla { namespace myns { // ... data type and actor definitions ... } // namespace myns } // namespace mozilla </pre> </div> </div> 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 <code class="docutils literal notranslate">mozilla::myns::MyUnion</code> and the actors <code class="docutils literal notranslate">mozilla::myns::PMyManagerParent</code> and <code class="docutils literal notranslate">mozilla::myns::PMyManagerChild</code>, which can be included from <code class="docutils literal notranslate">mozilla/myns/PMyManagerParent.h</code>, <code class="docutils literal notranslate">mozilla/myns/PMyManagerParent.h</code> and <code class="docutils literal notranslate">mozilla/myns/PMyManagerChild.h</code>, respectively. The namespace becomes part of the path. </section> <section id="generating-ipdl-aware-c-data-types-ipdl-structs-and-unions"> <h3>Generating IPDL-Aware C++ Data Types: IPDL Structs and Unions<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#generating-ipdl-aware-c-data-types-ipdl-structs-and-unions" title="Link to this heading">¶</a></h3> <code class="docutils literal notranslate">PMyManager.ipdl</code> and <code class="docutils literal notranslate">MyTypes.ipdlh</code> define: <div class="highlight-cpp notranslate"> <div class="highlight"> <pre>[Comparable] union MyUnion { float; MyOtherData; }; struct MyActorPair { PMyManaged actor1; nullable PMyManaged actor2; }; </pre> </div> </div> From these descriptions, IPDL generates C++ classes that approximate the behavior of C++ structs and unions but that come with pre-defined <code class="docutils literal notranslate">ParamTraits</code> 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 <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#paramtraits">ParamTraits</a> for details. The <code class="docutils literal notranslate">[Comparable]</code> attribute tells IPDL to generate <code class="docutils literal notranslate">operator==</code> and <code class="docutils literal notranslate">operator!=</code> 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 <code class="docutils literal notranslate">nullable</code> 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. </section> <section id="defining-actors"> <h3>Defining Actors<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#defining-actors" title="Link to this heading">¶</a></h3> The real point of any <code class="docutils literal notranslate">.ipdl</code> file is that each defines exactly one actor protocol. The definition always matches the <code class="docutils literal notranslate">.ipdl</code> filename. Repeating the one in <code class="docutils literal notranslate">PMyManager.ipdl</code>: <div class="highlight-cpp notranslate"> <div class="highlight"> <pre>[ChildProc=Content] sync protocol PMyManager { manages PMyManaged; async PMyManaged(); // ... more message declarations ... }; </pre> </div> </div> <div class="admonition important"> Important A form of reference counting is <cite>always</cite> 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 <cite>cannot</cite> 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 <cite>must</cite> delete it. If all of those objects were reference counted then there would be no complexity here. Indeed, new actors using <code class="docutils literal notranslate">[ManualDealloc]</code> should not be approved without a very compelling reason. New <code class="docutils literal notranslate">[ManualDealloc]</code> actors may soon be forbidden. </div> The <code class="docutils literal notranslate">sync</code> keyword tells IPDL that the actor contains messages that block the sender using <code class="docutils literal notranslate">sync</code> 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 <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#declaring-ipdl-messages">IPDL messages</a>. 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 <code class="docutils literal notranslate">sync</code> messages defined here. This list gives preliminary definitions of the options for the actor-blocking policy of messages: <table class="docutils align-default"> <tbody> <tr class="row-odd"> <td><code class="docutils literal notranslate">async</code></td> <td>Actor may contain only asynchronous messages.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">sync</code></td> <td>Actor has <code class="docutils literal notranslate">async</code> capabilities and adds <code class="docutils literal notranslate">sync</code> messages. <code class="docutils literal notranslate">sync</code> messages can only be sent from the child actor to the parent.</td> </tr> </tbody> </table> 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 <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#nested-messages">Nested messages</a>. <table class="docutils align-default"> <tbody> <tr class="row-odd"> <td><code class="docutils literal notranslate">[NestedUpTo=inside_sync]</code></td> <td>Actor has high priority messages that can be handled while waiting for a <code class="docutils literal notranslate">sync</code> response.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">[NestedUpTo=inside_cpow]</code></td> <td>Actor has the highest priority messages that can be handled while waiting for a <code class="docutils literal notranslate">sync</code> response.</td> </tr> </tbody> </table> In addition, top-level protocols are annotated with which processes each side should be bound into using the <code class="docutils literal notranslate">[ParentProc=*]</code> and <code class="docutils literal notranslate">[ChildProc=*]</code> attributes. The <code class="docutils literal notranslate">[ParentProc]</code> attribute is optional, and defaults to the <code class="docutils literal notranslate">Parent</code> process. The <code class="docutils literal notranslate">[ChildProc]</code> attribute is required. See <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#process-type-attributes">Process Type Attributes</a> for possible values. The <code class="docutils literal notranslate">manages</code> clause tells IPDL that <code class="docutils literal notranslate">PMyManager</code> manages the <code class="docutils literal notranslate">PMyManaged</code> actor that was previously <code class="docutils literal notranslate">include</code> d. As with any managed protocol, it must also be the case that <code class="docutils literal notranslate">PMyManaged.ipdl</code> includes <code class="docutils literal notranslate">PMyManager</code> and declares that <code class="docutils literal notranslate">PMyManaged</code> is <code class="docutils literal notranslate">managed</code> by <code class="docutils literal notranslate">PMyManager</code>. Recalling the code: <div class="highlight-cpp notranslate"> <div class="highlight"> <pre>// PMyManaged.ipdl include protocol PMyManager; // ... protocol PMyManaged { manager PMyManager; // ... }; </pre> </div> </div> An actor has a <code class="docutils literal notranslate">manager</code> (e.g. <code class="docutils literal notranslate">PMyManaged</code>) or else it is a top-level actor (e.g. <code class="docutils literal notranslate">PMyManager</code>). An actor protocol may be managed by more than one actor type. For example, <code class="docutils literal notranslate">PMyManaged</code> could have also been managed by some <code class="docutils literal notranslate">PMyOtherManager</code> not shown here. In that case, <code class="docutils literal notranslate">manager</code> s are presented in a list, separated by <code class="docutils literal notranslate">or</code> – e.g. <code class="docutils literal notranslate">manager PMyManager or PMyOtherManager</code>. 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 <code class="docutils literal notranslate">async PMyManaged()</code>. This message is a constructor for <code class="docutils literal notranslate">MyManaged</code> actors; unlike C++ classes, it is found in <code class="docutils literal notranslate">MyManager</code>. 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 <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#actor-lifetimes-in-c">Actor Lifetimes in C++</a>. We haven’t discussed a way to construct new top level actors. This is a more advanced topic and is covered separately in <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#top-level-actors">Top Level Actors</a>. </section> <section id="declaring-ipdl-messages"> <h3>Declaring IPDL Messages<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#declaring-ipdl-messages" title="Link to this heading">¶</a></h3> The final part of the actor definition is the declaration of messages: <div class="highlight-cpp notranslate"> <div class="highlight"> <pre>sync protocol PMyManager { // ... parent: async __delete__(nsString aNote); sync SomeMsg(MyActorPair? aActors, MyData[] aMyData) returns (int32_t x, int32_t y, MyUnion aUnion); async PMyManaged(); both: [Tainted] async AnotherMsg(MyActorEnum aEnum, int32_t a number) returns (MyOtherData aOtherData); }; </pre> </div> </div> The messages are grouped into blocks by <code class="docutils literal notranslate">parent:</code>, <code class="docutils literal notranslate">child:</code> and <code class="docutils literal notranslate">both:</code>. These labels work the way <code class="docutils literal notranslate">public:</code> and <code class="docutils literal notranslate">private:</code> work in C++ – messages after these descriptors are sent/received (only) in the direction specified. <div class="admonition note"> Note As a mnemonic to remember which direction they indicate, remember to put the word “to” in front of them. So, for example, <code class="docutils literal notranslate">parent:</code> precedes <code class="docutils literal notranslate">__delete__</code>, meaning <code class="docutils literal notranslate">__delete__</code> is sent from the child to the parent, and <code class="docutils literal notranslate">both:</code> states that <code class="docutils literal notranslate">AnotherMsg</code> can be sent to either endpoint. </div> IPDL messages support the following annotations: <table class="docutils align-default"> <tbody> <tr class="row-odd"> <td><code class="docutils literal notranslate">[Compress]</code></td> <td>Indicates repeated messages of this type will consolidate.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">[Tainted]</code></td> <td>Parameters are required to be validated before using them.</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">[Priority=Foo]</code></td> <td>Priority of <code class="docutils literal notranslate">MessageTask</code> that runs the C++ message handler. <code class="docutils literal notranslate">Foo</code> is one of: <code class="docutils literal notranslate">normal</code>, <code class="docutils literal notranslate">input</code>, <code class="docutils literal notranslate">vsync</code>, <code class="docutils literal notranslate">mediumhigh</code>, or <code class="docutils literal notranslate">control</code>. See the <code class="docutils literal notranslate">IPC::Message::PriorityValue</code> enum.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">[Nested=inside_sync]</code></td> <td>Indicates that the message can sometimes be handled while a sync message waits for a response.</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">[Nested=inside_cpow]</code></td> <td>Indicates that the message can sometimes be handled while a sync message waits for a response.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">[LazySend]</code></td> <td>Messages with this annotation will be queued up to be sent together either immediately before a non-LazySend message, or from a direct task.</td> </tr> </tbody> </table> <code class="docutils literal notranslate">[Compress]</code> provides crude protection against spamming with a flood of messages. When messages of type <code class="docutils literal notranslate">M</code> are compressed, the queue of unprocessed messages between actors will never contain an <code class="docutils literal notranslate">M</code> 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. <code class="docutils literal notranslate">[Compress=all]</code> is similar but applies whether or not the messages are adjacent in the message queue. <code class="docutils literal notranslate">[Tainted]</code> 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 <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#actors-and-messages-in-c">Actors and Messages in C++</a>. The <code class="docutils literal notranslate">Nested</code> annotations are deeply related to the message’s blocking policy that follows it and which was briefly discussed in <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#defining-actors">Defining Actors</a>. See <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#nested-messages">Nested messages</a> for details. <code class="docutils literal notranslate">[LazySend]</code> 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 <code class="docutils literal notranslate">[LazySend]</code> 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 <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#defining-actors">Defining Actors</a>: <table class="docutils align-default"> <tbody> <tr class="row-odd"> <td><code class="docutils literal notranslate">async</code></td> <td>Actor may contain only asynchronous messages.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">sync</code></td> <td>Actor has <code class="docutils literal notranslate">async</code> capabilities and adds <code class="docutils literal notranslate">sync</code> messages. <code class="docutils literal notranslate">sync</code> messages can only be sent from the child actor to the parent.</td> </tr> </tbody> </table> The policy defines whether an actor will wait for a response when it sends a certain type of message. A <code class="docutils literal notranslate">sync</code> actor will wait immediately after sending a <code class="docutils literal notranslate">sync</code> 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 <code class="docutils literal notranslate">sync</code> messages are therefore required to get approval from an IPC peer. The IPDL compiler will require such messages to be listed in the file <code class="docutils literal notranslate">sync-messages.ini</code>. The notion that only child actors can send <code class="docutils literal notranslate">sync</code> 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 <cite>or</cite> parent and some, like the main process, sometimes serve as both. This means that sync messages should be used with extreme care. <div class="admonition note"> 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). </div> An <code class="docutils literal notranslate">async</code> actor will not wait. An <code class="docutils literal notranslate">async</code> response is essentially identical to sending another <code class="docutils literal notranslate">async</code> message back. It may be handled whenever received messages are handled. The value over an <code class="docutils literal notranslate">async</code> 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 <code class="docutils literal notranslate">__delete__</code> stands out as strange – indeed, it terminates the actor’s connection. <cite>It does not delete any actor objects itself!</cite> It severs the connections of the actor <cite>and any actors it manages</cite> at both endpoints. An actor will never send or receive any messages after it sends or receives a <code class="docutils literal notranslate">__delete__</code>. 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 <code class="docutils literal notranslate">__delete__</code> 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 <code class="docutils literal notranslate">__delete__</code> 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. <code class="docutils literal notranslate">PMyManaged()</code> 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++ <code class="docutils literal notranslate">ParamTraits</code> specialization and is imported by a directive. That said, there are some surprises in the list of messages: <table class="docutils align-default"> <tbody> <tr class="row-odd"> <td><code class="docutils literal notranslate">int32_t</code>,…</td> <td>The standard primitive types are included. See <a class="reference external" href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://searchfox.org/mozilla-central/source/ipc/ipdl/ipdl/builtin.py">builtin.py</a> for a list. Pointer types are, unsurprisingly, forbidden.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">?</code></td> <td>When following a type T, the parameter is translated into <code class="docutils literal notranslate">Maybe<T></code> in C++.</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">[]</code></td> <td>When following a type T, the parameter is translated into <code class="docutils literal notranslate">nsTArray<T></code> in C++.</td> </tr> </tbody> </table> Finally, the returns list declares the information sent in response, also as a tuple of typed parameters. As previously mentioned, even <code class="docutils literal notranslate">async</code> messages can receive responses. A <code class="docutils literal notranslate">sync</code> message will always wait for a response but an <code class="docutils literal notranslate">async</code> message will not get one unless it has a <code class="docutils literal notranslate">returns</code> 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 <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#actors-and-messages-in-c">Actors and Messages in C++</a>. For suggestions on best practices when designing your IPDL actor approach, see <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#ipdl-best-practices">IPDL Best Practices</a>. </section> <section id="ipdl-syntax-quick-reference"> <h3>IPDL Syntax Quick Reference<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#ipdl-syntax-quick-reference" title="Link to this heading">¶</a></h3> The following is a list of the keywords and operators that have been introduced for use in IPDL files: <table class="docutils align-default"> <tbody> <tr class="row-odd"> <td><code class="docutils literal notranslate">include</code></td> <td>Include a C++ header (quoted file name) or <code class="docutils literal notranslate">.ipdlh</code> file (unquoted with no file suffix).</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">using (class|struct) from</code></td> <td>Similar to <code class="docutils literal notranslate">include</code> but imports only a specific data type.</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">include protocol</code></td> <td>Include another actor for use in management statements, IPDL data types or as parameters to messages.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">[RefCounted]</code></td> <td>Indicates that the imported C++ data types are reference counted. Refcounted types require a different <code class="docutils literal notranslate">ParamTraits</code> interface than non-reference-counted types.</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">[ManualDealloc]</code></td> <td>Indicates that the IPDL interface uses the legacy manual allocation/deallocation interface, rather than modern reference counting.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">[MoveOnly]</code></td> <td>Indicates that an imported C++ data type should not be copied. IPDL code will move it instead.</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">namespace</code></td> <td>Specifies the namespace for IPDL generated code.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">union</code></td> <td>An IPDL union definition.</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">struct</code></td> <td>An IPDL struct definition.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">[Comparable]</code></td> <td>Indicates that IPDL should generate <code class="docutils literal notranslate">operator==</code> and <code class="docutils literal notranslate">operator!=</code> for the given IPDL struct/union.</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">nullable</code></td> <td>Indicates that an actor reference in an IPDL type may be null when sent over IPC.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">protocol</code></td> <td>An IPDL protocol (actor) definition.</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">sync/async</code></td> <td>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 <code class="docutils literal notranslate">sync</code> messages must itself be labeled <code class="docutils literal notranslate">sync</code>.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">[NestedUpTo=inside_sync]</code></td> <td>Indicates that an actor contains [Nested=inside_sync] messages, in addition to normal messages.</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">[NestedUpTo=inside_cpow]</code></td> <td>Indicates that an actor contains [Nested=inside_cpow] messages, in addition to normal messages.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">[Nested=inside_sync]</code></td> <td>Indicates that the message can be handled while waiting for lower-priority, or in-message-thread, sync responses.</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">[Nested=inside_cpow]</code></td> <td>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.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">manager</code></td> <td>Used in a protocol definition to indicate that this actor manages another one.</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">manages</code></td> <td>Used in a protocol definition to indicate that this actor is managed by another one.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">or</code></td> <td>Used in a <code class="docutils literal notranslate">manager</code> clause for actors that have multiple potential managers.</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">parent: / child: / both:</code></td> <td>Indicates direction of subsequent actor messages. As a mnemonic to remember which direction they indicate, put the word “to” in front of them.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">returns</code></td> <td>Defines return values for messages. All types of message, including <code class="docutils literal notranslate">async</code>, support returning values.</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">__delete__</code></td> <td>A special message that destroys the related actors at both endpoints when sent. <code class="docutils literal notranslate">Recv__delete__</code> and <code class="docutils literal notranslate">ActorDestroy</code> are called before destroying the actor at the other endpoint, to allow for cleanup.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">int32_t</code>,…</td> <td>The standard primitive types are included.</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">String</code></td> <td>Translated into <code class="docutils literal notranslate">nsString</code> in C++.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">?</code></td> <td>When following a type T in an IPDL data structure or message parameter, the parameter is translated into <code class="docutils literal notranslate">Maybe<T></code> in C++.</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">[]</code></td> <td>When following a type T in an IPDL data structure or message parameter, the parameter is translated into <code class="docutils literal notranslate">nsTArray<T></code> in C++.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">[Tainted]</code></td> <td>Used to indicate that a message’s handler should receive parameters that it is required to manually validate. Parameters of type <code class="docutils literal notranslate">T</code> become <code class="docutils literal notranslate">Tainted<T></code> in C++.</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">[Compress]</code></td> <td>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).</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">[Compress=all]</code></td> <td>Like <code class="docutils literal notranslate">[Compress]</code> but discards the older message regardless of whether they are adjacent in the message queue.</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">[Priority=Foo]</code></td> <td>Priority of <code class="docutils literal notranslate">MessageTask</code> that runs the C++ message handler. <code class="docutils literal notranslate">Foo</code> is one of: <code class="docutils literal notranslate">normal</code>, <code class="docutils literal notranslate">input</code>, <code class="docutils literal notranslate">vsync</code>, <code class="docutils literal notranslate">mediumhigh</code>, or <code class="docutils literal notranslate">control</code>.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">[LazySend]</code></td> <td>Messages with this annotation will be queued up to be sent together immediately before a non-LazySend message, or from a direct task.</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">[ChildImpl="RemoteFoo"]</code></td> <td>Indicates that the child side implementation of the actor is a class named <code class="docutils literal notranslate">RemoteFoo</code>, and the definition is included by one of the <code class="docutils literal notranslate">include "...";</code> statements in the file. New uses of this attribute are discouraged.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">[ParentImpl="FooImpl"]</code></td> <td>Indicates that the parent side implementation of the actor is a class named <code class="docutils literal notranslate">FooImpl</code>, and the definition is included by one of the <code class="docutils literal notranslate">include "...";</code> statements in the file. New uses of this attribute are discouraged.</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">[ChildImpl=virtual]</code></td> <td>Indicates that the child side implementation of the actor is not exported by a header, so virtual <code class="docutils literal notranslate">Recv</code> methods should be used instead of direct function calls. New uses of this attribute are discouraged.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">[ParentImpl=virtual]</code></td> <td>Indicates that the parent side implementation of the actor is not exported by a header, so virtual <code class="docutils literal notranslate">Recv</code> methods should be used instead of direct function calls. New uses of this attribute are discouraged.</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">[ChildProc=...]</code></td> <td>Indicates which process the child side of the actor is expected to be bound in. This will be release asserted when creating the actor. Required for top-level actors. See <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#process-type-attributes">Process Type Attributes</a> for possible values.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">[ParentProc=...]</code></td> <td>Indicates which process the parent side of the actor is expected to be bound in. This will be release asserted when creating the actor. Defaults to <code class="docutils literal notranslate">Parent</code> for top-level actors. See <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#process-type-attributes">Process Type Attributes</a> for possible values.</td> </tr> </tbody> </table> <section id="process-type-attributes"> <h4>Process Type Attributes<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#process-type-attributes" title="Link to this heading">¶</a></h4> The following are valid values for the <code class="docutils literal notranslate">[ChildProc=...]</code> and <code class="docutils literal notranslate">[ParentProc=...]</code> attributes on protocols, each corresponding to a specific process type: <table class="docutils align-default"> <tbody> <tr class="row-odd"> <td><code class="docutils literal notranslate">Parent</code></td> <td>The primary “parent” or “main” process</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">Content</code></td> <td>A content process, such as those used to host web pages, workers, and extensions</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">IPDLUnitTest</code></td> <td>Test-only process used in IPDL gtests</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">GMPlugin</code></td> <td>Gecko Media Plugin (GMP) process</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">GPU</code></td> <td>GPU process</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">VR</code></td> <td>VR process</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">RDD</code></td> <td>Remote Data Decoder (RDD) process</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">Socket</code></td> <td>Socket/Networking process</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">ForkServer</code></td> <td>Fork Server process</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">Utility</code></td> <td>Utility process</td> </tr> </tbody> </table> The attributes also support some wildcard values, which can be used when an actor can be bound in multiple processes. If you are adding an actor which needs a new wildcard value, please reach out to the IPC team, and we can add one for your use-case. They are as follows: <table class="docutils align-default"> <tbody> <tr class="row-odd"> <td><code class="docutils literal notranslate">any</code></td> <td>Any process. If a more specific value is applicable, it should be preferred where possible.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">anychild</code></td> <td>Any process other than <code class="docutils literal notranslate">Parent</code>. Often used for utility actors which are bound on a per-process basis, such as profiling.</td> </tr> <tr class="row-odd"> <td><code class="docutils literal notranslate">compositor</code></td> <td>Either the <code class="docutils literal notranslate">GPU</code> or <code class="docutils literal notranslate">Parent</code> process. Often used for actors bound to the compositor thread.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">anydom</code></td> <td>Either the <code class="docutils literal notranslate">Parent</code> or a <code class="docutils literal notranslate">Content</code> process. Often used for actors used to implement DOM APIs.</td> </tr> </tbody> </table> Note that these assertions do not provide security guarantees, and are primarily intended for use when auditing and as documentation for how actors are being used. </section> </section> </section> <section id="the-c-interface"> <h2>The C++ Interface<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#the-c-interface" title="Link to this heading">¶</a></h2> <section id="paramtraits"> <h3>ParamTraits<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#paramtraits" title="Link to this heading">¶</a></h3> 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 <code class="docutils literal notranslate">ParamTraits</code> C++ type class. <code class="docutils literal notranslate">ParamTraits</code> 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 <code class="docutils literal notranslate">ParamTraits</code> 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 (<code class="docutils literal notranslate">std</code> and <code class="docutils literal notranslate">mozilla</code>), vectors (<code class="docutils literal notranslate">std</code> and <code class="docutils literal notranslate">mozilla</code>), <code class="docutils literal notranslate">RefPtr<T></code> (for serializable <code class="docutils literal notranslate">T</code>), <code class="docutils literal notranslate">UniquePtr<T></code>, <code class="docutils literal notranslate">nsCOMPtr<T></code>, <code class="docutils literal notranslate">nsTArray<T></code>, <code class="docutils literal notranslate">std::unordered_map<T></code>, <code class="docutils literal notranslate">nsresult</code>, etc. See <a class="reference external" href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://searchfox.org/mozilla-central/source/ipc/ipdl/ipdl/builtin.py">builtin.py</a>, <a class="reference external" href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://searchfox.org/mozilla-central/source/ipc/chromium/src/chrome/common/ipc_message_utils.h">ipc_message_utils.h</a> and <a class="reference external" href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://searchfox.org/mozilla-central/source/ipc/glue/IPCMessageUtilsSpecializations.h">IPCMessageUtilsSpecializations.h</a>. <code class="docutils literal notranslate">ParamTraits</code> typically bootstrap with the <code class="docutils literal notranslate">ParamTraits</code> of more basic types, until they hit bedrock (e.g. one of the basic types above). In the most extreme cases, a <code class="docutils literal notranslate">ParamTraits</code> 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 <code class="docutils literal notranslate">MyDataTypes.h</code>: <div class="highlight-cpp notranslate"> <div class="highlight"> <pre>// 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); }; } </pre> </div> </div> MyData is a struct and MyOtherData is a typedef. IPDL is fine with both. Additionally, MyOtherData is not copyable, matching its IPDL <code class="docutils literal notranslate">[MoveOnly]</code> annotation. <code class="docutils literal notranslate">ParamTraits</code> are required to be defined in the <code class="docutils literal notranslate">IPC</code> namespace. They must contain a <code class="docutils literal notranslate">Write</code> method with the proper signature that is used for serialization and a <code class="docutils literal notranslate">Read</code> method, again with the correct signature, for deserialization. Here we have three examples of declarations: one for an unannotated type, one for <code class="docutils literal notranslate">[MoveOnly]</code> and a <code class="docutils literal notranslate">[RefCounted]</code> one. Notice the difference in the <code class="docutils literal notranslate">[RefCounted]</code> 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 <code class="docutils literal notranslate">Read</code> but, in the reference-counted case, <code class="docutils literal notranslate">Read</code> is given an empty <code class="docutils literal notranslate">RefPtr<MyUnusedData></code> and should only allocate a <code class="docutils literal notranslate">MyUnusedData</code> to return if it so desires. These are straight-forward implementations of the <code class="docutils literal notranslate">ParamTraits</code> methods for <code class="docutils literal notranslate">MyData</code>: <div class="highlight-cpp notranslate"> <div class="highlight"> <pre>/* 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)); } </pre> </div> </div> <code class="docutils literal notranslate">WriteParam</code> and <code class="docutils literal notranslate">ReadParam</code> call the <code class="docutils literal notranslate">ParamTraits</code> for the data you pass them, determined using the type of the object as supplied. <code class="docutils literal notranslate">WriteBytes</code> and <code class="docutils literal notranslate">ReadBytesInto</code> work on raw, contiguous bytes as expected. <code class="docutils literal notranslate">MessageWriter</code> and <code class="docutils literal notranslate">MessageReader</code> 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. <div class="admonition important"> Important Potential failures in <code class="docutils literal notranslate">Read</code> include everyday C++ failures like out-of-memory conditions, which can be handled as usual. But <code class="docutils literal notranslate">Read</code> can also fail due to things like data validation errors. <code class="docutils literal notranslate">ParamTraits</code> read data that is considered insecure. It is important that they catch corruption and properly handle it. Returning false from <code class="docutils literal notranslate">Read</code> 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 <code class="docutils literal notranslate">ParamTraits</code> not crashing due to corruption failures. Occasionally, validation will require access to state that <code class="docutils literal notranslate">ParamTraits</code> 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 <code class="docutils literal notranslate">Tainted</code> annotation. See <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#actors-and-messages-in-c">Actors and Messages in C++</a> for more. </div> <div class="admonition note"> Note In the past, it was required to specialize <code class="docutils literal notranslate">mozilla::ipc::IPDLParamTraits<T></code> instead of <code class="docutils literal notranslate">IPC::ParamTraits<T></code> if you needed the actor object itself during serialization or deserialization. These days the actor can be fetched using <code class="docutils literal notranslate">IPC::Message{Reader,Writer}::GetActor()</code> in <code class="docutils literal notranslate">IPC::ParamTraits</code>, so that trait should be used for all new serializations. </div> 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. <code class="docutils literal notranslate">ContiguousEnumSerializer</code> and <code class="docutils literal notranslate">ContiguousEnumSerializerInclusive</code> safely implement <code class="docutils literal notranslate">ParamTraits</code> for enums that are only valid for a contiguous set of values, which is most of them. The generated <code class="docutils literal notranslate">ParamTraits</code> confirm that the enum is in valid range; <code class="docutils literal notranslate">Read</code> will return false otherwise. As an example, here is the <code class="docutils literal notranslate">MyActorEnum</code> included from <code class="docutils literal notranslate">MyActorUtils.h</code>: <div class="highlight-cpp notranslate"> <div class="highlight"> <pre>enum MyActorEnum { e1, e2, e3, e4, e5 }; template<> struct ParamTraits<MyActorEnum> : public ContiguousEnumSerializerInclusive<MyActorEnum, MyActorEnum::e1, MyActorEnum::e5> {}; </pre> </div> </div> </section> <section id="ipdl-structs-and-unions-in-c"> <h3>IPDL Structs and Unions in C++<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#ipdl-structs-and-unions-in-c" title="Link to this heading">¶</a></h3> IPDL structs and unions become C++ classes that provide interfaces that are fairly self-explanatory. Recalling <code class="docutils literal notranslate">MyUnion</code> and <code class="docutils literal notranslate">MyActorPair</code> from <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#generating-ipdl-aware-c-data-types-ipdl-structs-and-unions">IPDL Structs and Unions</a> : <div class="highlight-cpp notranslate"> <div class="highlight"> <pre>union MyUnion { float; MyOtherData; }; struct MyActorPair { PMyManaged actor1; nullable PMyManaged actor2; }; </pre> </div> </div> These compile to: <div class="highlight-cpp notranslate"> <div class="highlight"> <pre>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(); } </pre> </div> </div> The generated <code class="docutils literal notranslate">ParamTraits</code> use the <code class="docutils literal notranslate">ParamTraits</code> for the types referenced by the IPDL struct or union. Fields respect any annotations for their type (see <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#referencing-externally-defined-data-types-ipdl-includes">IPDL Includes</a>). For example, a <code class="docutils literal notranslate">[RefCounted]</code> type <code class="docutils literal notranslate">T</code> generates <code class="docutils literal notranslate">RefPtr<T></code> fields. Note that actor members result in members of both the parent and child actor types, as seen in <code class="docutils literal notranslate">MyActorPair</code>. 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, <code class="docutils literal notranslate">PMyManagedChild</code>), the adjacent actor of the other type (<code class="docutils literal notranslate">PMyManagedParent</code>) is received. This is not only true for message parameters and IPDL structs/unions but also for custom <code class="docutils literal notranslate">ParamTraits</code> implementations. If you <code class="docutils literal notranslate">Write</code> a <code class="docutils literal notranslate">PFooParent*</code> then you must <code class="docutils literal notranslate">Read</code> a <code class="docutils literal notranslate">PFooChild*</code>. 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 <code class="docutils literal notranslate">MyManagerParent::RecvSomeMsg(Maybe<MyActorPair>&& aActors, nsTArray<MyData>&& aMyData)</code> then the <code class="docutils literal notranslate">actor1Child</code> and <code class="docutils literal notranslate">actor2Child</code> fields cannot be valid since the child (usually) exists in another process. </section> <section id="actors-and-messages-in-c"> <h3>Actors and Messages in C++<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#actors-and-messages-in-c" title="Link to this heading">¶</a></h3> As mentioned in <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#using-the-ipdl-compiler">Using The IPDL compiler</a>, the IPDL compiler generates two header files for the protocol <code class="docutils literal notranslate">PMyManager</code>: <code class="docutils literal notranslate">PMyManagerParent.h</code> and <code class="docutils literal notranslate">PMyManagerChild.h</code>, which declare the actor’s base classes. There, we discussed how the headers are visible to C++ components that include <code class="docutils literal notranslate">chromium-config.mozbuild</code>. We, in turn, always need to define two files that declare our actor implementation subclasses (<code class="docutils literal notranslate">MyManagerParent.h</code> and <code class="docutils literal notranslate">MyManagerChild.h</code>). The IPDL file looked like this: <div class="highlight-c++ notranslate" id="id3"> <div class="highlight"> <pre>include protocol PMyManaged; include MyTypes; // for MyActorPair using MyActorEnum from "mozilla/myns/MyActorUtils.h"; using mozilla::myns::MyData from "mozilla/MyDataTypes.h"; [MoveOnly] using class mozilla::myns::MyOtherData from "mozilla/MyDataTypes.h"; [RefCounted] using class mozilla::myns::MyThirdData from "mozilla/MyDataTypes.h"; namespace mozilla { namespace myns { [Comparable] union MyUnion { float; MyOtherData; }; [ChildProc=any] sync protocol PMyManager { manages PMyManaged; 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); }; } // namespace myns } // namespace mozilla </pre> </div> </div> So <code class="docutils literal notranslate">MyManagerParent.h</code> looks like this: <div class="highlight-cpp notranslate"> <div class="highlight"> <pre>#include "PMyManagerParent.h" namespace mozilla { namespace myns { class MyManagerParent : public PMyManagerParent { NS_INLINE_DECL_REFCOUNTING(MyManagerParent, override) protected: IPCResult Recv__delete__(const nsString& aNote); IPCResult RecvSomeMsg(const Maybe<MyActorPair>& aActors, const nsTArray<MyData>& aMyData, int32_t* x, int32_t* y, MyUnion* aUnion); IPCResult RecvAnotherMsg(const Tainted<MyActorEnum>& aEnum, const Tainted<int32_t>& a number, AnotherMsgResolver&& aResolver); already_AddRefed<PMyManagerParent> AllocPMyManagedParent(); IPCResult RecvPMyManagedConstructor(PMyManagedConstructor* aActor); // ... etc ... }; } // namespace myns } // namespace mozilla </pre> </div> </div> All messages that can be sent to the actor must be handled by <code class="docutils literal notranslate">Recv</code> methods in the proper actor subclass. They should return <code class="docutils literal notranslate">IPC_OK()</code> on success and <code class="docutils literal notranslate">IPC_FAIL(actor, reason)</code> if an error occurred (where <code class="docutils literal notranslate">actor</code> is <code class="docutils literal notranslate">this</code> and <code class="docutils literal notranslate">reason</code> 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. <code class="docutils literal notranslate">Recv</code> methods are called by IPDL by enqueueing a task to run them on the <code class="docutils literal notranslate">MessageLoop</code> 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 <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#top-level-actors">Top Level Actors</a>. 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 <code class="docutils literal notranslate">std::move</code>-d into the <code class="docutils literal notranslate">Recv</code> method. They can be received as a const l-value reference, rvalue-reference, or by value (type-permitting). <code class="docutils literal notranslate">[MoveOnly]</code> 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, <code class="docutils literal notranslate">AnotherMsgResolver</code> would be a <code class="docutils literal notranslate">std::function<></code> and <code class="docutils literal notranslate">aResolver</code> would be given the value to return by passing it a reference to a <code class="docutils literal notranslate">MyOtherData</code> object. <code class="docutils literal notranslate">MyManagerParent</code> is also capable of <code class="docutils literal notranslate">sending</code> an async message that returns a value: <code class="docutils literal notranslate">AnotherMsg</code>. This is done with <code class="docutils literal notranslate">SendAnotherMsg</code>, which is defined automatically by IPDL in the base class <code class="docutils literal notranslate">PMyManagerParent</code>. There are two signatures for <code class="docutils literal notranslate">Send</code> and they look like this: <div class="highlight-cpp notranslate"> <div class="highlight"> <pre>// Return a Promise that IPDL will resolve with the response or reject. RefPtr<MozPromise<MyOtherData, ResponseRejectReason, true>> SendAnotherMsg(const MyActorEnum& aEnum, int32_t a number); // Provide callbacks to process response / reject. The callbacks are just // std::functions. void SendAnotherMsg(const MyActorEnum& aEnum, int32_t a number, ResolveCallback<MyOtherData>&& aResolve, RejectCallback&& aReject); </pre> </div> </div> The response is usually handled by lambda functions defined at the site of the <code class="docutils literal notranslate">Send</code> call, either by attaching them to the returned promise with e.g. <code class="docutils literal notranslate">MozPromise::Then</code>, or by passing them as callback parameters. See docs on <code class="docutils literal notranslate">MozPromise</code> 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. <code class="docutils literal notranslate">ResponseRejectReason</code> is an enum IPDL provides to explain failures. Additionally, the <code class="docutils literal notranslate">AnotherMsg</code> handler has <code class="docutils literal notranslate">Tainted</code> parameters, as a result of the [Tainted] annotation in the protocol file. Recall that <code class="docutils literal notranslate">Tainted</code> is used to force explicit validation of parameters in the message handler before their values can be used (as opposed to validation in <code class="docutils literal notranslate">ParamTraits</code>). 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 <a class="reference external" href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://searchfox.org/mozilla-central/source/mfbt/Tainting.h">here</a>. Send methods that are not for async messages with return values follow a simpler form; they return a <code class="docutils literal notranslate">bool</code> indicating success or failure and return response values in non-const parameters, as the <code class="docutils literal notranslate">Recv</code> methods do. For example, <code class="docutils literal notranslate">PMyManagerChild</code> defines this to send the sync message <code class="docutils literal notranslate">SomeMsg</code>: <div class="highlight-cpp notranslate"> <div class="highlight"> <pre>// generated in PMyManagerChild bool SendSomeMsg(const Maybe<MyActorPair>& aActors, const nsTArray<MyData>& aMyData, int32_t& x, int32_t& y, MyUnion& aUnion); </pre> </div> </div> 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 <code class="docutils literal notranslate">Send</code> methods, like all messages handler <code class="docutils literal notranslate">Recv</code> methods, must only be called on the worker thread for the actor. Constructors, like the one for <code class="docutils literal notranslate">MyManaged</code>, are clearly an exception to these rules. They are discussed in the next section. </section> <section id="actor-lifetimes-in-c"> <h3>Actor Lifetimes in C++<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#actor-lifetimes-in-c" title="Link to this heading">¶</a></h3> The constructor message for <code class="docutils literal notranslate">MyManaged</code> becomes two methods at the receiving end. <code class="docutils literal notranslate">AllocPMyManagedParent</code> constructs the managed actor, then <code class="docutils literal notranslate">RecvPMyManagedConstructor</code> is called to update the new actor. The following diagram shows the construction of the <code class="docutils literal notranslate">MyManaged</code> actor pair: <figure class="align-center" id="id7"> <pre class="mermaid"> %%{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 [mgd_child, params] mgrc->>ipc: Form actor pair [mgd_child, params] par mgdc->>ipc: early PMyManaged messages and ipc->>mgrp: AllocPMyManagedParent [params] mgrp->>mgdp: new mgdp->>mgrp: [mgd_parent] ipc->>mgrp: RecvPMyManagedConstructor [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. </pre> <figcaption> A <code class="docutils literal notranslate">MyManaged</code> actor pair being created by some <code class="docutils literal notranslate">Driver</code> 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.<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#id7" title="Link to this image">¶</a> </figcaption> </figure> The next diagram shows the destruction of the <code class="docutils literal notranslate">MyManaged</code> actor pair, as initiated by a call to <code class="docutils literal notranslate">Send__delete__</code>. <code class="docutils literal notranslate">__delete__</code> is sent from the child process because that is the only side that can call it, as declared in the IPDL protocol file. <figure class="align-center" id="id8"> <pre class="mermaid"> %%{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 actor pair par ipc->>mgdc: ActorDestroy ipc->>mgdc: Release and ipc->>mgdp: Recv__delete__ ipc->>mgdp: ActorDestroy ipc->>mgdp: Release end </pre> <figcaption> A <code class="docutils literal notranslate">MyManaged</code> actor pair being disconnected due to some <code class="docutils literal notranslate">Driver</code> object in the child process sending <code class="docutils literal notranslate">__delete__</code>.<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#id8" title="Link to this image">¶</a> </figcaption> </figure> Finally, let’s take a look at the behavior of an actor whose peer has been lost (e.g. due to a crashed process). <figure class="align-center" id="id9"> <pre class="mermaid"> %%{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 </pre> <figcaption> A <code class="docutils literal notranslate">MyManaged</code> actor pair being disconnected when its peer is lost due to a fatal error. Note that <code class="docutils literal notranslate">Recv__delete__</code> is not called.<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#id9" title="Link to this image">¶</a> </figcaption> </figure> The <code class="docutils literal notranslate">Alloc</code> and <code class="docutils literal notranslate">Recv...Constructor</code> methods are somewhat mirrored by <code class="docutils literal notranslate">Recv__delete__</code> and <code class="docutils literal notranslate">ActorDestroy</code> but there are a few differences. First, the <code class="docutils literal notranslate">Alloc</code> method really does create the actor but the <code class="docutils literal notranslate">ActorDestroy</code> method does not delete it. Additionally, <code class="docutils literal notranslate">ActorDestroy</code> is run at both endpoints, during <code class="docutils literal notranslate">Send__delete__</code> or after <code class="docutils literal notranslate">Recv__delete__</code>. Finally and most importantly, <code class="docutils literal notranslate">Recv__delete__</code> is only called if the <code class="docutils literal notranslate">__delete__</code> message is received but it may not be if, for example, the remote process crashes. <code class="docutils literal notranslate">ActorDestroy</code>, on the other hand, is guaranteed to run for every actor unless the process terminates uncleanly. For this reason, <code class="docutils literal notranslate">ActorDestroy</code> is the right place for most actor shutdown code. <code class="docutils literal notranslate">Recv__delete__</code> 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: <div class="highlight-cpp notranslate"> <div class="highlight"> <pre>class MyManagerParent : public PMyManagerParent { already_AddRefed<PMyManagedParent> AllocPMyManagedParent(); IPCResult RecvPMyManagedConstructor(PMyManagedParent* aActor); IPCResult Recv__delete__(const nsString& aNote); void ActorDestroy(ActorDestroyReason why); // ... etc ... }; </pre> </div> </div> The <code class="docutils literal notranslate">Alloc</code> method is required for managed actors that are constructed by IPDL receiving a <code class="docutils literal notranslate">Send</code> message. It is not required for the actor at the endpoint that calls <code class="docutils literal notranslate">Send</code>. The <code class="docutils literal notranslate">Recv...Constructor</code> 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 <code class="docutils literal notranslate">Alloc</code> method by const reference but are moved into the <code class="docutils literal notranslate">Recv</code> method. They differ in that messages can be sent from the <code class="docutils literal notranslate">Recv</code> method but, in <code class="docutils literal notranslate">Alloc</code>, the newly created actor is not yet operational. The <code class="docutils literal notranslate">Send</code> method for a constructor is similarly different from other <code class="docutils literal notranslate">Send</code> methods. In the child actor, ours looks like this: <div class="highlight-cpp notranslate"> <div class="highlight"> <pre>IPCResult SendPMyManagedConstructor(PMyManagedChild* aActor); </pre> </div> </div> The method expects a <code class="docutils literal notranslate">PMyManagedChild</code> that the caller will have constructed, presumably using <code class="docutils literal notranslate">new</code> (this is why it does not require an <code class="docutils literal notranslate">Alloc</code> method). Once <code class="docutils literal notranslate">Send...Constructor</code> 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 <code class="docutils literal notranslate">[ManualDealloc]</code> actors removes a lot of the complexity but there is still a process to understand. Actor destruction begins when an <code class="docutils literal notranslate">__delete__</code> message is sent. In <code class="docutils literal notranslate">PMyManager</code>, this message is declared from child to parent. The actor calling <code class="docutils literal notranslate">Send__delete__</code> is no longer connected to anything when the method returns. Future calls to <code class="docutils literal notranslate">Send</code> return an error and no future messages will be received. This is also the case for an actor that has run <code class="docutils literal notranslate">Recv__delete__</code>; it is no longer connected to the other endpoint. <div class="admonition note"> Note Since <code class="docutils literal notranslate">Send__delete__</code> may release the final reference to itself, it cannot safely be a class instance method. Instead, unlike other <code class="docutils literal notranslate">Send</code> methods, it’s a <code class="docutils literal notranslate">static</code> class method and takes the actor as a parameter: <div class="highlight-cpp notranslate"> <div class="highlight"> <pre>static IPCResult Send__delete__(PMyManagerChild* aToDelete); </pre> </div> </div> Additionally, the <code class="docutils literal notranslate">__delete__</code> message tells IPDL to disconnect both the given actor and all of its managed actors. So it is really deleting the actor subtree, although <code class="docutils literal notranslate">Recv__delete__</code> is only called for the actor it was sent to. </div> During the call to <code class="docutils literal notranslate">Send__delete__</code>, or after the call to <code class="docutils literal notranslate">Recv__delete__</code>, the actor’s <code class="docutils literal notranslate">ActorDestroy</code> method is called. This method gives client code a chance to do any teardown that must happen in <cite>all</cite> circumstances were it is possible – both expected and unexpected. This means that <code class="docutils literal notranslate">ActorDestroy</code> 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 <code class="docutils literal notranslate">__delete__</code>. The only way for an actor to avoid <code class="docutils literal notranslate">ActorDestroy</code> is for its process to crash first. <code class="docutils literal notranslate">ActorDestroy</code> is always run after its actor is disconnected so it is pointless to try to send messages from it. Why use <code class="docutils literal notranslate">ActorDestroy</code> instead of the actor’s destructor? <code class="docutils literal notranslate">ActorDestroy</code> 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 <code class="docutils literal notranslate">ActorDestroy</code>, 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 <cite>only</cite> 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 <code class="docutils literal notranslate">__delete__</code> 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 <code class="docutils literal notranslate">AddRef</code> to have it send <code class="docutils literal notranslate">__delete__</code> only when it’s count is down to one reference (which must be IPDL if <code class="docutils literal notranslate">actor.CanSend()</code> is true). A better approach would be to create a reference-counted delegate for your actor that can send <code class="docutils literal notranslate">__delete__</code> from its destructor. IPDL does not guarantee that it will not hold more than one reference to your actor. </section> </section> <section id="top-level-actors"> <h2>Top Level Actors<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#top-level-actors" title="Link to this heading">¶</a></h2> 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 <a class="reference external" href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://phabricator.services.mozilla.com/D119038">new process example</a> demonstrates both of these. It is discussed in detail in <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/processes.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#adding-a-new-type-of-process">Adding a New Type of Process</a>. <section id="value-of-top-level-actors"> <h3>Value of Top Level Actors<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#value-of-top-level-actors" title="Link to this heading">¶</a></h3> 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. <div class="admonition note"> 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. </div> So why use a new top level actor? <ul class="simple"> <li>The most dramatic property distinguishing top-level actors is the ability to bind to whatever <code class="docutils literal notranslate">EventTarget</code> they choose. This means that any thread that runs a <code class="docutils literal notranslate">MessageLoop</code> can use the event target for that loop as the place to send incoming messages. In other words, <code class="docutils literal notranslate">Recv</code> 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 <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#pbackground">PBackground</a> 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.</li> <li>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).</li> <li>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 <code class="docutils literal notranslate">Endpoints</code> 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 <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/processes.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#connecting-with-other-processes">Connecting With Other Processes</a>.</li> </ul> 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, <code class="docutils literal notranslate">PBackground</code> is sometimes a simpler alternative to achieve the same goals. </section> <section id="creating-top-level-actors-from-other-actors"> <h3>Creating Top Level Actors From Other Actors<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#creating-top-level-actors-from-other-actors" title="Link to this heading">¶</a></h3> 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: <div class="highlight-cpp notranslate"> <div class="highlight"> <pre>bool MyPreexistingActorParent::MakeMyActor() { Endpoint<PMyActorParent> parentEnd; Endpoint<PMyActorChild> childEnd; if (NS_WARN_IF(NS_FAILED(PMyActor::CreateEndpoints(&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; } </pre> </div> </div> Here <code class="docutils literal notranslate">MyPreexistingActorParent</code> is used to send a child endpoint for the new top level actor to <code class="docutils literal notranslate">MyPreexistingActorChild</code>, 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 <code class="docutils literal notranslate">MyPreexistingActorParent</code> is bound to since we are sending <code class="docutils literal notranslate">CreateMyActorChild</code> 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. <code class="docutils literal notranslate">MyPreexistingActorChild</code> still has to receive the create message. The code for that handler is pretty similar: <div class="highlight-cpp notranslate"> <div class="highlight"> <pre>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(); } </pre> </div> </div> Like the parent, the child is ready to send as soon as <code class="docutils literal notranslate">Bind</code> is complete. It will start receiving messages soon afterward on the event target for the thread on which it is bound. </section> <section id="creating-first-top-level-actors"> <h3>Creating First Top Level Actors<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#creating-first-top-level-actors" title="Link to this heading">¶</a></h3> The first actor in a process is an advanced topic that is covered in <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/processes.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#adding-a-new-type-of-process">the documentation for adding a new process</a>. </section> </section> <section id="pbackground"> <h2>PBackground<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#pbackground" title="Link to this heading">¶</a></h2> Developed as a convenient alternative to top level actors, <code class="docutils literal notranslate">PBackground</code> 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 <code class="docutils literal notranslate">PBackground</code> (aka a background actor) is an option. <div class="admonition warning"> 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. </div> Background actors can only be used in limited circumstances: <ul class="simple"> <li><code class="docutils literal notranslate">PBackground</code> only supports the following process connections (where ordering is parent <-> child): main <-> main, main <-> content, main <-> socket and socket <-> content.</li> </ul> <div class="admonition important"> Important Socket process <code class="docutils literal notranslate">PBackground</code> 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 <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#top-level-actors">Top Level Actors</a> instead of <code class="docutils literal notranslate">PBackground</code> actor when communicating with socket process worker threads. </div> <ul class="simple"> <li>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.</li> <li>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.</li> <li>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 <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#the-old-ways">The Old Ways</a> for details.</li> </ul> A hypothetical layout of <code class="docutils literal notranslate">PBackground</code> threads, demonstrating some of the process-type limitations, is shown in the diagram below. <figure class="align-center" id="id10"> <pre class="mermaid"> 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 </pre> <figcaption> Hypothetical <code class="docutils literal notranslate">PBackground</code> thread setup. Arrow direction indicates child-to-parent <code class="docutils literal notranslate">PBackground</code>-managee relationships. Parents always share a thread and may be connected to multiple processes. Child threads can be any thread, including main.<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#id10" title="Link to this image">¶</a> </figcaption> </figure> Creating background actors is done a bit differently than normal managees. The new managed type and constructor are still added to <code class="docutils literal notranslate">PBackground.ipdl</code> as with normal managees but, instead of <code class="docutils literal notranslate">new</code>-ing the child actor and then passing it in a <code class="docutils literal notranslate">SendFooConstructor</code> call, background actors issue the send call to the <code class="docutils literal notranslate">BackgroundChild</code> manager, which returns the new child: <div class="highlight-cpp notranslate"> <div class="highlight"> <pre>// 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); </pre> </div> </div> <div class="admonition note"> Note <code class="docutils literal notranslate">PBackgroundParent</code> still needs a <code class="docutils literal notranslate">RecvMyBackgroundActorConstructor</code> handler, as usual. This must be done in the <code class="docutils literal notranslate">ParentImpl</code> class. <code class="docutils literal notranslate">ParentImpl</code> is the non-standard name used for the implementation of <code class="docutils literal notranslate">PBackgroundParent</code>. </div> To summarize, <code class="docutils literal notranslate">PBackground</code> 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, <code class="docutils literal notranslate">PBackground</code> offers a compromise for some cases. </section> <section id="ipdl-best-practices"> <h2>IPDL Best Practices<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#ipdl-best-practices" title="Link to this heading">¶</a></h2> 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: <ul class="simple"> <li>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.</li> <li>Even <code class="docutils literal notranslate">[moveonly]</code> 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).</li> <li>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.</li> <li>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 <code class="docutils literal notranslate">ParamTraits</code>, 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.</li> <li>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 <code class="docutils literal notranslate">PBackground</code> managee that facilitates processing messages simultaneously.</li> <li>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.</li> <li>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.</li> </ul> </section> <section id="the-old-ways"> <h2>The Old Ways<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#the-old-ways" title="Link to this heading">¶</a></h2> TODO: </section> <section id="the-fud"> <h2>The FUD<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#the-fud" title="Link to this heading">¶</a></h2> TODO: </section> <section id="the-rest"> <h2>The Rest<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#the-rest" title="Link to this heading">¶</a></h2> <section id="nested-messages"> <h3>Nested messages<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#nested-messages" title="Link to this heading">¶</a></h3> The <code class="docutils literal notranslate">Nested</code> 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, <code class="docutils literal notranslate">Nested</code> messages can make other <code class="docutils literal notranslate">sync</code> 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 <code class="docutils literal notranslate">sync</code> message <code class="docutils literal notranslate">M</code> to handle and respond to some special (nested) messages that may be needed for the other endpoint to finish processing <code class="docutils literal notranslate">M</code>. There is a <a class="reference external" href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://searchfox.org/mozilla-central/rev/077501b34cca91763ae04f4633a42fddd919fdbd/ipc/glue/MessageChannel.cpp%2354-118">comment in MessageChannel</a> 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 <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#defining-actors">Defining Actors</a> and <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#declaring-ipdl-messages">Declaring IPDL Messages</a>. 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: <table class="docutils align-default"> <tbody> <tr class="row-odd"> <td><code class="docutils literal notranslate">[NestedUpTo=inside_sync]</code></td> <td>Indicates that an actor contains messages of priority [Nested=inside_sync] or lower.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">[NestedUpTo=inside_cpow]</code></td> <td>Indicates that an actor contains messages of priority [Nested=inside_cpow] or lower.</td> </tr> </tbody> </table> <div class="admonition note"> Note The order of the nesting priorities is: (no nesting priority) < <code class="docutils literal notranslate">inside_sync</code> < <code class="docutils literal notranslate">inside_cpow</code>. </div> The message annotations are: <table class="docutils align-default"> <tbody> <tr class="row-odd"> <td><code class="docutils literal notranslate">[Nested=inside_sync]</code></td> <td>Indicates that the message can be handled while waiting for lower-priority, or in-message-thread, sync responses.</td> </tr> <tr class="row-even"> <td><code class="docutils literal notranslate">[Nested=inside_cpow]</code></td> <td>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.</td> </tr> </tbody> </table> <div class="admonition note"> Note <code class="docutils literal notranslate">[Nested=inside_sync]</code> messages must be sync (this is enforced by the IPDL compiler) but <code class="docutils literal notranslate">[Nested=inside_cpow]</code> may be async. </div> 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 <code class="docutils literal notranslate">actorX</code> is waiting for a sync reply from <code class="docutils literal notranslate">actorY</code> for message <code class="docutils literal notranslate">m1</code> when <code class="docutils literal notranslate">actorY</code> sends <code class="docutils literal notranslate">actorX</code> a message <code class="docutils literal notranslate">m2</code>. We distinguish two cases here: (1) when <code class="docutils literal notranslate">m2</code> is sent while processing <code class="docutils literal notranslate">m1</code> (so <code class="docutils literal notranslate">m2</code> is sent by the <code class="docutils literal notranslate">RecvM1()</code> method – this is what we mean when we say “nested”) and (2) when <code class="docutils literal notranslate">m2</code> is unrelated to <code class="docutils literal notranslate">m1</code>. Case (2) is easy; <code class="docutils literal notranslate">m2</code> is only dispatched while <code class="docutils literal notranslate">m1</code> waits if <code class="docutils literal notranslate">priority(m2) > priority(m1) > (no priority)</code> and the message is being received by the parent, or if <code class="docutils literal notranslate">priority(m2) >= priority(m1) > (no priority)</code> 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) <code class="docutils literal notranslate">m1</code> is sent by the parent to the child and <code class="docutils literal notranslate">m2</code> is sent by the child to the parent, or (B) where the directions are reversed. The following tables explain what happens in all cases: <table class="docutils align-center" id="id11"> <caption> Case (A): Child sends message to a parent that is awaiting a sync response<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#id11" title="Link to this table">¶</a> </caption> <thead> <tr class="row-odd"> <th class="head">sync <code class="docutils literal notranslate">m1</code> type (from parent)</th> <th class="head"><code class="docutils literal notranslate">m2</code> type (from child)</th> <th class="head"><code class="docutils literal notranslate">m2</code> handled or rejected</th> </tr> </thead> <tbody> <tr class="row-even"> <td>sync (no priority)</td> <td>*</td> <td>IPDL compiler error: parent cannot send sync (no priority)</td> </tr> <tr class="row-odd"> <td>sync inside_sync</td> <td>async (no priority)</td> <td><strike> <code class="docutils literal notranslate">m2</code> delayed until after <code class="docutils literal notranslate">m1</code> completes </strike> Currently <code class="docutils literal notranslate">m2</code> is handled during the sync wait (bug?)</td> </tr> <tr class="row-even"> <td>sync inside_sync</td> <td>sync (no priority)</td> <td><strike> <code class="docutils literal notranslate">m2</code> send fails: lower priority than <code class="docutils literal notranslate">m1</code> </strike> Currently <code class="docutils literal notranslate">m2</code> is handled during the sync wait (bug?)</td> </tr> <tr class="row-odd"> <td>sync inside_sync</td> <td>sync inside_sync</td> <td><code class="docutils literal notranslate">m2</code> handled during <code class="docutils literal notranslate">m1</code> sync wait: same message thread and same priority</td> </tr> <tr class="row-even"> <td>sync inside_sync</td> <td>async inside_cpow</td> <td><code class="docutils literal notranslate">m2</code> handled during <code class="docutils literal notranslate">m1</code> sync wait: higher priority</td> </tr> <tr class="row-odd"> <td>sync inside_sync</td> <td>sync inside_cpow</td> <td><code class="docutils literal notranslate">m2</code> handled during <code class="docutils literal notranslate">m1</code> sync wait: higher priority</td> </tr> <tr class="row-even"> <td>sync inside_cpow</td> <td>*</td> <td>IPDL compiler error: parent cannot use inside_cpow priority</td> </tr> </tbody> </table> <table class="docutils align-center" id="id12"> <caption> Case (B): Parent sends message to a child that is awaiting a sync response<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#id12" title="Link to this table">¶</a> </caption> <thead> <tr class="row-odd"> <th class="head">sync <code class="docutils literal notranslate">m1</code> type (from child)</th> <th class="head"><code class="docutils literal notranslate">m2</code> type (from parent)</th> <th class="head"><code class="docutils literal notranslate">m2</code> handled or rejected</th> </tr> </thead> <tbody> <tr class="row-even"> <td>*</td> <td>async (no priority)</td> <td><code class="docutils literal notranslate">m2</code> delayed until after <code class="docutils literal notranslate">m1</code> completes</td> </tr> <tr class="row-odd"> <td>*</td> <td>sync (no priority)</td> <td>IPDL compiler error: parent cannot send sync (no priority)</td> </tr> <tr class="row-even"> <td>sync (no priority)</td> <td>sync inside_sync</td> <td><code class="docutils literal notranslate">m2</code> send fails: no-priority sync messages cannot handle incoming messages during wait</td> </tr> <tr class="row-odd"> <td>sync inside_sync</td> <td>sync inside_sync</td> <td><code class="docutils literal notranslate">m2</code> handled during <code class="docutils literal notranslate">m1</code> sync wait: same message thread and same priority</td> </tr> <tr class="row-even"> <td>sync inside_cpow</td> <td>sync inside_sync</td> <td><code class="docutils literal notranslate">m2</code> send fails: lower priority than <code class="docutils literal notranslate">m1</code></td> </tr> <tr class="row-odd"> <td>*</td> <td>async inside_cpow</td> <td>IPDL compiler error: parent cannot use inside_cpow priority</td> </tr> <tr class="row-even"> <td>*</td> <td>sync inside_cpow</td> <td>IPDL compiler error: parent cannot use inside_cpow priority</td> </tr> </tbody> </table> We haven’t seen rule #2 from the <a class="reference external" href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://searchfox.org/mozilla-central/rev/077501b34cca91763ae04f4633a42fddd919fdbd/ipc/glue/MessageChannel.cpp%2354-118">comment in MessageChannel</a> 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. </section> <section id="message-logging"> <h3>Message Logging<a class="headerlink" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/ipdl.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#message-logging" title="Link to this heading">¶</a></h3> The environment variable <code class="docutils literal notranslate">MOZ_IPC_MESSAGE_LOG</code> controls the logging of IPC messages. It logs details about the transmission and reception of messages. This isn’t controlled by <code class="docutils literal notranslate">MOZ_LOG</code> – it is a separate system. Set this variable to <code class="docutils literal notranslate">1</code> to log information on all IPDL messages, or specify a comma-separated list of protocols to log. If the <code class="docutils literal notranslate">Child</code> or <code class="docutils literal notranslate">Parent</code> suffix is given, then only activity on the given side is logged; otherwise, both sides are logged. All protocol names must include the <code class="docutils literal notranslate">P</code> prefix. For example: <div class="highlight-default notranslate"> <div class="highlight"> <pre>MOZ_IPC_MESSAGE_LOG="PMyManagerChild,PMyManaged" </pre> </div> </div> This requests logging of child-side activity on <code class="docutils literal notranslate">PMyManager</code>, and both parent- and child-side activity on <code class="docutils literal notranslate">PMyManaged</code>. <a class="reference internal" href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/processes.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB#debugging-with-ipdl-logging">Debugging with IPDL Logging</a> has an example where IPDL logging is useful in tracking down a bug. </section> </section> </section> </div> </div> <footer> <div class="rst-footer-buttons" role="navigation" aria-label="Footer"><a href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/index.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB" class="btn btn-neutral float-left" title="Processes, Threads and IPC" accesskey="p" rel="prev"> Previous</a> <a href="https://firefox--source--docs-mozilla-org.translate.goog/ipc/processes.html?_x_tr_sl=pl&_x_tr_tl=iw&_x_tr_hl=en-GB" class="btn btn-neutral float-right" title="Gecko Processes" accesskey="n" rel="next">Next </a> </div> <hr> <div role="contentinfo"> </div> Built with <a href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://www.sphinx-doc.org/">Sphinx</a> using a <a href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://github.com/readthedocs/sphinx_rtd_theme">theme</a> provided by <a href="https://translate.google.com/website?sl=pl&tl=iw&hl=en-GB&u=https://readthedocs.org">Read the Docs</a>. </footer> </div> </div> </section> </div> <script> jQuery(function () { SphinxRtdTheme.Navigation.enable(true); }); </script> <script>function gtElInit() {var lib = new google.translate.TranslateService();lib.translatePage('pl', 'iw', function () {});}</script> <script src="https://translate.google.com/translate_a/element.js?cb=gtElInit&hl=en-GB&client=wt" type="text/javascript"></script> </body> </html>