Bug 1763652 - Update utility process doc about UtilityProcessManager::StartUtility r=handyman

Differential Revision: https://phabricator.services.mozilla.com/D143840

ipc/docs/utility_process.rst

@@ -16,28 +16,54 @@ 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<PEmptyUtilChild>)``
+
   - 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()`` there.
+    inspiration from ``StartEmptyUtil()`` in the sample.
+
+  - Ideally, this starting method should rely on `StartUtility() <https://searchfox.org/mozilla-central/rev/fb511723f821ceabeea23b123f1c50c9e93bde9d/ipc/glue/UtilityProcessManager.cpp#210-258,266>`_
+
+  - To use ``StartUtility()`` mentioned above, please ensure that you provide
+    a ``nsresult BindToUtilityProcess(RefPtr<UtilityProcessParent>
+    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 <https://searchfox.org/mozilla-central/rev/4b3039b48c3cb67774270ebcc2a7d8624d888092/ipc/glue/UtilityAudioDecoderChild.h#31-51>`_
+
+  - 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 <https://searchfox.org/mozilla-central/rev/fb511723f821ceabeea23b123f1c50c9e93bde9d/dom/chrome-webidl/ChromeUtils.webidl#686-689>`_
+
+    + Add member within `enum class UtilityActorName of <https://searchfox.org/mozilla-central/rev/fb511723f821ceabeea23b123f1c50c9e93bde9d/toolkit/components/processtools/ProcInfo.h#71-74>`_
+
+    + Update mapping in `switch case <https://searchfox.org/mozilla-central/rev/fb511723f821ceabeea23b123f1c50c9e93bde9d/dom/base/ChromeUtils.cpp#916-919>`_ and update the `static assert <https://searchfox.org/mozilla-central/rev/fb511723f821ceabeea23b123f1c50c9e93bde9d/dom/base/ChromeUtils.cpp#910-911>`_
+
   - Handle reception of ``StartEmptyUtilService`` on the child side of
     ``UtilityProcess`` within ``RecvStartEmptyUtilService()``
+
   - The specific sandboxing requirements can be implemented by tracking
     ``SandboxingKind``, and it starts within `UtilityProcessSandboxing header
     <https://searchfox.org/mozilla-central/source/ipc/glue/UtilityProcessSandboxing.h>`_
+
   - Try and make sure you at least add some ``gtest`` coverage of your new
     actor, for example like in `existing gtest
     <https://searchfox.org/mozilla-central/source/ipc/glue/test/gtest/TestUtilityProcess.cpp>`_
+
   - Also ensure actual sandbox testing within
 
     + ``SandboxTest`` to start your new process,
       `<https://searchfox.org/mozilla-central/source/security/sandbox/common/test/SandboxTest.cpp>`_
+
     + ``SandboxTestingChildTests`` to define the test
       `<https://searchfox.org/mozilla-central/source/security/sandbox/common/test/SandboxTestingChildTests.h>`_
+
     + ``SandboxTestingChild`` to run your test
       `<https://searchfox.org/mozilla-central/source/security/sandbox/common/test/SandboxTestingChild.cpp>`_