From 36d22d82aa202bb199967e9512281e9a53db42c9 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 21:33:14 +0200 Subject: Adding upstream version 115.7.0esr. Signed-off-by: Daniel Baumann --- ipc/docs/utility_process.rst | 69 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 ipc/docs/utility_process.rst (limited to 'ipc/docs/utility_process.rst') diff --git a/ipc/docs/utility_process.rst b/ipc/docs/utility_process.rst new file mode 100644 index 0000000000..8940a56317 --- /dev/null +++ b/ipc/docs/utility_process.rst @@ -0,0 +1,69 @@ +Utility Process +=============== + +.. warning:: + As of january 2022, this process is under heavy work, and many things can + evolve. Documentation might not always be as accurate as it should be. + Please reach to #ipc if you intent to add a new utility. + +The utility process is used to provide a simple way to implement IPC actor with +some more specific sandboxing properties, in case where you don't need or want +to deal with the extra complexity of adding a whole new process type but you +just want to apply different sandboxing policies. +To implement such an actor, you will have to follow a few steps like for +implementing the trivial example visible in `EmptyUtil +`_: + + - Define a new IPC actor, e.g., ``PEmptyUtil`` that allows to get some string + via ``GetSomeString()`` from the child to the parent + + - In the ``PUtilityProcess`` definition, expose a new child-level method, + e.g., ``StartEmptyUtilService(Endpoint)`` + + - Implement ``EmptyUtilChild`` and ``EmptyUtilParent`` classes both deriving + from their ``PEmptyUtilXX``. If you want or need to run things from a + different thread, you can have a look at ``UtilityProcessGenericActor`` + + - Make sure both are refcounted + + - Expose your new service on ``UtilityProcessManager`` with a method + performing the heavy lifting of starting your process, you can take + inspiration from ``StartEmptyUtil()`` in the sample. + + - Ideally, this starting method should rely on `StartUtility() `_ + + - To use ``StartUtility()`` mentioned above, please ensure that you provide + a ``nsresult BindToUtilityProcess(RefPtr + aUtilityParent)``. Usually, it should be in charge of creating a set of + endpoints and performing ``Bind()`` to setup the IPC. You can see some example for `Utility AudioDecoder `_ + + - For proper user-facing exposition in ``about:processes`` you will have to also provide an actor + name via a method ``UtilityActorName GetActorName() { return UtilityActorName::EmptyUtil; }`` + + + Add member within `enum WebIDLUtilityActorName in `_ + + - Handle reception of ``StartEmptyUtilService`` on the child side of + ``UtilityProcess`` within ``RecvStartEmptyUtilService()`` + + - In ``UtilityProcessChild::ActorDestroy``, release any resources that + you stored a reference to in ``RecvStartEmptyUtilService()``. This + will probably include a reference to the ``EmptyUtilChild``. + + - The specific sandboxing requirements can be implemented by tracking + ``SandboxingKind``, and it starts within `UtilityProcessSandboxing header + `_ + + - Try and make sure you at least add some ``gtest`` coverage of your new + actor, for example like in `existing gtest + `_ + + - Also ensure actual sandbox testing within + + + ``SandboxTest`` to start your new process, + ``_ + + + ``SandboxTestingChildTests`` to define the test + ``_ + + + ``SandboxTestingChild`` to run your test + ``_ -- cgit v1.2.3