dom/localstorage/PBackgroundLSSnapshot.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 include protocol PBackgroundLSDatabase;
   7
   8 include PBackgroundLSSharedTypes;
   9
  10 include "mozilla/dom/localstorage/SerializationHelpers.h";
  11
  12 using mozilla::dom::LSValue
  13   from "mozilla/dom/LSValue.h";
  14
  15 namespace mozilla {
  16 namespace dom {
  17
  18 struct LSSetItemInfo
  19 {
  20   nsString key;
  21   LSValue value;
  22 };
  23
  24 struct LSRemoveItemInfo
  25 {
  26   nsString key;
  27 };
  28
  29 struct LSClearInfo
  30 {
  31 };
  32
  33 /**
  34  * Union of LocalStorage mutation types.
  35  */
  36 union LSWriteInfo
  37 {
  38   LSSetItemInfo;
  39   LSRemoveItemInfo;
  40   LSClearInfo;
  41 };
  42
  43 struct LSSetItemAndNotifyInfo
  44 {
  45   nsString key;
  46   LSValue oldValue;
  47   LSValue value;
  48 };
  49
  50 struct LSRemoveItemAndNotifyInfo
  51 {
  52   nsString key;
  53   LSValue oldValue;
  54 };
  55
  56 /**
  57  * Union of LocalStorage mutation types.
  58  */
  59 union LSWriteAndNotifyInfo
  60 {
  61   LSSetItemAndNotifyInfo;
  62   LSRemoveItemAndNotifyInfo;
  63   LSClearInfo;
  64 };
  65
  66 [ManualDealloc, ChildImpl=virtual, ParentImpl=virtual]
  67 sync protocol PBackgroundLSSnapshot
  68 {
  69   manager PBackgroundLSDatabase;
  70
  71 parent:
  72   async DeleteMe();
  73
  74   async AsyncCheckpoint(LSWriteInfo[] writeInfos);
  75
  76   async AsyncCheckpointAndNotify(LSWriteAndNotifyInfo[] writeAndNotifyInfos);
  77
  78   // A synchronous checkpoint. This should only be used by the snapshotting code
  79   // to checkpoint an explicit snapshot.
  80   sync SyncCheckpoint(LSWriteInfo[] writeInfos);
  81
  82   // A synchronous checkpoint and notify. This should only be used by the
  83   // snapshotting code to checkpoint and notify an explicit snapshot.
  84   sync SyncCheckpointAndNotify(LSWriteAndNotifyInfo[] writeAndNotifyInfos);
  85
  86   async AsyncFinish();
  87
  88   // A synchronous finish. This should only be used by the snapshotting code to
  89   // end an explicit snapshot.
  90   sync SyncFinish();
  91
  92   async Loaded();
  93
  94   /**
  95    * Invoked on demand to load an item that didn't fit into the initial
  96    * snapshot prefill and also some additional key/value pairs to lower down
  97    * the need to use this synchronous message again.
  98    *
  99    * This needs to be synchronous because LocalStorage's semantics are
 100    * synchronous.  Note that the Snapshot in the PBackground parent already
 101    * has the answers to this request immediately available without needing to
 102    * consult any other threads or perform any I/O.
 103    */
 104   sync LoadValueAndMoreItems(nsString key)
 105     returns (LSValue value, LSItemInfo[] itemInfos);
 106
 107   /**
 108    * Invoked on demand to load all keys in in their canonical order if they
 109    * didn't fit into the initial snapshot prefill.
 110    *
 111    * This needs to be synchronous because LocalStorage's semantics are
 112    * synchronous.  Note that the Snapshot in the PBackground parent already
 113    * has the answers to this request immediately available without needing to
 114    * consult any other threads or perform any I/O.
 115    */
 116   sync LoadKeys()
 117     returns (nsString[] keys);
 118
 119   /**
 120    * This needs to be synchronous because LocalStorage's semantics are
 121    * synchronous.  Note that the Snapshot in the PBackground parent typically
 122    * doesn't need to consult any other threads or perform any I/O to handle
 123    * this request.  However, it has to call a quota manager method that can
 124    * potentially do I/O directly on the PBackground thread.  It can only happen
 125    * rarely in a storage pressure (low storage space) situation.  Specifically,
 126    * after we get a list of origin directories for eviction, we will delete
 127    * them directly on the PBackground thread.  This doesn't cause any
 128    * performance problems, but avoiding I/O completely might need to be done as
 129    * a futher optimization.
 130    */
 131   sync IncreasePeakUsage(int64_t minSize)
 132     returns (int64_t size);
 133
 134 child:
 135   /**
 136    * Compels the child LSSnapshot to Checkpoint() and Finish(), effectively
 137    * compelling the snapshot to flush any issued mutations and close itself.
 138    * The child LSSnapshot does that either immediately if it's just waiting
 139    * to be reused or when it gets into a stable state.
 140    *
 141    * This message is expected to be sent in the following two cases only:
 142    *   1. The state of the underlying Datastore starts to differ from the state
 143    *      captured at the time of snapshot creation.
 144    *   2. The last private browsing context exits.  And in that case we expect
 145    *      all private browsing globals to already have been destroyed.
 146    */
 147   async MarkDirty();
 148
 149   async __delete__();
 150 };
 151
 152 } // namespace dom
 153 } // namespace mozilla