dom/localstorage/PBackgroundLSRequest.ipdl

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