diff options
Diffstat (limited to 'dom/docs/ipc')
| -rw-r--r-- | dom/docs/ipc/Fission-IPC-Diagram.svg | 5 | ||||
| -rw-r--r-- | dom/docs/ipc/Fission-actors-diagram.png | bin | 0 -> 69010 bytes | |||
| -rw-r--r-- | dom/docs/ipc/Fission-framescripts.png | bin | 0 -> 84425 bytes | |||
| -rw-r--r-- | dom/docs/ipc/index.rst | 9 | ||||
| -rw-r--r-- | dom/docs/ipc/jsactors.rst | 547 | ||||
| -rw-r--r-- | dom/docs/ipc/mainthread.rst | 13 | ||||
| -rw-r--r-- | dom/docs/ipc/process_model.rst | 334 |
7 files changed, 908 insertions, 0 deletions
diff --git a/dom/docs/ipc/Fission-IPC-Diagram.svg b/dom/docs/ipc/Fission-IPC-Diagram.svg new file mode 100644 index 0000000000..f53d4b65b4 --- /dev/null +++ b/dom/docs/ipc/Fission-IPC-Diagram.svg @@ -0,0 +1,5 @@ +<!-- This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. --> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<svg xmlns="http://www.w3.org/2000/svg" style="background-color: rgb(255, 255, 255);" version="1.1" width="841px" height="861px" viewBox="-0.5 -0.5 841 861" content="<mxfile modified="2019-04-26T17:33:16.547Z" host="www.draw.io" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:68.0) Gecko/20100101 Firefox/68.0" etag="ryQDoUVJ1oS_b3fguxas" version="10.6.5" type="google"><diagram id="GcJpJ4Eku4OUxVByAJcz" name="Page-1">7Vxbc9o6EP41PDZjyzd4DCSkZ6ZnJnNyZto+dYQtQImxOLZISH/9kWzJNxlsKAY1pQ+ptbp6d7/VrrRmYE1W24cYrpd/kwCFA2AE24F1NwBgZA7ZX054zwiO7WWERYyDjGQWhCf8EwmiIagbHKCk0pASElK8rhJ9EkXIpxUajGPyVm02J2F11jVcIIXw5MNQpX7FAV1m1KFjFPTPCC+WcmbTEDUrKBsLQrKEAXkrkaz7gTWJCaHZ02o7QSHnneRL1m+6ozZfWIwi2qXDN289dbav0x8Pw89T4IHk2f7nkxjlFYYb8cJisfRdciAmmyhAfBBzYI3flpiipzX0ee0bEzmjLekqFNXqouQMKKZoWyKJRT4gskI0fmdNRK0t+CUUxrSNGyejvBUC8FzRalliPpC8h0Loi3zwgi/sQbDmADYB7dlkgyY22cMGNtm9scnSj02O24VPOTfPwydb4dOYWyoUM+JjTHyUJArj2PvSKncSGpMXNCEhiRklIhFrOZ7jMKyRYIgXESv6jItsCmvMuYeZibsVFSscBHyaRnEUAjP48CSiT2JRDRboYPEM62C3G6RjNkkH9CUcp0GJ3ZDzPsCv7HHBHyeMD/ytS/LK2rApS83+TCl6I/PCMnSvMjxUhq6pmxCBo7AeBcw5E0US0yVZkAiG9wW1xqSizRdC1kJaz4jSd+Fpwg0lVVmiLabfeHdmiLLS91LN3VaMnBbeZSFi71vqxIvfy3VFt7Qk+zXqTUJhTG+568o1JYRJgn1JnuKwdW9MyCb20R6+CgecjbdAdE874blznu9VoBiFkOLXqsN8em3w2p2LM6jHVTr7Vr3f4LL/4YpbsrRiu2Ez3M5yxyeJ/bSn+9+Gh0RjeOOTVVHk65P95WiN1lqZNkqmMVyhLwQGfKKsfhbXe7RY/arm9O+4jmqekdfkt5qgwSC7vRnk0U4p892owi8pNl7xKUnRdMsamGC9Lcs0Y/Zj7v7mosgG3CELfXB+rOU/3j4MO9qH0antg+j6SHAqaqnETi2+MnM9lYNkSxX9aiqYL+R4rRwqSim06THjrmZAZvC8OJAt48/YS0cdsSJdX002U9XMCo2eLHEY6KbQduMB3ZkV2lS48uFChZ6xIjHQDhZTK7CYqi2Lkq9olrsUeqHFsTRAy0Ws/cdCi7yLakUL0AstTRc+LYEanvPwqSFCm/Uaoekdj7nyYvNiKLatS6LYLGG4QHQbiisYvvGci8MYdIVxP+EUezf4Xmqw5kFSUhq5Fm05Ru2Q1hqJ3WTasQcL2Ko92EO2ipMGZbZ6ICSD/HGMORPruqueqscowT/hLG3AtUEwh7V2xgPnbnDIeXoIZygcQ/9lkSJAHrkOgDVP/zVq0V7YKZYjz0EQSx6Ur/mbLIpxYw09cVNxbBQupJorsuxC5vME9RJuy5nU6CQTrJYximeMLu91Nd2Ol7bCYw/PznQE12lTvrqRB+4/dtf9x9HLjdyZwaDJoZvlaHjqZv8ueOlf752Oeg/0Opkz1eQQrY7m6mqvxdnc7oSaD3drpCfY3K6bjKcX2NQsHr02GRdouMl4V72vqXP7JqPZibYaO2u1ydTVXodNxv5tLoD6V/uuGQLSiddF7Xde5GcHC5oY/bqLpUNijuX+LtqvbyTeOVfA1Qs1O5MFtEJNfc/QATVA85vjuqXR4up4dLU0v2hp8s8YW91SoJWlyRVYU7jUTYwOcJHfS1zhcjxcQFe4WHrBBShwOT7Tot9ceM0yLepA1iDV4jIn9xKSZgWQN+BEaRO5mSgZibZUjufNai1fG3Il/RVkW11d7pN/69KcK1FXPA8ouezZSym57AfncdS/mGzP46h/KTs8Tx6HGl7onscR4Bj5FBPej4mLW4zOuR3yWvMEuR3G0AEVicnfWjhWSftP7QBqhoKGqR0KSjXI7ZCibtjsl6bcWB+Q/0JYo78e2STGnCkuMKaYGWemqvu+SitGaNjQ77fMDeCiuO3sA1zoM7y8WzRL1mnZOHeeqbqEtnLXJXblUvtnh02LPu6LxeO/U08YfnG0YASnKP2bui381KQZ5YRBeB6mPseSmWsUKT7QCcBf/3EYQwH+0GgAfm4NDkA+KxY/zpOZ2OIXjqz7/wE=</diagram></mxfile>"><defs/><g><rect x="20" y="160.5" width="760" height="200" rx="30" ry="30" fill="#ffffff" stroke="#000000" pointer-events="none"/><rect x="20" y="440.5" width="480" height="400" rx="60" ry="60" fill="#ffffff" stroke="#000000" pointer-events="none"/><rect x="540" y="440.5" width="240" height="400" rx="36" ry="36" fill="#ffffff" stroke="#000000" pointer-events="none"/><g transform="translate(80.5,168.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="98" height="12" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 99px; white-space: nowrap; overflow-wrap: normal; font-weight: bold; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;">Browser Process</div></div></foreignObject><text x="49" y="12" fill="#000000" text-anchor="middle" font-size="12px" font-family="Helvetica" font-weight="bold">Browser Process</text></switch></g><g transform="translate(82.5,814.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="95" height="12" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 96px; white-space: nowrap; overflow-wrap: normal; font-weight: bold; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;"><div>Content Process</div></div></div></foreignObject><text x="48" y="12" fill="#000000" text-anchor="middle" font-size="12px" font-family="Helvetica" font-weight="bold"><div>Content Process</div></text></switch></g><g transform="translate(612.5,814.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="95" height="12" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 96px; white-space: nowrap; overflow-wrap: normal; font-weight: bold; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;"><div>Content Process</div></div></div></foreignObject><text x="48" y="12" fill="#000000" text-anchor="middle" font-size="12px" font-family="Helvetica" font-weight="bold"><div>Content Process</div></text></switch></g><path d="M 130 256.87 L 130 271 L 130 261 L 130 274.13" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 130 251.62 L 133.5 258.62 L 130 256.87 L 126.5 258.62 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 130 279.38 L 126.5 272.38 L 130 274.13 L 133.5 272.38 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><rect x="70" y="190.5" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="none"/><g transform="translate(71.5,199.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="116" height="41" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 116px; white-space: normal; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;"><div><xul:browser src="a.com"/></div><div>nsFrameLoader<br /></div></div></div></foreignObject><text x="58" y="27" fill="#000000" text-anchor="middle" font-size="12px" font-family="Helvetica">[Not supported by viewer]</text></switch></g><path d="M 130 346.87 L 130 454.63" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 130 341.62 L 133.5 348.62 L 130 346.87 L 126.5 348.62 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 130 459.88 L 126.5 452.88 L 130 454.63 L 133.5 452.88 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><g transform="translate(103.5,394.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="52" height="12" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 11px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; white-space: nowrap; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;background-color:#ffffff;"><font style="font-size: 12px">PBrowser</font></div></div></foreignObject><text x="26" y="12" fill="#000000" text-anchor="middle" font-size="11px" font-family="Helvetica">[Not supported by viewer]</text></switch></g><rect x="70" y="280.5" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="none"/><g transform="translate(90.5,304.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="79" height="12" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 80px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;">BrowserParent</div></div></foreignObject><text x="40" y="12" fill="#000000" text-anchor="middle" font-size="12px" font-family="Helvetica">BrowserParent</text></switch></g><path d="M 130 526.87 L 130 541 L 130 531 L 130 544.13" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 130 521.62 L 133.5 528.62 L 130 526.87 L 126.5 528.62 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 130 549.38 L 126.5 542.38 L 130 544.13 L 133.5 542.38 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><rect x="70" y="460.5" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="none"/><g transform="translate(94.5,484.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="71" height="12" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 72px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;">BrowserChild</div></div></foreignObject><text x="36" y="12" fill="#000000" text-anchor="middle" font-size="12px" font-family="Helvetica">BrowserChild</text></switch></g><path d="M 130 617.37 L 130 631.63" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 130 612.12 L 133.5 619.12 L 130 617.37 L 126.5 619.12 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 130 636.88 L 126.5 629.88 L 130 631.63 L 133.5 629.88 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><rect x="70" y="550.5" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="none"/><g transform="translate(89.5,574.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="81" height="12" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 82px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;">nsWebBrowser</div></div></foreignObject><text x="41" y="12" fill="#000000" text-anchor="middle" font-size="12px" font-family="Helvetica">nsWebBrowser</text></switch></g><path d="M 130 704.37 L 130 723.63" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 130 699.12 L 133.5 706.12 L 130 704.37 L 126.5 706.12 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 130 728.88 L 126.5 721.88 L 130 723.63 L 133.5 721.88 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><rect x="70" y="638" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="none"/><g transform="translate(71.5,647.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="116" height="41" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 116px; white-space: normal; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;"><div><iframe src="b.com"/></div><div>nsFrameLoader</div></div></div></foreignObject><text x="58" y="27" fill="#000000" text-anchor="middle" font-size="12px" font-family="Helvetica">[Not supported by viewer]</text></switch></g><path d="M 196.37 760 L 480 760 L 480 236 L 593.63 236" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 191.12 760 L 198.12 756.5 L 196.37 760 L 198.12 763.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 598.88 236 L 591.88 239.5 L 593.63 236 L 591.88 232.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><g transform="translate(436.5,384.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="87" height="12" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; white-space: nowrap; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;background-color:#ffffff;">PBrowserBridge</div></div></foreignObject><text x="44" y="12" fill="#000000" text-anchor="middle" font-size="12px" font-family="Helvetica">PBrowserBridge</text></switch></g><rect x="70" y="729.5" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="none"/><g transform="translate(76.5,753.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="106" height="12" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 107px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;">BrowserBridgeChild</div></div></foreignObject><text x="53" y="12" fill="#000000" text-anchor="middle" font-size="12px" font-family="Helvetica">BrowserBridgeChild</text></switch></g><path d="M 390 347.37 L 390 454.63" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 390 342.12 L 393.5 349.12 L 390 347.37 L 386.5 349.12 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 390 459.88 L 386.5 452.88 L 390 454.63 L 393.5 452.88 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><g transform="translate(363.5,394.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="52" height="12" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 11px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; white-space: nowrap; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;background-color:#ffffff;"><div style="font-size: 12px"><font style="font-size: 12px">PBrowser</font></div></div></div></foreignObject><text x="26" y="12" fill="#000000" text-anchor="middle" font-size="11px" font-family="Helvetica">[Not supported by viewer]</text></switch></g><rect x="330" y="280.5" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="none"/><g transform="translate(350.5,304.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="79" height="12" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 80px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;">BrowserParent</div></div></foreignObject><text x="40" y="12" fill="#000000" text-anchor="middle" font-size="12px" font-family="Helvetica">BrowserParent</text></switch></g><path d="M 390 527.37 L 390 541 L 390 531 L 390 544.13" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 390 522.12 L 393.5 529.12 L 390 527.37 L 386.5 529.12 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 390 549.38 L 386.5 542.38 L 390 544.13 L 393.5 542.38 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><rect x="330" y="460.5" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="none"/><g transform="translate(354.5,484.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="71" height="12" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 72px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;">BrowserChild</div></div></foreignObject><text x="36" y="12" fill="#000000" text-anchor="middle" font-size="12px" font-family="Helvetica">BrowserChild</text></switch></g><path d="M 660 347.37 L 660 454.13" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 660 342.12 L 663.5 349.12 L 660 347.37 L 656.5 349.12 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 660 459.38 L 656.5 452.38 L 660 454.13 L 663.5 452.38 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><g transform="translate(633.5,394.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="52" height="12" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 11px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; white-space: nowrap; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;background-color:#ffffff;"><font style="font-size: 12px">PBrowser</font></div></div></foreignObject><text x="26" y="12" fill="#000000" text-anchor="middle" font-size="11px" font-family="Helvetica">[Not supported by viewer]</text></switch></g><rect x="600" y="280.5" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="none"/><g transform="translate(620.5,304.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="79" height="12" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 80px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;">BrowserParent</div></div></foreignObject><text x="40" y="12" fill="#000000" text-anchor="middle" font-size="12px" font-family="Helvetica">BrowserParent</text></switch></g><path d="M 660 527.37 L 660 541 L 660 531 L 660 544.13" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 660 522.12 L 663.5 529.12 L 660 527.37 L 656.5 529.12 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 660 549.38 L 656.5 542.38 L 660 544.13 L 663.5 542.38 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><rect x="600" y="460.5" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="none"/><g transform="translate(624.5,484.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="71" height="12" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 72px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;">BrowserChild</div></div></foreignObject><text x="36" y="12" fill="#000000" text-anchor="middle" font-size="12px" font-family="Helvetica">BrowserChild</text></switch></g><path d="M 390 257.37 L 390 271 L 390 261 L 390 274.13" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 390 252.12 L 393.5 259.12 L 390 257.37 L 386.5 259.12 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 390 279.38 L 386.5 272.38 L 390 274.13 L 393.5 272.38 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><rect x="330" y="190.5" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="none"/><g transform="translate(332.5,214.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="114" height="12" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 115px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;">BrowserBridgeParent</div></div></foreignObject><text x="57" y="12" fill="#000000" text-anchor="middle" font-size="12px" font-family="Helvetica">BrowserBridgeParent</text></switch></g><path d="M 660 257.37 L 660 274.63" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 660 252.12 L 663.5 259.12 L 660 257.37 L 656.5 259.12 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 660 279.88 L 656.5 272.88 L 660 274.63 L 663.5 272.88 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><rect x="600" y="190.5" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="none"/><g transform="translate(602.5,214.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="114" height="12" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 115px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;">BrowserBridgeParent</div></div></foreignObject><text x="57" y="12" fill="#000000" text-anchor="middle" font-size="12px" font-family="Helvetica">BrowserBridgeParent</text></switch></g><rect x="330" y="550.5" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="none"/><g transform="translate(349.5,574.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="81" height="12" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 82px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;">nsWebBrowser</div></div></foreignObject><text x="41" y="12" fill="#000000" text-anchor="middle" font-size="12px" font-family="Helvetica">nsWebBrowser</text></switch></g><path d="M 660 617.37 L 660 631.63" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 660 612.12 L 663.5 619.12 L 660 617.37 L 656.5 619.12 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 660 636.88 L 656.5 629.88 L 660 631.63 L 663.5 629.88 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><rect x="600" y="550.5" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="none"/><g transform="translate(619.5,574.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="81" height="12" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 82px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;">nsWebBrowser</div></div></foreignObject><text x="41" y="12" fill="#000000" text-anchor="middle" font-size="12px" font-family="Helvetica">nsWebBrowser</text></switch></g><path d="M 660 704.37 L 660 723.63" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 660 699.12 L 663.5 706.12 L 660 704.37 L 656.5 706.12 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 660 728.88 L 656.5 721.88 L 660 723.63 L 663.5 721.88 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><rect x="600" y="638" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="none"/><g transform="translate(601.5,647.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="116" height="41" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 116px; white-space: normal; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;"><div><iframe src="a.com"/></div><div>nsFrameLoader</div></div></div></foreignObject><text x="58" y="27" fill="#000000" text-anchor="middle" font-size="12px" font-family="Helvetica">[Not supported by viewer]</text></switch></g><path d="M 593.63 760 L 560 760 L 560 239 C 563.9 239 563.9 233 560 233 L 560 233 L 560 206 L 456.37 206" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 598.88 760 L 591.88 763.5 L 593.63 760 L 591.88 756.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><path d="M 451.12 206 L 458.12 202.5 L 456.37 206 L 458.12 209.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="none"/><g transform="translate(517.5,412.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="87" height="12" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; white-space: nowrap; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;background-color:#ffffff;">PBrowserBridge</div></div></foreignObject><text x="44" y="12" fill="#000000" text-anchor="middle" font-size="12px" font-family="Helvetica">PBrowserBridge</text></switch></g><rect x="600" y="729.5" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="none"/><g transform="translate(606.5,753.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="106" height="12" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; width: 107px; white-space: nowrap; overflow-wrap: normal; text-align: center;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;">BrowserBridgeChild</div></div></foreignObject><text x="53" y="12" fill="#000000" text-anchor="middle" font-size="12px" font-family="Helvetica">BrowserBridgeChild</text></switch></g><g transform="translate(24.5,19.5)"><switch><foreignObject style="overflow:visible;" pointer-events="all" width="249" height="130" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; vertical-align: top; overflow: hidden; max-height: 130px; max-width: 790px; width: 250px; white-space: normal; overflow-wrap: normal;"><div xmlns="http://www.w3.org/1999/xhtml" style="display:inline-block;text-align:inherit;text-decoration:inherit;"><h1>Gecko IPC for Fission<br /></h1><div>Example:</div><div><xul:browser src="a.com"/></div><div> <iframe src="b.com"/></div><div> <iframe src="a.com"/><br /></div><div><br /></div></div></div></foreignObject><text x="125" y="71" fill="#000000" text-anchor="middle" font-size="12px" font-family="Helvetica">[Not supported by viewer]</text></switch></g></g></svg>
\ No newline at end of file diff --git a/dom/docs/ipc/Fission-actors-diagram.png b/dom/docs/ipc/Fission-actors-diagram.png Binary files differnew file mode 100644 index 0000000000..d3acce2c5c --- /dev/null +++ b/dom/docs/ipc/Fission-actors-diagram.png diff --git a/dom/docs/ipc/Fission-framescripts.png b/dom/docs/ipc/Fission-framescripts.png Binary files differnew file mode 100644 index 0000000000..98748bc965 --- /dev/null +++ b/dom/docs/ipc/Fission-framescripts.png diff --git a/dom/docs/ipc/index.rst b/dom/docs/ipc/index.rst new file mode 100644 index 0000000000..4a044ab906 --- /dev/null +++ b/dom/docs/ipc/index.rst @@ -0,0 +1,9 @@ +DOM IPC +======= + +.. toctree:: + :maxdepth: 1 + + jsactors + mainthread + process_model diff --git a/dom/docs/ipc/jsactors.rst b/dom/docs/ipc/jsactors.rst new file mode 100644 index 0000000000..3cd2d63c79 --- /dev/null +++ b/dom/docs/ipc/jsactors.rst @@ -0,0 +1,547 @@ +JSActors +======== + +In the Fission world, the preferred method of communication between between things-that-may-live-in-a-different-process are JSActors. + +At the time of this writing, Fission offers the following JSActors: + +- `JSProcessActor`, to communicate between a child process and its parent; +- `JSWindowActor`, to communicate between a frame and its parent. + +JSProcessActor +--------------- + +What are JSProcessActors? +~~~~~~~~~~~~~~~~~~~~~~~~~ + +A JSProcess pair (see below) is the preferred method of communication between a child process and its parent process. + +In the Fission world, JSProcessActors are the replacement for e10s-era *process scripts*. + +The life of a JSProcessActor pair +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +JSProcessActors always exist by pair: + +- one instance of `JSProcessActorChild`, which lives in the child process – for instance, `MyActorChild`; +- one instance of `JSProcessActorParent`, which lives in the parent process – for instance, `MyActorParent`. + +The pair is instantiated lazily, upon the first call to `getActor("MyActor")` (see below). Note that if a +parent process has several children, the parent process will typically host several instances of `MyActorParent` +whereas the children will each host a single instance of `MyActorChild`. + +JSProcessActor primitives allow sending and receiving messages *within the pair*. As of this writing, +JSProcessActor does not offer primitives for broadcasting, enumerating, etc. + +The pair dies when the child process dies. + +About actor names +`````````````````` + +Note that the names +`MyActorChild` and `MyActorParent` are meaningful – suffixes `Child` and `Parent` are how `getActor(...)` finds +the correct classes to load within the JS code. + + +JSWindowActor +--------------- + +What are JSWindowActors? +~~~~~~~~~~~~~~~~~~~~~~~~~ + +A JSWindowActor pair (see below) is the preferred method of communication between a frame and its parent, regardless of whether the frame +and parent live in the same process or in distinct processes. + +In the Fission world, JSWindowActors are the replacement for *framescripts*. Framescripts were how we structured code to be aware of the parent (UI) and child (content) separation, including establishing the communication channel between the two (via the Frame Message Manager). + +However, the framescripts had no way to establish further process separation downwards (that is, for out-of-process iframes). JSWindowActors will be the replacement. + +How are they structured? +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A review of the pre-Fission Message Manager mechanism +````````````````````````````````````````````````````` + +.. note:: + There are actually several types of Message Managers: Frame Message Managers, Window Message Managers, Group Message Managers and Process Message Managers. For the purposes of this documentation, it's simplest to refer to all of these mechanisms altogether as the "Message Manager mechanism". Most of the examples in this document will be operating on the assumption that the Message Manager is a Frame Message Manager, which is the most commonly used one. + +Currently, in the post `Electrolysis Project`_ Firefox codebase, we have code living in the parent process (UI) that is in plain JS (.js files) or in JS modules (.jsm files). In the child process (hosting the content), we use framescripts (.js) and also JS modules. The framescripts are instantiated once per top-level frame (or, in simpler terms, once per tab). This code has access to all of the DOM from the web content, including all iframes within it. + +The two processes communicate via the Frame Message Manager (mm) using the ``sendAsyncMessage`` / ``receiveMessage`` API, and any code in the parent can communicate with any code in the child (and vice versa), by just listening to the messages of interest. + +The Frame Message Manager communication mechanism follows a publish / subscribe pattern similar to how Events work in Firefox: + +1. Something exposes a mechanism for subscribing to notifications (``addMessageListener`` for the Frame Message Manager, ``addEventListener`` for Events). +2. The subscriber is responsible for unsubscribing when there's no longer interest in the notifications (``removeMessageListener`` for the Frame Message Manager, ``removeEventListener`` for Events). +3. Any number of subscribers can be attached at any one time. + +.. figure:: Fission-framescripts.png + :width: 320px + :height: 200px + +How JSWindowActors differ from the Frame Message Manager +`````````````````````````````````````````````````````````` + +For Fission, the JSWindowActors replacing framescripts will be structured in pairs. A pair of JSWindowActors will be instantiated lazily: one in the parent and one in the child process, and a direct channel of communication between the two will be established. The JSWindowActor in the parent must extend the global ``JSWindowActorParent`` class, and the JSWindowActor in the child must extend the global ``JSWindowActorChild`` class. + +The JSWindowActor mechanism is similar to how `IPC Actors`_ work in the native layer of Firefox: + +#. Every Actor has one counterpart in another process that they can communicate directly with. +#. Every Actor inherits a common communications API from a parent class. +#. Every Actor has a name that ends in either ``Parent`` or ``Child``. +#. There is no built-in mechanism for subscribing to messages. When one JSWindowActor sends a message, the counterpart JSWindowActor on the other side will receive it without needing to explicitly listen for it. + +Other notable differences between JSWindowActor's and Message Manager / framescripts: + +#. Each JSWindowActor pair is associated with a particular frame. For example, given the following DOM hierarchy:: + + <browser src="https://www.example.com"> + <iframe src="https://www.a.com" /> + <iframe src="https://www.b.com" /> + + A ``JSWindowActorParent`` / ``JSWindowActorChild`` pair instantiated for either of the ``iframe``'s would only be sending messages to and from that ``iframe``. + +#. There's only one pair per actor type, per frame. + + For example, suppose we have a ``ContextMenu`` actor. The parent process can have up to N instances of the ``ContextMenuParent`` actor, where N is the number of frames that are currently loaded. For any individual frame though, there's only ever one `ContextMenuChild` associated with that frame. + +#. We can no longer assume full, synchronous access to the frame tree, even in content processes. + + This is a natural consequence of splitting frames to run out-of-process. + +#. ``JSWindowActorChild``'s live as long as the ``WindowGlobalChild`` they're associated with. + + If in the previously mentioned DOM hierarchy, one of the ``<iframe>``'s unload, any associated JSWindowActor pairs will be torn down. + +.. hint:: + JSWindowActors are "managed" by the WindowGlobal IPC Actors, and are implemented as JS classes (subclasses of ``JSWindowActorParent`` and ``JSWindowActorChild``) instantiated when requested for any particular window. Like the Frame Message Manager, they are ultimately using IPC Actors to communicate under the hood. + +.. figure:: Fission-actors-diagram.png + :width: 233px + :height: 240px + +.. note:: + Like the Message Manager, JSWindowActors are implemented for both in-process and out-of-process frame communication. This means that porting to JSWindowActors can be done immediately without waiting for out-of-process iframes to be enabled. + + +Communication with actors +------------------------- + +Sending messages +~~~~~~~~~~~~~~~~ + +The ``JSActor`` base class exposes two methods for sending messages. Both methods are asynchronous. +There **is no way to send messages synchronously** with ``JSActor``. + + +``sendAsyncMessage`` +```````````````````` + + sendAsyncMessage("SomeMessage", value); + +Where `value` is anything that can be serialized using the structured clone algorithm. Additionally, a ``nsIPrincipal`` can be sent without having to manually serializing and deserializing it. + +.. note:: + Cross Process Object Wrappers (CPOWs) cannot be sent over JSWindowActors. + + +``sendQuery`` +````````````` + + Promise<any> sendQuery("SomeMessage", value); + + +``sendQuery`` improves upon ``sendAsyncMessage`` by returning a ``Promise``. The receiver of the message must then return a ``Promise`` that can eventually resolve into a value - at which time the ``sendQuery`` ``Promise`` resolves with that value. + +The ``sendQuery`` method arguments follow the same conventions as ``sendAsyncMessage``, with the second argument being a structured clone. + +Receiving messages +~~~~~~~~~~~~~~~~~~ + +``receiveMessage`` +`````````````````` + +To receive messages, you need to implement + + receiveMessage(value) + +The method receives a single argument, which is the de-serialized arguments that were sent via either ``sendAsyncMessage`` or ``sendQuery``. + +.. note:: + If `receiveMessage` is responding to a `sendQuery`, it MUST return a ``Promise`` for that message. + +.. hint:: + Using ``sendQuery``, and the ``receiveMessage`` is able to return a value right away? Try using ``Promise.resolve(value);`` to return ``value``, or you could also make your ``receiveMessage`` method an async function, presuming none of the other messages it handles need to get a non-Promise return value. + +Other methods that can be overridden +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``constructor()`` + +If there's something you need to do as soon as the ``JSActor`` is instantiated, the ``constructor`` function is a great place to do that. + +.. note:: + At this point the infrastructure for sending messages is not ready yet and objects such as ``manager`` or ``browsingContext`` are not available. + +``observe(subject, topic, data)`` +````````````````````````````````` + +If you register your Actor to listen for ``nsIObserver`` notifications, implement an ``observe`` method with the above signature to handle the notification. + +``handleEvent(event)`` +`````````````````````` + +If you register your Actor to listen for content events, implement a ``handleEvent`` method with the above signature to handle the event. + +.. note:: + Only JSWindowActors can register to listen for content events. + +``actorCreated`` +```````````````` + +This method is called immediately *after* a child actor is created and initialized. Unlike the actor's constructor, it is possible to do things like access the actor's content window and send messages from this callback. + +``didDestroy`` +`````````````` + +This is another point to clean-up an Actor before it is destroyed, but at this point, no communication is possible with the other side. + +.. note:: + This method cannot be async. + +.. note:: + As a `JSProcessActorChild` is destroyed when its process dies, a `JSProcessActorChild` will never receive this call. + +Other things exposed on a JSWindowActorParent +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``CanonicalBrowsingContext`` +```````````````````````````` + +Getter: ``this.browsingcontext``. + +``WindowGlobalParent`` +`````````````````````` + +TODO + +Other things exposed on a JSWindowActorChild +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``BrowsingContext`` +``````````````````` + +TODO + +``WindowGlobalChild`` +````````````````````` + +TODO + + +Helpful getters +``````````````` + +A number of helpful getters exist on a ``JSWindowActorChild``, including: + +``this.document`` +^^^^^^^^^^^^^^^^^ + +The currently loaded document in the frame associated with this ``JSWindowActorChild``. + +``this.contentWindow`` +^^^^^^^^^^^^^^^^^^^^^^ + +The outer window for the frame associated with this ``JSWindowActorChild``. + +``this.docShell`` +^^^^^^^^^^^^^^^^^ + +The ``nsIDocShell`` for the frame associated with this ``JSWindowActorChild``. + +See `JSWindowActor.webidl`_ for more detail on exactly what is exposed on both ``JSWindowActorParent`` and ``JSWindowActorChild`` implementations. + +How to port from message manager and framescripts to JSWindowActors +------------------------------------------------------------------- + +.. _fission.message-manager-actors: + +Message Manager Actors +~~~~~~~~~~~~~~~~~~~~~~ + +While the JSWindowActor mechanism was being designed and developed, large sections of our framescripts were converted to an "actor style" pattern to make eventual porting to JSWindowActors easier. These Actors use the Message Manager under the hood, but made it much easier to shrink our framescripts, and also allowed us to gain significant memory savings by having the actors be lazily instantiated. + +You can find the list of Message Manager Actors (or "Legacy Actors") in :searchfox:`BrowserGlue.sys.mjs <browser/components/BrowserGlue.sys.mjs>` and :searchfox:`ActorManagerParent.sys.mjs <toolkit/modules/ActorManagerParent.sys.mjs>`, in the ``LEGACY_ACTORS`` lists. + +.. note:: + The split in Message Manager Actors defined between ``BrowserGlue`` and ``ActorManagerParent`` is mainly to keep Firefox Desktop specific Actors separate from Actors that can (in theory) be instantiated for non-Desktop browsers (like Fennec and GeckoView-based browsers). Firefox Desktop-specific Actors should be registered in ``BrowserGlue``. Shared "toolkit" Actors should go into ``ActorManagerParent``. + +"Porting" these Actors often means doing what is necessary in order to move their registration entries from ``LEGACY_ACTORS`` to the ``JSWINDOWACTORS`` list. + +Figuring out the lifetime of a new Actor pair +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In the old model, framescript were loaded and executed as soon as possible by the top-level frame. In the JSWindowActor model, the Actors are much lazier, and only instantiate when: + +1. They're instantiated explicitly by calling ``getActor`` on a ``WindowGlobal``, and passing in the name of the Actor. +2. A message is sent to them. +3. A pre-defined ``nsIObserver`` observer notification fires with the subject of the notification corresponding to an inner or outer window. +4. A pre-defined content Event fires. + +Making the Actors lazy like this saves on processing time to get a frame ready to load web pages, as well as the overhead of loading the Actor into memory. + +When porting a framescript to JSWindowActors, often the first question to ask is: what's the entrypoint? At what point should the Actors instantiate and become active? + +For example, when porting the content area context menu for Firefox, it was noted that the ``contextmenu`` event firing in content was a natural event to wait for to instantiate the Actor pair. Once the ``ContextMenuChild`` instantiated, the ``handleEvent`` method was used to inspect the event and prepare a message to be sent to the ``ContextMenuParent``. This example can be found by looking at the patch for the `Context Menu Fission Port`_. + +.. _fission.registering-a-new-jswindowactor: + +Using ContentDOMReference instead of CPOWs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Despite being outlawed as a way of synchronously accessing the properties of objects in other processes, CPOWs ended up being useful as a way of passing handles for DOM elements between processes. + +CPOW messages, however, cannot be sent over the JSWindowActor communications pipe, so this handy mechanism will no longer work. + +Instead, a new module called :searchfox:`ContentDOMReference.sys.mjs <toolkit/modules/ContentDOMReference.sys.mjs>` has been created which supplies the same capability. See that file for documentation. + +How to start porting parent-process browser code to use JSWindowActors +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :ref:`fission.message-manager-actors` work made it much easier to migrate away from framescripts towards something that is similar to ``JSWindowActors``. It did not, however, substantially change how the parent process interacted with those framescripts. + +So when porting code to work with ``JSWindowActors``, we find that this is often where the time goes - refactoring the parent process browser code to accommodate the new ``JSWindowActor`` model. + +Usually, the first thing to do is to find a reasonable name for your actor pair, and get them registered (see :ref:`fission.registering-a-new-jswindowactor`), even if the actors implementations themselves are nothing but unmodified subclasses of ``JSWindowActorParent`` and ``JSWindowActorChild``. + +Next, it's often helpful to find and note all of the places where ``sendAsyncMessage`` is being used to send messages through the old message manager interface for the component you're porting, and where any messages listeners are defined. + +Let's look at a hypothetical example. Suppose we're porting part of the Page Info dialog, which scans each frame for useful information to display in the dialog. Given a chunk of code like this: + +.. code-block:: javascript + + // This is some hypothetical Page Info dialog code. + + let mm = browser.messageManager; + mm.sendAsyncMessage("PageInfo:getInfoFromAllFrames", { someArgument: 123 }); + + // ... and then later on + + mm.addMessageListener("PageInfo:info", async function onmessage(message) { + // ... + }); + +If a ``PageInfo`` pair of ``JSWindowActor``'s is registered, it might be tempting to simply replace the first part with: + +.. code-block:: javascript + + let actor = browser.browsingContext.currentWindowGlobal.getActor("PageInfo"); + actor.sendAsyncMessage("PageInfo:getInfoFromAllFrames", { someArgument: 123 }); + +However, if any of the frames on the page are running in their own process, they're not going to receive that ``PageInfo:getInfoFromAllFrames`` message. Instead, in this case, we should walk the ``BrowsingContext`` tree, and instantiate a ``PageInfo`` actor for each global, and send one message each to get information for each frame. Perhaps something like this: + +.. code-block:: javascript + + let contextsToVisit = [browser.browsingContext]; + while (contextsToVisit.length) { + let currentContext = contextsToVisit.pop(); + let global = currentContext.currentWindowGlobal; + + if (!global) { + continue; + } + + let actor = global.getActor("PageInfo"); + actor.sendAsyncMessage("PageInfo:getInfoForFrame", { someArgument: 123 }); + + contextsToVisit.push(...currentContext.children); + } + +The original ``"PageInfo:info"`` message listener will need to be updated, too. Any responses from the ``PageInfoChild`` actor will end up being passed to the ``receiveMessage`` method of the ``PageInfoParent`` actor. It will be necessary to pass that information along to the interested party (in this case, the dialog code which is showing the table of interesting Page Info). + +It might be necessary to refactor or rearchitect the original senders and consumers of message manager messages in order to accommodate the ``JSWindowActor`` model. Sometimes it's also helpful to have a singleton management object that manages all ``JSWindowActorParent`` instances and does something with their results. + +Where to store state +~~~~~~~~~~~~~~~~~~~~ + +It's not a good idea to store any state within a ``JSWindowActorChild`` that you want to last beyond the lifetime of its ``BrowsingContext``. An out-of-process ``<iframe>`` can be closed at any time, and if it's the only one for a particular content process, that content process will soon be shut down, and any state you may have stored there will go away. + +Your best bet for storing state is in the parent process. + +.. hint:: + If each individual frame needs state, consider using a ``WeakMap`` in the parent process, mapping ``CanonicalBrowsingContext``'s with that state. That way, if the associates frames ever go away, you don't have to do any cleaning up yourself. + +If you have state that you want multiple ``JSWindowActorParent``'s to have access to, consider having a "manager" of those ``JSWindowActorParent``'s inside of the same .jsm file to hold that state. + +Registering a new actor +----------------------- + +``ChromeUtils`` exposes an API for registering actors, but both ``BrowserGlue`` and ``ActorManagerParent`` are the main entry points where the registration occurs. If you want to register an actor, +you should add it either to ``JSPROCESSACTORS`` or ``JSWINDOWACTORS`` in either of those two files. + +In the ``JS*ACTORS`` objects, each key is the name of the actor pair (example: ``ContextMenu``), and the associated value is an ``Object`` of registration parameters. + +The full list of registration parameters can be found: + +- for JSProcessActor in file `JSProcessActor.webidl`_ as ``WindowActorOptions``, ``ProcessActorSidedOptions`` and ``ProcessActorChildOptions``. +- for JSWindowActor in file `JSWindowActor.webidl`_ as ``WindowActorOptions``, ``WindowActorSidedOptions`` and ``WindowActorChildOptions``. + +Here's an example ``JSWindowActor`` registration pulled from ``BrowserGlue.sys.mjs``: + +.. code-block:: javascript + + Plugin: { + kind: "JSWindowActor", + parent: { + esModuleURI: "resource:///actors/PluginParent.sys.mjs", + }, + child: { + esModuleURI: "resource:///actors/PluginChild.sys.mjs", + events: { + PluginCrashed: { capture: true }, + }, + + observers: ["decoder-doctor-notification"], + }, + + allFrames: true, + }, + +This example is for the JSWindowActor implementation of crash reporting for GMP. + +Let's examine parent registration: + +.. code-block:: javascript + + parent: { + esModuleURI: "resource:///actors/PluginParent.sys.mjs", + }, + +Here, we're declaring that class ``PluginParent`` (here, a subclass of ``JSWindowActorParent``) is defined and exported from module ``PluginParent.sys.mjs``. That's all we have to say for the parent (main process) side of things. + +.. note:: + It's not sufficient to just add a new .jsm file to the actors subdirectories. You also need to update the ``moz.build`` files in the same directory to get the ``resource://`` linkages set up correctly. + +Let's look at the second chunk: + +.. code-block:: javascript + + child: { + esModuleURI: "resource:///actors/PluginChild.sys.mjs", + events: { + PluginCrashed: { capture: true }, + }, + + observers: ["decoder-doctor-notification"], + }, + + allFrames: true, + }, + +We're similarly declaring where the ``PluginChild`` subclassing ``JSWindowActorChild`` can be found. + +Next, we declare the content events which, when fired in a window, will cause the ``JSWindowActorChild`` to instantiate if it doesn't already exist, and then have ``handleEvent`` called on the ``PluginChild`` instance. For each event name, an Object of event listener options can be passed. You can use the same event listener options as accepted by ``addEventListener``. If an event listener has no useful effect when the actor hasn't been created yet, ``createActor: false`` may also be specified to avoid creating the actor when not needed. + +.. note:: + Content events make sense for ``JSWindowActorChild`` (which *have* a content) but are ignored for ``JSProcessActorChild`` (which don't). + +Next, we declare that ``PluginChild`` should observe the ``decoder-doctor-notification`` ``nsIObserver`` notification. When that observer notification fires, the ``PluginChild`` actor will be instantiated for the ``BrowsingContext`` corresponding to the inner or outer window that is the subject argument of the observer notification, and the ``observe`` method on that ``PluginChild`` implementation will be called. If you need this functionality to work with other subjects, please file a bug. + +.. note:: + Unlike ``JSWindowActorChild`` subclasses, observer topics specified for ``JSProcessActorChild`` subclasses will cause those child actor instances to be created and invoke their ``observe`` method no matter what the subject argument of the observer is. + +Finally, we say that the ``PluginChild`` actor should apply to ``allFrames``. This means that the ``PluginChild`` is allowed to be loaded in any subframe. If ``allFrames`` is set to false (the default), the actor will only ever load in the top-level frame. + +Design considerations when adding a new actor +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A few things worth bearing in mind when adding your own actor registration: + +- Any ``child`` or ``parent`` side you register **must** have a ``moduleURI`` property. +- You do not need to have both ``child`` and ``parent`` modules, and should avoid having actor sides that do nothing but send messages. The process without a defined module will still get an actor, and you can send messages from that side, but cannot receive them via ``receiveMessage``. Note that you **can** also use ``sendQuery`` from this side, enabling you to handle a response from the other process despite not having a ``receiveMessage`` method. +- If you are writing a JSWindowActor, consider whether you really need ``allFrames`` - it'll save memory and CPU time if we don't need to instantiate the actor for subframes. +- When copying/moving "Legacy" :ref:`fission.message-manager-actors`, remove their ``messages`` properties. They are no longer necessary. + + +Minimal Example Actors +----------------------- + +Get a JSWindowActor +~~~~~~~~~~~~~~~~~~~~ + +**Define an Actor** + +.. code-block:: javascript + + // resource://testing-common/TestWindowParent.jsm + var EXPORTED_SYMBOLS = ["TestWindowParent"]; + class TestParent extends JSWindowActorParent { + ... + } + +.. code-block:: javascript + + // resource://testing-common/TestWindowChild.jsm + var EXPORTED_SYMBOLS = ["TestWindowChild"]; + class TestChild extends JSWindowActorChild { + ... + } + + +**Get a JS window actor for a specific window** + +.. code-block:: javascript + + // get parent side actor + let parentActor = this.browser.browsingContext.currentWindowGlobal.getActor("TestWindow"); + + // get child side actor + let childActor = content.windowGlobalChild.getActor("TestWindow"); + +Get a JSProcessActor +~~~~~~~~~~~~~~~~~~~~ + +**Define an Actor** + +.. code-block:: javascript + + // resource://testing-common/TestProcessParent.jsm + var EXPORTED_SYMBOLS = ["TestProcessParent"]; + class TestParent extends JSProcessActorParent { + ... + } + +.. code-block:: javascript + + // resource://testing-common/TestProcessChild.jsm + var EXPORTED_SYMBOLS = ["TestProcessChild"]; + class TestChild extends JSProcessActorChild { + ... + } + + +**Get a JS process actor for a specific process** + +.. code-block:: javascript + + // get parent side actor + let parentActor = this.browser + .browsingContext + .currentWindowGlobal + .domProcess + .getActor("TestProcess"); + + // get child side actor + let childActor = ChromeUtils.domProcessChild + .getActor("TestProcess"); + +And more +=========== + + +.. _Electrolysis Project: https://wiki.mozilla.org/Electrolysis +.. _IPC Actors: https://developer.mozilla.org/en-US/docs/Mozilla/IPDL/Tutorial +.. _Context Menu Fission Port: https://hg.mozilla.org/mozilla-central/rev/adc60720b7b8 +.. _JSProcessActor.webidl: https://searchfox.org/mozilla-central/source/dom/chrome-webidl/JSProcessActor.webidl +.. _JSWindowActor.webidl: https://searchfox.org/mozilla-central/source/dom/chrome-webidl/JSWindowActor.webidl +.. _BrowserElementParent.jsm: https://searchfox.org/mozilla-central/rev/ec806131cb7bcd1c26c254d25cd5ab8a61b2aeb6/toolkit/actors/BrowserElementParent.jsm diff --git a/dom/docs/ipc/mainthread.rst b/dom/docs/ipc/mainthread.rst new file mode 100644 index 0000000000..c04e8dc484 --- /dev/null +++ b/dom/docs/ipc/mainthread.rst @@ -0,0 +1,13 @@ +================== +Main Thread Actors +================== + +Actors on the main thread between the parent and content processes are +generally managed by ``PContent``, the primary actor for a content process. + +TODO + +Fission Actor Diagram +===================== + +.. image:: Fission-IPC-Diagram.svg diff --git a/dom/docs/ipc/process_model.rst b/dom/docs/ipc/process_model.rst new file mode 100644 index 0000000000..b405566a1d --- /dev/null +++ b/dom/docs/ipc/process_model.rst @@ -0,0 +1,334 @@ +Process Model +============= + +The complete set of recognized process types is defined in `GeckoProcessTypes <https://searchfox.org/mozilla-central/source/xpcom/geckoprocesstypes_generator/geckoprocesstypes/__init__.py>`_. + +For more details on how process types are added and managed by IPC, see the process creation documentation :ref:`Gecko Processes`. + +Diagram +------- + +.. digraph:: processtypes + :caption: Diagram of processes used by Firefox. All child processes are spawned and managed by the Parent process. + + compound=true; + node [shape=rectangle]; + + launcher [label=<Launcher Process>] + parent [label=<Parent Process>] + + subgraph cluster_child { + color=lightgrey; + label=<Child Processes>; + + subgraph cluster_content { + color=lightgrey; + label=<Content Processes>; + + web [ + color=lightgrey; + label=< + <TABLE BORDER="0" CELLSPACING="5" CELLPADDING="5" COLOR="black"> + <TR><TD BORDER="0" CELLPADDING="0" CELLSPACING="0">Web Content</TD></TR> + <TR><TD BORDER="1">Shared Web Content<BR/>(<FONT FACE="monospace">web</FONT>)</TD></TR> + <TR><TD BORDER="1">Isolated Web Content<BR/>(<FONT FACE="monospace">webIsolated=$SITE</FONT>)</TD></TR> + <TR><TD BORDER="1">COOP+COEP Web Content<BR/>(<FONT FACE="monospace">webCOOP+COEP=$SITE</FONT>)</TD></TR> + <TR><TD BORDER="1">ServiceWorker Web Content<BR/>(<FONT FACE="monospace">webServiceWorker</FONT>)</TD></TR> + </TABLE> + > + ] + + nonweb [ + shape=none; + label=< + <TABLE BORDER="0" CELLSPACING="5" CELLPADDING="5" COLOR="black"> + <TR><TD BORDER="1">Preallocated Content<BR/>(<FONT FACE="monospace">prealloc</FONT>)</TD></TR> + <TR><TD BORDER="1">File Content<BR/>(<FONT FACE="monospace">file</FONT>)</TD></TR> + <TR><TD BORDER="1">WebExtensions<BR/>(<FONT FACE="monospace">extension</FONT>)</TD></TR> + <TR><TD BORDER="1">Privileged Content<BR/>(<FONT FACE="monospace">privilegedabout</FONT>)</TD></TR> + <TR><TD BORDER="1">Privileged Mozilla Content<BR/>(<FONT FACE="monospace">privilegedmozilla</FONT>)</TD></TR> + </TABLE> + > + ] + } + + helper [ + color=lightgrey; + label=< + <TABLE BORDER="0" CELLSPACING="5" CELLPADDING="5" COLOR="black"> + <TR><TD BORDER="0" CELLPADDING="0" CELLSPACING="0">Helper Processes</TD></TR> + <TR><TD BORDER="1">Gecko Media Plugins (GMP) Process</TD></TR> + <TR><TD BORDER="1">GPU Process</TD></TR> + <TR><TD BORDER="1">VR Process</TD></TR> + <TR><TD BORDER="1">Data Decoder (RDD) Process</TD></TR> + <TR><TD BORDER="1">Network (Socket) Process</TD></TR> + <TR><TD BORDER="1">Utility Process</TD></TR> + <TR><TD BORDER="1">Remote Sandbox Broker Process</TD></TR> + <TR><TD BORDER="1">Fork Server</TD></TR> + </TABLE> + > + ] + } + + subgraph { rank=same; launcher -> parent; } + + parent -> web [lhead="cluster_content"]; + parent -> helper; + +.. _parent-process: + +Parent Process +-------------- + +:remoteType: *null* +:other names: UI Process, Main Process, Chrome Process, Browser Process, Default Process, Broker Process +:sandboxed?: no + +The parent process is the primary process which handles the core functionality of Firefox, including its UI, profiles, process selection, navigation, and more. The parent process is responsible for launching all other child processes, and acts as a broker establishing communication between them. + +All primary protocols establish a connection between the parent process and the given child process, which can then be used to establish additional connections to other processes. + +As the parent process can display HTML and JS, such as the browser UI and privileged internal pages such as ``about:preferences`` and ``about:config``, it is often treated as-if it was a content process with a *null* remote type by process selection logic. The parent process has extra protections in place to ensure it cannot load untrusted code when running in multiprocess mode. To this effect, any attempts to load web content in the parent process will lead to a browser crash, and all navigations to and from parent-process documents immediately perform full isolation, to prevent content processes from manipulating them. + +.. _content-process: + +Content Process +--------------- + +:primary protocol: `PContent <https://searchfox.org/mozilla-central/source/dom/ipc/PContent.ipdl>`_ +:other names: Renderer Process +:sandboxed?: yes (content sandbox policy) + +Content processes are used to load web content, and are the only process type (other than the parent process) which can load and execute JS code. These processes are further subdivided into specific "remote types", which specify the type of content loaded within them, their sandboxing behavior, and can gate access to certain privileged IPC methods. + +The specific remote type and isolation behaviour used for a specific resource is currently controlled in 2 major places. When performing a document navigation, the final process to load the document in is selected by the logic in `ProcessIsolation.cpp <https://searchfox.org/mozilla-central/source/dom/ipc/ProcessIsolation.cpp>`_. This will combine information about the specific response, such as the site and headers, with other state to select which process and other isolating actions should be taken. When selecting which process to create the initial process for a new tab in, and when selecting processes for serviceworkers and shared workers, the logic in :searchfox:`E10SUtils.sys.mjs <toolkit/modules/E10SUtils.sys.mjs>`_ is used to select a process. The logic in ``E10SUtils.sys.mjs`` will likely be removed and replaced with ``ProcessIsolation.cpp`` in the future. + +.. note:: + + The "Renderer" alternative name is used by Chromium for its equivalent to content processes, and is occasionally used in Gecko as well, due to the similarity in process architecture. The actual rendering & compositing steps are performed in the GPU or main process. + +Preallocated Content +^^^^^^^^^^^^^^^^^^^^ + +:remoteType: ``prealloc`` +:default count: 3 (``dom.ipc.processPrelaunch.fission.number``, or 1 if Fission is disabled) + +To avoid the need to launch new content processes to host new content when navigating, new content processes are pre-launched and specialized when they are requested. These preallocated content processes will never load content, and must be specialized before they can be used. + +The count of preallocated processes can vary depending on various factors, such as the memory available in the host system. + +The ``prealloc`` process cannot be used to launch ``file`` content processes, due to their weakened OS sandbox. ``extension`` content processes are also currently not supported due to `Bug 1637119 <https://bugzilla.mozilla.org/show_bug.cgi?id=1638119>`_. + +File Content +^^^^^^^^^^^^ + +:remoteType: ``file`` +:default count: 1 (``dom.ipc.processCount.file``) +:capabilities: File System Access + +The File content process is used to load ``file://`` URIs, and is therefore less sandboxed than other content processes. It may also be used to load remote web content if the browser has used a legacy CAPS preference to allow that site to access local resources (see `Bug 995943 <https://bugzilla.mozilla.org/show_bug.cgi?id=995943>`_) + +WebExtensions +^^^^^^^^^^^^^ + +:remoteType: ``extension`` +:default count: 1 (``dom.ipc.processCount.extension``) +:capabilities: Extension APIs, Shared Memory (SharedArrayBuffer) + +The WebExtension content process is used to load background pages and top level WebExtension frames. This process generally has access to elevated permissions due to loading privileged extension pages with access to the full WebExtension API surface. Currently all extensions share a single content process. + +Privileged extensions loaded within the extension process may also be granted access to shared memory using SharedArrayBuffer. + +.. note:: + + ``moz-extension://`` subframes are currently loaded in the same process as the parent document, rather than in the ``extension`` content process, due to existing permissions behaviour granting content scripts the ability to access the content of extension subframes. This may change in the future. + +Privileged Content +^^^^^^^^^^^^^^^^^^ + +:remoteType: ``privilegedabout`` +:default count: 1 (``dom.ipc.processCount.privilegedabout``) +:capabilities: Restricted JSWindowActor APIs + +The ``privilegedabout`` content process is used to load internal pages which have privileged access to internal state. The use of the ``privilegedabout`` content process is requested by including both ``nsIAboutModule::URI_MUST_LOAD_IN_CHILD`` and ``nsIAboutModule::URI_CAN_LOAD_IN_PRIVILEGEDABOUT_PROCESS`` flags in the corresponding ``nsIAboutModule``. + +As of August 11, 2021, the following internal pages load in the privileged content process: ``about:logins``, ``about:loginsimportreport``, ``about:privatebrowsing``, ``about:home``, ``about:newtab``, ``about:welcome``, ``about:protections``, and ``about:certificate``. + +Various ``JSWindowActor`` instances which provide special API access for these internal about pages are restricted to only be available in this content process through the ``remoteTypes`` attribute, which will block attempts to use them from other content processes. + +Privileged Mozilla Content +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:remoteType: ``privilegedmozilla`` +:default count: 1 (``dom.ipc.processCount.privilegedmozilla``) +:domains: ``addons.mozilla.org`` and ``accounts.firefox.com`` (``browser.tabs.remote.separatedMozillaDomains``) +:capabilities: Restricted Addon Manager APIs + +The ``privilegedmozilla`` content process is used to load specific high-value Mozilla-controlled webpages which have been granted access to privileged features. To provide an extra layer of security for these sites, they are loaded in a separate process from other web content even when Fission is disabled. + +This separate remote type is also used to gate access at the IPC boundary to certain high-power web APIs, such as access to the ability to interact with installed extension APIs. + +Web Content Processes +^^^^^^^^^^^^^^^^^^^^^ + +These processes all have remote types beginning with ``web``, and are used to host general untrusted web content. The different variants of web content processes are used at different times, depending on the isolation strategy requested by the page and the browser's configuration. + +Shared Web Content +"""""""""""""""""" + +:remoteType: ``web`` +:default count: 8 (``dom.ipc.processCount``) + +The shared web content process is used to host content which is not isolated into one of the other web content process types. This includes almost all web content with Fission disabled, and web content which cannot be attributed to a specific origin with Fission enabled, such as user-initiated ``data:`` URI loads. + +Isolated Web Content +"""""""""""""""""""" + +:remoteType: ``webIsolated=$SITE`` +:default count: 1 per-site (``dom.ipc.processCount.webIsolated``) + +Isolated web content processes are used to host web content with Fission which can be attributed to a specific site. These processes are allocated when navigating, and will only load content from the named site. When Fission is disabled, isolated web content processes are not used. + +A different ``webIsolated=`` remote type, and therefore a different pool of processes, is used for each site loaded, with separation also being used for different container tabs and private browsing. + +COOP+COEP Web Content +""""""""""""""""""""" + +:remoteType: ``webCOOP+COEP=$SITE`` +:default count: 1 per-site (``dom.ipc.processCount.webCOOP+COEP``) +:capabilities: Shared Memory (SharedArrayBuffer) + +When loading a top level document with both the ``Cross-Origin-Opener-Policy`` and ``Cross-Origin-Embedder-Policy`` headers configured correctly, the document is requesting access to Shared Memory. For security reasons, we only provide this API access to sufficiently-isolated pages, and we load them within special isolated content processes. + +Like Isolated Web Content, these processes are keyed by the site loaded within them, and are also segmented based on container tabs and private browsing. + +.. note:: + + Another name for this process may be "Cross-Origin Isolated Web Content", to correspond with the ``window.crossOriginIsolated`` attribute which is set for documents loaded with these headers set. Unfortunately that may be confused with Fission's "Isolated Web Content" processes, as the attribute was named after the ``webIsolated`` remote type was already in use. + + In ``about:processes``, COOP+COEP Web Content processes will be listed with a "cross-origin isolated" note after the PID, like ``https://example.com (12345, cross-origin isolated)``. + +ServiceWorker Web Content +""""""""""""""""""""""""" + +:remoteType: ``webServiceWorker=$SITE`` +:default count: 1 per-site using ServiceWorkers + +ServiceWorker web content processes are used to host ServiceWorkers on a per-site basis, so that ServiceWorker operations aren't impacted by MainThread event latency whenrunning in the same process as the content for the page. ServiceWorkers are usually transitory, and will disappear if unused for a short period of time. + +.. _gecko-media-plugins-process: + +Gecko Media Plugins (GMP) Process +--------------------------------- + +:primary protocol: `PGMP <https://searchfox.org/mozilla-central/source/dom/media/gmp/PGMP.ipdl>`_ +:sandboxed?: yes (GMP sandbox policy) + +The GMP process is used to sandbox third-party "Content Decryption Module" (CDM) binaries used for media playback in a sandboxed environment. This process is only launched when DRM-enabled content is loaded. + +.. _gpu-process: + +GPU Process +----------- + +:primary protocol: `PGPU <https://searchfox.org/mozilla-central/source/gfx/ipc/PGPU.ipdl>`_ +:other names: Compositor Process +:sandboxed?: no (`bug 1347710 <https://bugzilla.mozilla.org/show_bug.cgi?id=1347710>`_ tracks sandboxing on windows) + +The GPU process performs compositing, and is used to talk to GPU hardware in an isolated process. This helps isolate things like GPU driver crashes from impacting the entire browser, and will allow for this code to be sandboxed in the future. In addition, some components like Windows Media Foundation (WMF) are run in the GPU process when it is available. + +The GPU process is not used on all platforms. Platforms which do not use it, such as macOS and some Linux configurations, will perform compositing on a background thread in the Parent Process. + +.. _vr-process: + +VR Process +---------- + +:primary protocol: `PVR <https://searchfox.org/mozilla-central/source/gfx/vr/ipc/PVR.ipdl>`_ +:sandboxed?: no (`bug 1430043 <https://bugzilla.mozilla.org/show_bug.cgi?id=1430043>`_ tracks sandboxing on windows) + +VR headset libraries require access to specific OS level features and other requirements which we would generally like to block with the sandbox in other processes. In order to allow the GPU process to have tighter sandboxing rules, these VR libraries are loaded into the less-restricted VR process. Like the GPU process, this serves to isolate them from the rest of Firefox and reduce the impact of bugs in these libraries on the rest of the browser. The VR process is launched only after a user visits a site which uses WebVR. + +.. _data-decoder-process: + +Data Decoder (RDD) Process +-------------------------- + +:primary protocol: `PRDD <https://searchfox.org/mozilla-central/source/dom/media/ipc/PRDD.ipdl>`_ +:sandboxed?: yes (RDD sandbox policy) + +This process is used to run media data decoders within their own sandboxed process, allowing the code to be isolated from other code in Gecko. This aims to reduce the severity of potential bugs in media decoder libraries, and improve the security of the browser. + +.. note:: + + This process is in the process of being restructured into a generic "utility" process type for running untrusted code in a maximally secure sandbox. After these changes, the following new process types will exist, replacing the RDD process: + + * ``Utility``: A maximally sandboxed process used to host untrusted code which does not require access to OS resources. This process will be even more sandboxed than RDD today on Windows, where the RDD process has access to Win32k. + * ``UtilityWithWin32k``: A Windows-only process with the same sandboxing as the RDD process today. This will be used to host untrusted sandboxed code which requires access to Win32k to allow decoding directly into GPU surfaces. + * ``GPUFallback``: A Windows-only process using the GPU process' sandboxing policy which will be used to run Windows Media Foundation (WMF) when the GPU process itself is unavailable, allowing ``UtilityWithWin32k`` to re-enable Arbitrary Code Guard (ACG) on Windows. + + For more details about the planned utility process architecture changes, see `the planning document <https://docs.google.com/document/d/1WDEY5fQetK_YE5oxGxXK9BzC1A8kJP3q6F1gAPc2UGE>`_. + +.. _network-socket-process: + +Network (Socket) Process +------------------------ + +:primary protocol: `PSocketProcess <https://searchfox.org/mozilla-central/source/netwerk/ipc/PSocketProcess.ipdl>`_ +:sandboxed?: yes (socket sandbox policy) + +The socket process is used to separate certain networking operations from the parent process, allowing them to be performed more directly in a partially sandboxed process. The eventual goal is to move all TCP/UDP network operations into this dedicated process, and is being tracked in `Bug 1322426 <https://bugzilla.mozilla.org/show_bug.cgi?id=1322426>`_. + +.. _remote-sandbox-process: + +Remote Sandbox Broker Process +----------------------------- + +:platform: Windows on ARM only +:primary protocol: `PRemoteSandboxBroker <https://searchfox.org/mozilla-central/source/security/sandbox/win/src/remotesandboxbroker/PRemoteSandboxBroker.ipdl>`_ +:sandboxed?: no + +In order to run sandboxed x86 plugin processes from Windows-on-ARM, the remote sandbox broker process is launched in x86-mode, and used to launch sandboxed x86 subprocesses. This avoids issues with the sandboxing layer, which unfortunately assumes that pointer width matches between the sandboxer and sandboxing process. To avoid this, the remote sandbox broker is used as an x86 sandboxing process which wraps these plugins. + +.. _fork-server: + +Fork Server +----------- + +:platform: Linux only +:pref: ``dom.ipc.forkserver.enable`` (disabled by default) +:primary protocol: *none* +:sandboxed?: no (processes forked by the fork server are sandboxed) + +The fork server process is used to reduce the memory overhead and improve launch efficiency for new processes. When a new supported process is requested and the feature is enabled, the parent process will ask the fork server to ``fork(2)`` itself, and then begin executing. This avoids the need to re-load ``libxul.so`` and re-perform relocations. + +The fork server must run before having initialized XPCOM or the IPC layer, and therefore uses a custom low-level IPC system called ``MiniTransceiver`` rather than IPDL to communicate. + +.. _launcher-process: + +Launcher Process +---------------- + +:platform: Windows only +:metabug: `Bug 1435780 <https://bugzilla.mozilla.org/show_bug.cgi?id=1435780>`_ +:sandboxed?: no + +The launcher process is used to bootstrap Firefox on Windows before launching the main Firefox process, allowing things like DLL injection blocking to initialize before the main thread even starts running, and improving stability. Unlike the other utility processes, this process is not launched by the parent process, but rather launches it. + +IPDLUnitTest +------------ + +:primary protocol: varies + +This test-only process type is intended for use when writing IPDL unit tests. However, it is currently broken, due to these tests having never been run in CI. The type may be removed or re-used when these unit tests are fixed. + +.. _utility-process: + +Utility Process +--------------- + +:primary protocol: `PUtilityProcess <https://searchfox.org/mozilla-central/source/ipc/glue/PUtilityProcess.ipdl>`_ +:metabug: `Bug 1722051 <https://bugzilla.mozilla.org/show_bug.cgi?id=1722051>`_ +:sandboxed?: yes, customizable + +The utility process is used to provide a simple way to implement IPC actor with some more specific sandboxing properties, in case where you don't need or want to deal with the extra complexity of adding a whole new process type but you just want to apply different sandboxing policies. Details can be found in :ref:`Utility Process`. |
