tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

PBackgroundLSRequest.ipdl (3961B)

      1 /* This Source Code Form is subject to the terms of the Mozilla Public
      2  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
      3  * You can obtain one at http://mozilla.org/MPL/2.0/. */
      4 
      5 include protocol PBackground;
      6 include protocol PBackgroundLSDatabase;
      7 
      8 using struct mozilla::null_t from "mozilla/ipc/IPCCore.h";
      9 
     10 namespace mozilla {
     11 namespace dom {
     12 
     13 struct LSRequestPreloadDatastoreResponse
     14 {
     15   bool invalidated;
     16 };
     17 
     18 struct LSRequestPrepareDatastoreResponse
     19 {
     20   Endpoint<PBackgroundLSDatabaseChild> databaseChildEndpoint;
     21   bool invalidated;
     22 };
     23 
     24 struct LSRequestPrepareObserverResponse
     25 {
     26   uint64_t observerId;
     27 };
     28 
     29 /**
     30  * Discriminated union which can contain an error code (`nsresult`) or
     31  * particular request response.
     32  */
     33 union LSRequestResponse
     34 {
     35   nsresult;
     36   LSRequestPreloadDatastoreResponse;
     37   LSRequestPrepareDatastoreResponse;
     38   LSRequestPrepareObserverResponse;
     39 };
     40 
     41 /**
     42  * An asynchronous protocol for issuing requests that are used in a synchronous
     43  * fashion by LocalStorage via LSObject's RequestHelper mechanism.  This differs
     44  * from LSSimpleRequest which is implemented and used asynchronously.
     45  *
     46  * See `PBackgroundLSSharedTypes.ipdlh` for more on the request types, the
     47  * response types above for their corresponding responses, and `RequestHelper`
     48  * for more on the usage and lifecycle of this mechanism.
     49  */
     50 [ManualDealloc, ChildImpl=virtual, ParentImpl=virtual]
     51 protocol PBackgroundLSRequest
     52 {
     53   manager PBackground;
     54 
     55 parent:
     56   // The Cancel message is used to avoid a possible dead lock caused by a CPOW
     57   // sending a synchronous message from the main thread in the chrome process
     58   // to the main thread in the content process at the time we are blocking
     59   // the main thread in the content process to handle a request.
     60   // We use the PBackground thread on the parent side to handle requests, but
     61   // sometimes we need to get information from principals and that's currently
     62   // only possible on the main thread. So if the main thread in the chrome
     63   // process is blocked by a CPOW operation, our request must wait for the CPOW
     64   // operation to complete. However the CPOW operation can't complete either
     65   // because we are blocking the main thread in the content process.
     66   // The dead lock is prevented by canceling our nested event loop in the
     67   // content process when we receive a synchronous IPC message from the parent.
     68   //
     69   // Note that cancellation isn't instantaneous.  It's just an asynchronous flow
     70   // that definitely doesn't involve the main thread in the parent process, so
     71   // we're guaranteed to unblock the main-thread in the content process and
     72   // allow the sync IPC to make progress.  When Cancel() is received by the
     73   // parent, it will Send__delete__.  The child will either send Cancel or
     74   // Finish, but not both.
     75   async Cancel();
     76 
     77   /**
     78    * Sent by the child in response to Ready, requesting that __delete__ be sent
     79    * with the result.  The child will either send Finish or Cancel, but not
     80    * both.  No further message will be sent from the child after invoking one.
     81    */
     82   async Finish();
     83 
     84 child:
     85   /**
     86    * The deletion is sent with the result of the request directly in response to
     87    * either Cancel or Finish.
     88    */
     89   async __delete__(LSRequestResponse response);
     90 
     91   /**
     92    * Sent by the parent when it has completed whatever async stuff it needs to
     93    * do and is ready to send the results.  It then awaits the Finish() call to
     94    * send the results.  This may seem redundant, but it's not.  If the
     95    * __delete__ was sent directly, it's possible there could be a race where
     96    * Cancel() would be received by the parent after it had already sent
     97    * __delete__.  (Which may no longer be fatal thanks to improvements to the
     98    * IPC layer, but it would still lead to warnings, etc.  And we don't
     99    * expect PBackground to be highly contended nor the RemoteLazyInputStream
    100    * thread.)
    101    */
    102   async Ready();
    103 };
    104 
    105 } // namespace dom
    106 } // namespace mozilla