diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-28 14:29:10 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-28 14:29:10 +0000 |
| commit | 2aa4a82499d4becd2284cdb482213d541b8804dd (patch) | |
| tree | b80bf8bf13c3766139fbacc530efd0dd9d54394c /dom/docs | |
| parent | Initial commit. (diff) | |
| download | firefox-2aa4a82499d4becd2284cdb482213d541b8804dd.tar.xz firefox-2aa4a82499d4becd2284cdb482213d541b8804dd.zip | |
Adding upstream version 86.0.1.upstream/86.0.1upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
| -rw-r--r-- | dom/docs/index.rst | 11 | ||||
| -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 | 8 | ||||
| -rw-r--r-- | dom/docs/ipc/jsactors.rst | 558 | ||||
| -rw-r--r-- | dom/docs/ipc/mainthread.rst | 13 | ||||
| -rw-r--r-- | dom/docs/navigation/BrowsingContext.rst | 149 | ||||
| -rw-r--r-- | dom/docs/navigation/embedding.rst | 93 | ||||
| -rw-r--r-- | dom/docs/navigation/index.rst | 9 | ||||
| -rw-r--r-- | dom/docs/navigation/nav_replace.rst | 95 | ||||
| -rw-r--r-- | dom/docs/workersAndStorage/CodeStyle.rst | 357 | ||||
| -rw-r--r-- | dom/docs/workersAndStorage/index.rst | 9 |
13 files changed, 1307 insertions, 0 deletions
diff --git a/dom/docs/index.rst b/dom/docs/index.rst new file mode 100644 index 0000000000..1635bf7a83 --- /dev/null +++ b/dom/docs/index.rst @@ -0,0 +1,11 @@ +DOM +=== + +These linked pages contain design documents for the DOM implementation in Gecko. They live in-tree under the 'dom/docs' directory. + +.. toctree:: + :maxdepth: 1 + + ipc/index + navigation/index + workersAndStorage/index diff --git a/dom/docs/ipc/Fission-IPC-Diagram.svg b/dom/docs/ipc/Fission-IPC-Diagram.svg new file mode 100644 index 0000000000..7e6faaa6e6 --- /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);" xmlns:xlink="http://www.w3.org/1999/xlink" 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..2c9a3b873e --- /dev/null +++ b/dom/docs/ipc/index.rst @@ -0,0 +1,8 @@ +DOM IPC +======= + +.. toctree:: + :maxdepth: 1 + + jsactors + mainthread diff --git a/dom/docs/ipc/jsactors.rst b/dom/docs/ipc/jsactors.rst new file mode 100644 index 0000000000..afd307ce80 --- /dev/null +++ b/dom/docs/ipc/jsactors.rst @@ -0,0 +1,558 @@ +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 the 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 a 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 current 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`` +```````````````````````````` + +TODO + +``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 `BrowserGlue.jsm <https://searchfox.org/mozilla-central/source/browser/components/BrowserGlue.jsm>`_ and `ActorManagerParent.jsm <https://searchfox.org/mozilla-central/source/toolkit/modules/ActorManagerParent.jsm>`_, 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 `ContentDOMReference.jsm`_ 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.jsm``: + +.. code-block:: javascript + + Plugin: { + kind: "JSWindowActor", + parent: { + moduleURI: "resource:///actors/PluginParent.jsm", + }, + child: { + moduleURI: "resource:///actors/PluginChild.jsm", + events: { + PluginBindingAttached: { capture: true, wantUntrusted: true }, + PluginCrashed: { capture: true }, + PluginOutdated: { capture: true }, + PluginInstantiated: { capture: true }, + PluginRemoved: { capture: true }, + HiddenPlugin: { capture: true }, + }, + + observers: ["decoder-doctor-notification"], + }, + + allFrames: true, + }, + +This example is for the JSWindowActor implementation of click-to-play for Flash. + +Let's examine parent registration: + +.. code-block:: javascript + + parent: { + moduleURI: "resource:///actors/PluginParent.jsm", + }, + +Here, we're declaring that class ``PluginParent`` (here, a subclass of ``JSWindowActorParent``) is defined and exported from module ``PluginParent.jsm``. 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: { + moduleURI: "resource:///actors/PluginChild.jsm", + events: { + PluginBindingAttached: { capture: true, wantUntrusted: true }, + PluginCrashed: { capture: true }, + PluginOutdated: { capture: true }, + PluginInstantiated: { capture: true }, + PluginRemoved: { capture: true }, + HiddenPlugin: { 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, if fired in a BrowsingContext, will cause the JSWindowActor pair 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``. + +.. 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 +.. _ContentDOMReference.jsm: https://searchfox.org/mozilla-central/source/toolkit/modules/ContentDOMReference.jsm +.. _JSProcessActor.webidl: https://searchfox.org/mozilla-central/source/dom/chrome-webidl/JSWindowActor.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..5b1ce136c9 --- /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
\ No newline at end of file diff --git a/dom/docs/navigation/BrowsingContext.rst b/dom/docs/navigation/BrowsingContext.rst new file mode 100644 index 0000000000..213b2fcce5 --- /dev/null +++ b/dom/docs/navigation/BrowsingContext.rst @@ -0,0 +1,149 @@ +BrowsingContext and WindowContext +================================= + +The ``BrowsingContext`` is the Gecko representation of the spec-defined +`Browsing Context`_ object. + +.. _Browsing Context: https://html.spec.whatwg.org/multipage/browsers.html#browsing-context + + +The Browsing Context Tree +------------------------- + +``BrowsingContext`` and ``WindowContext`` objects form a tree, corresponding +to the tree of frame elements which was used to construct them. + + +Example +^^^^^^^ + +Loading the HTML documents listed here, would end up creating a set of BrowsingContexts and WindowContexts forming the tree. + +.. code-block:: html + + <!-- http://example.com/top.html --> + <iframe src="frame1.html"></iframe> + <iframe src="http://mozilla.org/"></iframe> + + <!-- http://example.com/frame1.html --> + <iframe src="http://example.com/frame2.html"></iframe> + + <!-- http://mozilla.org --> + <iframe></iframe> + <iframe></iframe> + +.. digraph:: browsingcontext + + node [shape=rectangle] + + "BC1" [label="BrowsingContext A"] + "BC2" [label="BrowsingContext B"] + "BC3" [label="BrowsingContext C"] + "BC4" [label="BrowsingContext D"] + "BC5" [label="BrowsingContext E"] + "BC6" [label="BrowsingContext F"] + + "WC1" [label="WindowContext\n(http://example.com/top.html)"] + "WC2" [label="WindowContext\n(http://example.com/frame1.html)"] + "WC3" [label="WindowContext\n(http://mozilla.org)"] + "WC4" [label="WindowContext\n(http://example.com/frame2.html)"] + "WC5" [label="WindowContext\n(about:blank)"] + "WC6" [label="WindowContext\n(about:blank)"] + + "BC1" -> "WC1"; + "WC1" -> "BC2"; + "WC1" -> "BC3"; + "BC2" -> "WC2"; + "BC3" -> "WC3"; + "WC2" -> "BC4"; + "BC4" -> "WC4"; + "WC3" -> "BC5"; + "BC5" -> "WC5"; + "WC3" -> "BC6"; + "BC6" -> "WC6"; + + +Synced Fields +------------- + +WIP - In-progress documentation at `<https://wiki.mozilla.org/Project_Fission/BrowsingContext>`_. + + +API Documentation +----------------- + +.. cpp:class:: BrowsingContext + + .. hlist:: + :columns: 3 + + * `header (searchfox) <https://searchfox.org/mozilla-central/source/docshell/base/BrowsingContext.h>`_ + * `source (searchfox) <https://searchfox.org/mozilla-central/source/docshell/base/BrowsingContext.cpp>`_ + * `html spec <https://html.spec.whatwg.org/multipage/browsers.html#browsing-context>`_ + + This is a synced-context type. Instances of it will exist in every + "relevant" content process for the navigation. + + Instances of :cpp:class:`BrowsingContext` created in the parent processes + will be :cpp:class:`CanonicalBrowsingContext`. + + .. cpp:function:: WindowContext* GetParentWindowContext() + + Get the parent ``WindowContext`` embedding this context, or ``nullptr``, + if this is the toplevel context. + + .. cpp:function:: WindowContext* GetTopWindowContext() + + Get the toplevel ``WindowContext`` embedding this context, or ``nullptr`` + if this is the toplevel context. + + This is equivalent to repeatedly calling ``GetParentWindowContext()`` + until it returns nullptr. + + .. cpp:function:: BrowsingContext* GetParent() + + .. cpp:function:: BrowsingContext* Top() + + .. cpp:function:: static already_AddRefed<BrowsingContext> Get(uint64_t aId) + + Look up a specific ``BrowsingContext`` by it's unique ID. Callers should + check if the returned context has already been discarded using + ``IsDiscarded`` before using it. + +.. cpp:class:: CanonicalBrowsingContext : public BrowsingContext + + .. hlist:: + :columns: 3 + + * `header (searchfox) <https://searchfox.org/mozilla-central/source/docshell/base/CanonicalBrowsingContext.h>`_ + * `source (searchfox) <https://searchfox.org/mozilla-central/source/docshell/base/CanonicalBrowsingContext.cpp>`_ + + When a :cpp:class:`BrowsingContext` is constructed in the parent process, + it is actually an instance of :cpp:class:`CanonicalBrowsingContext`. + + Due to being in the parent process, more information about the context is + available from a ``CanonicalBrowsingContext``. + +.. cpp:class:: WindowContext + + .. hlist:: + :columns: 3 + + * `header (searchfox) <https://searchfox.org/mozilla-central/source/docshell/base/WindowContext.h>`_ + * `source (searchfox) <https://searchfox.org/mozilla-central/source/docshell/base/WindowContext.cpp>`_ + +.. cpp:class:: WindowGlobalParent : public WindowContext, public WindowGlobalActor, public PWindowGlobalParent + + .. hlist:: + :columns: 3 + + * `header (searchfox) <https://searchfox.org/mozilla-central/source/dom/ipc/WindowGlobalParent.h>`_ + * `source (searchfox) <https://searchfox.org/mozilla-central/source/dom/ipc/WindowGlobalParent.cpp>`_ + +.. cpp:class:: WindowGlobalChild : public WindowGlobalActor, public PWindowGlobalChild + + .. hlist:: + :columns: 3 + + * `header (searchfox) <https://searchfox.org/mozilla-central/source/dom/ipc/WindowGlobalChild.h>`_ + * `source (searchfox) <https://searchfox.org/mozilla-central/source/dom/ipc/WindowGlobalChild.cpp>`_ diff --git a/dom/docs/navigation/embedding.rst b/dom/docs/navigation/embedding.rst new file mode 100644 index 0000000000..b213b03ea4 --- /dev/null +++ b/dom/docs/navigation/embedding.rst @@ -0,0 +1,93 @@ +Browsing Context Embedding +========================== + +Embedder Element to nsDocShell +------------------------------ + +In order to render the contents of a ``BrowsingContext``, the embedding +element needs to be able to communicate with the ``nsDocShell`` which is +currently being used to host it's content. This is done in 3 different ways +depending on which combination of processes is in-use. + +- *in-process*: The ``nsFrameLoader`` directly embeds the ``nsDocShell``. +- *remote tab*: The parent process is the embedder, and uses a ``PBrowser``, + via a ``BrowserHost``. The ``BrowserChild`` actor holds the actual + ``nsDocShell`` alive. +- *remote subframe*: A content process is the embedder, and uses a + ``PBrowserBridge``, via a ``BrowserBridgeHost`` to communicate with the + parent process. The parent process then uses a ``BrowserParent``, as in the + *remote tab* case, to communicate with the ``nsDocShell``. + +Diagram +^^^^^^^ + +.. digraph:: embedding + + node [shape=rectangle] + + subgraph cluster_choice { + color=transparent; + node [shape=none]; + + "In-Process"; + "Remote Tab"; + "Remote Subframe"; + } + + "nsFrameLoaderOwner" [label="nsFrameLoaderOwner\ne.g. <iframe>, <xul:browser>, <embed>"] + + "nsFrameLoaderOwner" -> "nsFrameLoader"; + + "nsFrameLoader" -> "In-Process" [dir=none]; + "nsFrameLoader" -> "Remote Tab" [dir=none]; + "nsFrameLoader" -> "Remote Subframe" [dir=none]; + + "In-Process" -> "nsDocShell"; + "Remote Tab" -> "BrowserHost"; + "Remote Subframe" -> "BrowserBridgeHost"; + + "BrowserHost" -> "BrowserParent"; + "BrowserParent" -> "BrowserChild" [label="PBrowser" style=dotted]; + "BrowserChild" -> "nsDocShell"; + + "BrowserBridgeHost" -> "BrowserBridgeChild"; + "BrowserBridgeChild" -> "BrowserBridgeParent" [label="PBrowserBridge", style=dotted]; + "BrowserBridgeParent" -> "BrowserParent"; + +nsDocShell to Document +---------------------- + +Embedding an individual document within a ``nsDocShell`` is done within the +content process, which has that docshell. + + +Diagram +^^^^^^^ + +This diagram shows the objects involved in a content process which is being +used to host a given ``BrowsingContext``, along with rough relationships +between them. Dotted lines represent a "current" relationship, whereas solid +lines are a stronger lifetime relationship. + +.. graph:: document + + node [shape=rectangle] + + "BrowsingContext" -- "nsDocShell" [style=dotted]; + "nsDocShell" -- "nsGlobalWindowOuter"; + "nsGlobalWindowOuter" -- "nsGlobalWindowInner" [style=dotted]; + "nsGlobalWindowInner" -- "Document" [style=dotted]; + + "nsDocShell" -- "nsDocumentViewer" [style=dotted]; + "nsDocumentViewer" -- "Document"; + "nsDocumentViewer" -- "PresShell"; + + "nsGlobalWindowInner" -- "WindowGlobalChild"; + "BrowsingContext" -- "WindowContext" [style=dotted]; + "WindowContext" -- "nsGlobalWindowInner"; + + subgraph cluster_synced { + label = "Synced Contexts"; + "BrowsingContext" "WindowContext"; + } + diff --git a/dom/docs/navigation/index.rst b/dom/docs/navigation/index.rst new file mode 100644 index 0000000000..b322855eb6 --- /dev/null +++ b/dom/docs/navigation/index.rst @@ -0,0 +1,9 @@ +DOM Navigation +============== + +.. toctree:: + :maxdepth: 1 + + embedding + BrowsingContext + nav_replace diff --git a/dom/docs/navigation/nav_replace.rst b/dom/docs/navigation/nav_replace.rst new file mode 100644 index 0000000000..bed1a30b95 --- /dev/null +++ b/dom/docs/navigation/nav_replace.rst @@ -0,0 +1,95 @@ +Objects Replaced by Navigations +=============================== + +There are 3 major types of navigations, each of which can cause different +objects to be replaced. The general rules look something like this: + +.. csv-table:: objects replaced or preserved across navigations + :header: "Class/Id", ":ref:`in-process navigations`", ":ref:`cross-process navigations`", ":ref:`cross-group navigations`" + + "BrowserId [#bid]_", |preserve|, |preserve|, |preserve| + "BrowsingContextWebProgress", |preserve|, |preserve|, |preserve| + "BrowsingContextGroup", |preserve|, |preserve|, |replace| + "BrowsingContext", |preserve|, |preserve|, |replace| + "nsFrameLoader", |preserve|, |replace|, |replace| + "RemoteBrowser", |preserve|, |replace|, |replace| + "Browser{Parent,Child}", |preserve|, |replace|, |replace| + "nsDocShell", |preserve|, |replace|, |replace| + "nsGlobalWindowOuter", |preserve|, |replace|, |replace| + "nsGlobalWindowInner", "|replace| [#inner]_", |replace|, |replace| + "WindowContext", "|replace| [#inner]_", |replace|, |replace| + "WindowGlobal{Parent,Child}", "|replace| [#inner]_", |replace|, |replace| + "Document", "|replace|", |replace|, |replace| + + +.. |replace| replace:: ❌ replaced +.. |preserve| replace:: ✔️ preserved + +.. [#bid] + + The BrowserId is a unique ID on each ``BrowsingContext`` object, obtained + using ``GetBrowserId``, not a class. This ID will persist even when a + ``BrowsingContext`` is replaced (e.g. due to + ``Cross-Origin-Opener-Policy``). + +.. [#inner] + + When navigating from the initial ``about:blank`` document to a same-origin + document, the same ``nsGlobalWindowInner`` may be used. This initial + ``about:blank`` document is the one created when synchronously accessing a + newly-created pop-up window from ``window.open``, or a newly-created + document in an ``<iframe>``. + +Types of Navigations +-------------------- + +in-process navigations +^^^^^^^^^^^^^^^^^^^^^^ + +An in-process navigation is the traditional type of navigation, and the most +common type of navigation when :ref:`Fission` is not enabled. + +These navigations are used when no process switching or BrowsingContext +replacement is required, which includes most navigations with Fission +disabled, and most same site-origin navigations when Fission is enabled. + +cross-process navigations +^^^^^^^^^^^^^^^^^^^^^^^^^ + +A cross-process navigation is used when a navigation requires a process +switch to occur, and no BrowsingContext replacement is required. This is a +common type of load when :ref:`Fission` is enabled, though it is also used +for navigations to and from special URLs like ``file://`` URIs when +Fission is disabled. + +These process changes are triggered by ``DocumentLoadListener`` when it +determines that a process switch is required. See that class's documentation +for more details. + +cross-group navigations +^^^^^^^^^^^^^^^^^^^^^^^ + +A cross-group navigation is used when the navigation's `response requires +a browsing context group switch +<https://html.spec.whatwg.org/multipage/origin.html#browsing-context-group-switches-due-to-cross-origin-opener-policy>`_. + +These types of switches may or may not cause the process to change, but will +finish within a different ``BrowsingContextGroup`` than they started with. +Like :ref:`cross-process navigations`, these navigations are triggered using +the process switching logic in ``DocumentLoadListener``. + +As of the time of this writing, we currently trigger a cross-group navigation +in the following circumstances, though this may change in the future: + +- If the `Cross-Origin-Opener-Policy + <https://html.spec.whatwg.org/multipage/origin.html#the-cross-origin-opener-policy-header>`_ + header is specified, and a mismatch is detected. +- When switching processes between the parent process, and a content process. +- When loading an extension document in a toplevel browsing context. +- When navigating away from a preloaded ``about:newtab`` document. +- Sometimes, when loading a document with the ``Large-Allocation`` header on + 32-bit windows. + +State which needs to be saved over cross-group navigations on +``BrowsingContext`` instances is copied in the +``CanonicalBrowsingContext::ReplacedBy`` method. diff --git a/dom/docs/workersAndStorage/CodeStyle.rst b/dom/docs/workersAndStorage/CodeStyle.rst new file mode 100644 index 0000000000..7d8defe1e3 --- /dev/null +++ b/dom/docs/workersAndStorage/CodeStyle.rst @@ -0,0 +1,357 @@ +==================================== +DOM Workers & Storage C++ Code Style +==================================== + +This page describes the code style for the components maintained by the DOM Workers & Storage team. They live in-tree under the 'dom/docs/indexedDB' directory. + +This document is currently owned by Simon Giesecke <sgiesecke@mozilla.com>. + +.. contents:: + :depth: 4 + +Introduction +============ + +This code style currently applies to the components living in the following directories: + +* ``dom/file`` +* ``dom/indexedDB`` +* ``dom/localstorage`` +* ``dom/payments`` +* ``dom/quota`` +* ``dom/serviceworkers`` +* ``dom/workers`` + +In the long-term, the code is intended to use the +:ref:`Mozilla Coding Style <Coding style>`, +which references the `Google C++ Coding Style <https://google.github.io/styleguide/cppguide.html>`_. + +However, large parts of the code were written before rules and in particular +the reference to the Google C++ Coding Style were enacted, and due to the +size of the code, this misalignment cannot be fixed in the short term. +To avoid that an arbitrary mixture of old-style and new-style code grows, +this document makes deviations from the "global" code style explicit, and +will be amended to describe migration paths in the future. + +In addition, to achieve higher consistency within the components maintained by +the team and to reduce style discussions during reviews, allowing them to focus +on more substantial issues, more specific rules are described here that go +beyond the global code style. These topics might have been deliberately or +accidentally omitted from the global code style. Depending on wider agreement +and applicability, these specific rules might be migrated into the global code +style in the future. + +Note that this document does not cover pure formatting issues. The code is and +must be kept formatted automatically by clang-format using the supplied +configuration file, and whatever clang-format does takes precedence over any +other stated rules regarding formatting. + +Deviations from the Google C++ Coding Style +=========================================== + +Deviations not documented yet. + +Deviations from the Mozilla C++ Coding Style +============================================ + +.. the table renders impractically, cf. https://github.com/readthedocs/sphinx_rtd_theme/issues/117 + +.. tabularcolumns:: |p{4cm}|p{4cm}|p{2cm}|p{2cm}| + ++--------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------+-----------------+-------------------------------------------------------------------------------------+ +| Mozilla style | Prevalent WAS style | Deviation scope | Evolution | ++========================================================================================================+============================================================================================+=================+=====================================================================================+ +| `We prefer using "static", instead of anonymous C++ namespaces. | Place all symbols that should have internal linkage in a single anonymous | All files | Unclear. The recommendation in the Mozilla code style says this might change in the | +| | namespace block at the top of an implementation file, rather than declarating them static. | | future depending on debugger support, so this deviation might become obsolete. | +| | | | | ++--------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------+-----------------+-------------------------------------------------------------------------------------+ +| `All parameters passed by lvalue reference must be labeled const. [...] Input parameters may be const | Non-const reference parameters may be used. | All files | Unclear. Maybe at least restrict the use of non-const reference parameters to | +| pointers, but we never allow non-const reference parameters except when required by convention, e.g., | | | cases that are not clearly output parameters (i.e. which are assigned to). | +| swap(). <https://google.github.io/styleguide/cppguide.html#Reference_Arguments>`_ | | | | ++--------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------+-----------------+-------------------------------------------------------------------------------------+ + +Additions to the Google/Mozilla C++ Code Style +============================================== + +This section contains style guidelines that do not conflict with the Google or +Mozilla C++ Code Style, but may make guidelines more specific or add guidelines +on topics not covered by those style guides at all. + +Naming +------ + +gtest test names +~~~~~~~~~~~~~~~~ + +gtest constructs a full test name from different fragments. Test names are +constructed somewhat differently for basic and parametrized tests. + +The *prefix* for a test should start with an identifier of the component +and class, based on the name of the source code directory, transformed to +PascalCase and underscores as separators, so e.g. for a class ``Key`` in +``dom/indexedDB``, use ``DOM_IndexedDB_Key`` as a prefix. + +For basic tests constructed with ``TEST(test_case_name, test_name)``: Use +the *prefix* as the ``test_case_name``. Test ``test_name`` should start with +the name of tested method(s), and a . Use underscores as a separator within +the ``test_name``. + +Value-parametrized tests are constructed with +``TEST_P(parametrized_test_case_name, parametrized_test_name)``. They require a +custom test base class, whose name is used as the ``parametrized_test_case_name``. +Start the class name with ``TestWithParam_``, and end it with a transliteration +of the parameter type (e.g. ``String_Int_Pair`` for ``std::pair<nsString, int>``), +and place it in an (anonymous) namespace. + +.. attention:: + It is important to place the class in an (anonymous) namespace, since its + name according to this guideline is not unique within libxul-gtest, and name + clashes are likely, which would lead to ODR violations otherwise. + +A ``parametrized_test_name`` is constructed according to the same rules +described for ``test_name`` above. + +Instances of value-parametrized tests are constructed using +``INSTANTIATE_TEST_CASE_P(prefix, parametrized_test_case_name, generator, ...)``. +As ``prefix``, use the prefix as described above. + +Similar considerations apply to type-parametrized tests. If necessary, specific +rules for type-parametrized tests will be added here. + +Rationale + All gtests (not only from the WAS components) are linked into libxul-gtest, + which requires names to be unique within that large scope. In addition, it + should be clear from the test name (e.g. in the test execution log) in what + source file (or at least which directory) the test code can be found. + Optimally, test names should be structured hierarchically to allow + easy selection of groups of tests for execution. However, gtest has some + restrictions that do not allow that completely. The guidelines try to + accommodate for these as far as possible. Note that gtest recommends not to + use underscores in test names in general, because this may lead to reserved + names and naming conflicts, but the rules stated here should avoid that. + In case of any problems arising, we can evolve the rules to accommodate + for that. + +Specifying types +---------------- + +Use of ``auto`` for declaring variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The `Google C++ Code Style on auto <https://google.github.io/styleguide/cppguide.html#auto>`_ +allows the use of ``auto`` generally with encouragements for specific cases, which still +leaves a rather wide range for interpretation. + +We extend this by some more encouragements and discouragements: + +* DO use ``auto`` when the type is already present in the + initialization expression (esp. a template argument or similar), + e.g. ``auto c = static_cast<uint16_t>(*(iter++)) << 8;`` or + ``auto x = MakeRefPtr<MediaStreamError>(mWindow, *aError);`` + +* DO use ``auto`` if the spelled out type were complex otherwise, + e.g. a nested typedef or type alias, e.g. ``foo_container::value_type``. + +* DO NOT use ``auto`` if the type were spelled out as a builtin + integer type or one of the types from ``<cstdint>``, e.g. + instead of ``auto foo = funcThatReturnsUint16();`` use + ``uint16_t foo = funcThatReturnsUint16();``. + +.. note:: + Some disadvantages of using ``auto`` relate to the unavailability of type + information outside an appropriate IDE/editor. This may be somewhat remedied + by resolving `Bug 1567464 <https://bugzilla.mozilla.org/show_bug.cgi?id=1567464>`_ + which will make the type information available in searchfox. In consequence, + the guidelines might be amended to promote a more widespread use of ``auto``. + +Pointer types +------------- + +Plain pointers +~~~~~~~~~~~~~~ + +The use of plain pointers is error-prone. Avoid using owning plain pointers. In +particular, avoid using literal, non-placement new. There are various kinds +of smart pointers, not all of which provide appropriate factory functions. +However, where such factory functions exist, do use them (along with auto). +The following is an incomplete list of smart pointer types and corresponding +factory functions: + ++------------------------+-------------------------+------------------------+ +| Type | Factory function | Header file | ++========================+=========================+========================+ +| ``mozilla::RefPtr`` | ``mozilla::MakeRefPtr`` | ``"mfbt/RefPtr.h"`` | ++------------------------+-------------------------+------------------------+ +| ``mozilla::UniquePtr`` | ``mozilla::MakeUnique`` | ``"mfbt/UniquePtr.h"`` | ++------------------------+-------------------------+------------------------+ +| ``std::unique_ptr`` | ``std::make_unique`` | ``<memory>`` | ++------------------------+-------------------------+------------------------+ +| ``std::shared_ptr`` | ``std::make_shared`` | ``<memory>`` | ++------------------------+-------------------------+------------------------+ + +Also, to create an ``already_AddRefed<>`` to pass as a parameter or return from +a function without the need to dereference it, use ``MakeAndAddRef`` instead of +creating a dereferenceable ``RefPtr`` (or similar) first and then using +``.forget()``. + +Smart pointers +~~~~~~~~~~~~~~ + +In function signatures, prefer accepting or returning ``RefPtr`` instead of +``already_AddRefed`` in conjunction with regular ``std::move`` rather than +``.forget()``. This improves readability and code generation. Prevailing +legimitate uses of ``already_AddRefed`` are described in its +`documentation <https://searchfox.org/mozilla-central/rev/4df8821c1b824db5f40f381f48432f219d99ae36/mfbt/AlreadyAddRefed.h#31>`_. + +Prefer using ``mozilla::UniquePtr`` over ``nsAutoPtr``, since the latter is +deprecated (and e.g. has no factory function, see Bug 1600079). + +Use ``nsCOMPtr<T>`` iff ``T`` is an XPCOM interface type +(`more details on MDN <https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/nsCOMPtr_versus_RefPtr>`). + +Enums +----- + +Use scoped resp. strongly typed enums (``enum struct``) rather than non-scoped +enums. Use PascalCase for naming the values of scoped enums. + +Evolution Process +================= + +This section explains the process to evolve the coding style described in this +document. For clarity, we will distinguish coding tasks from code style +evolution tasks in this section. + +Managing code style evolution tasks +----------------------------------- + +A code style evolution task is a task that ought to amend or revise the +coding style as described in this document. + +Code style evolution tasks should be managed in Bugzilla, as individual bugs +for each topic. All such tasks +should block the meta-bug +`1586788 <https://bugzilla.mozilla.org/show_bug.cgi?id=1586788>`. + +When you take on to work on a code style evolution task: + +- The task may already include a sketch of a resolution. If no preferred + solution is obvious, discuss options to resolve it via comments on the bug + first. +- When the general idea is ready to be spelled out in this document, amend or + revise it accordingly. +- Submit the changes to this document as a patch to Phabricator, and put it up + for review. Since this will affect a number of people, every change should + be reviewed by at least two people. Ideally, this should include the owner + of this style document and one person with good knowledge of the parts of + the code base this style applies to. +- If there are known violations of the amendment to the coding style, consider + fixing some of them, so that the amendment is tested on actual code. If + the code style evolution task refers to a particular code location from a + review, at least that location should be fixed to comply with the amended + coding style. +- When you have two r+, land the patch. +- Report on the addition in the next team meeting to raise awareness. + +Basis for code style evolution tasks +------------------------------------ + +The desire or necessity to evolve the code style can originate from +different activities, including +- reviews +- reading or writing code locally +- reading the coding style +- general thoughts on coding style + +The code style should not be cluttered with aspects that are rarely +relevant or rarely leads to discussions, as the maintenance of the +code style has a cost as well. The code style should be as comprehensive +as necessary to reduce the overall maintenance costs of the code and +code style combined. + +A particular focus is therefore on aspects that led to some discussion in +a code review, as reducing the number or verbosity of necessary style +discussions in reviews is a major indicator for the effectiveness of the +documented style. + +Evolving code style based on reviews +------------------------------------ + +The goal of the process described here is to take advantage of style-related +discussions that originate from a code review, but to decouple evolution of +the code style from the review process, so that it does not block progress on +the underlying bug. + +The following should be considered when performing a review: + +- Remind yourself of the code style, maybe skim through the document before + starting the review, or have it open side-by-side while doing the review. +- If you find a violation of an existing rule, add an inline comment. +- Have an eye on style-relevant aspects in the code itself or after a + discussions with the author. Consider if this could be generalized into a + style rule, but is not yet covered by the documented global or local style. + This might be something that is in a different style as opposed to other + locations, differs from your personal style, etc. +- In that case, find an acceptable temporary solution for the code fragments + at hand, which is acceptable for an r+ of the patch. Maybe agree with the + code author on adding a comment that this should be revised later, when + a rule is codified. +- Create a code style evolution task in Bugzilla as described above. In the + description of the bug, reference the review comment that gave rise to it. + If you can suggest a resolution, include that in the description, but this + is not a necessary condition for creating the task. + +Improving code style compliance when writing code +------------------------------------------------- + +Periodically look into the code style document, and remind yourself of its +rules, and give particular attention to recent changes. + +When writing code, i.e. adding new code or modify existing code, +remind yourself of checking the code for style compliance. + +Time permitting, resolve existing violations on-the-go as part of other work +in the code area. Submit such changes in dedicated patches. If you identify +major violations that are too complex to resolve on-the-go, consider +creating a bug dedicated to the resolution of that violation, which +then can be scheduled in the planning process. + +Syncing with the global Mozilla C++ Coding Style +------------------------------------------------ + +Several aspects of the coding style described here will be applicable to +the overall code base. However, amendments to the global coding style will +affect a large number of code authors and may require extended discussion. +Deviations from the global coding style should be limited in the long term. +On the other hand, amendments that are not relevant to all parts of the code +base, or where it is difficult to reach a consensus at the global scope, +may make sense to be kept in the local style. + +The details of synchronizing with the global style are subject to discussion +with the owner and peers of the global coding style (see +`Bug 1587810 <https://bugzilla.mozilla.org/show_bug.cgi?id=1587810>`). + +FAQ +--- + +* When someone introduces new code that adheres to the current style, but the + remainder of the function/class/file does not, is it their responsibility + to update that remainder on-the-go? + + The code author is not obliged to update the remainder, but they are + encouraged to do so, time permitting. Whether that is the case depends on a + number of factors, including the number and complexity of existing style + violations, the risk introduced by changing that on the go etc. Judging this + is left to the code author. + At the very least, the function/class/file should not be left in a worse + state than before. + +* Are stylistic inconsistencies introduced by applying the style as defined + here only to new code considered acceptable? + + While this is certainly not optimal, accepting such inconsistencies to + some degree is inevitable to allow making progress towards an improved style. + Personal preferences regarding the degree may differ, but in doubt such + inconsistencies should be considered acceptable. They should not block a bug + from being closed. + diff --git a/dom/docs/workersAndStorage/index.rst b/dom/docs/workersAndStorage/index.rst new file mode 100644 index 0000000000..2d2f2a761e --- /dev/null +++ b/dom/docs/workersAndStorage/index.rst @@ -0,0 +1,9 @@ +DOM Workers & Storage +===================== + +These linked pages contain design documents for the Workers & Storage implementations in Gecko. They live in-tree under the 'dom/docs/workerAndStorage' directory. + +.. toctree:: + :maxdepth: 1 + + CodeStyle |
