PBackgroundLSDatabase.ipdl (6267B)
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 PBackgroundLSSnapshot; 6 7 include PBackgroundLSSharedTypes; 8 9 include "mozilla/dom/localstorage/SerializationHelpers.h"; 10 11 using mozilla::dom::LSSnapshot::LoadState 12 from "mozilla/dom/LSSnapshot.h"; 13 14 namespace mozilla { 15 namespace dom { 16 17 /** 18 * Initial LSSnapshot state as produced by Datastore::GetSnapshotLoadInfo. See 19 * `LSSnapshot::LoadState` for more details about the possible states and a 20 * high level overview. 21 */ 22 struct LSSnapshotInitInfo 23 { 24 /** 25 * Boolean indicating whether the `key` provided as an argument to the 26 * PBackgroundLSSnapshot constructor did not exist in the Datastore and should 27 * be treated as an unknown and therefore undefined value. Note that `key` may 28 * have been provided as a void string, in which case this value is forced to 29 * be false. 30 */ 31 bool addKeyToUnknownItems; 32 33 /** 34 * As many key/value or key/void pairs as the snapshot prefill byte budget 35 * allowed. 36 */ 37 LSItemInfo[] itemInfos; 38 39 /** 40 * The total number of key/value pairs in LocalStorage for this origin at the 41 * time the snapshot was created. (And the point of the snapshot is to 42 * conceptually freeze the state of the Datastore in time, so this value does 43 * not change despite what other LSDatabase objects get up to in other 44 * processes.) 45 */ 46 uint32_t totalLength; 47 48 /** 49 * The current amount of LocalStorage usage as measured by the summing the 50 * nsString Length() of both the key and the value over all stored pairs. 51 */ 52 int64_t usage; 53 54 /** 55 * The amount of storage allowed to be used by the Snapshot without requesting 56 * more storage space via IncreasePeakUsage. This is the `usage` plus 0 or 57 * more bytes of space. If space was available, the increase will be the 58 * `minSize` from the PBackgroundLSSnapshot constructor plus the configured 59 * pre-increment (via "dom.storage.snapshot_peak_usage.initial_preincrement"). 60 * If the LocalStorage total usage was already close to the limit, then the 61 * fallback is either the `minSize` plus the configured reduced pre-increment 62 * (via "dom.storage.snapshot_peak_usage.reduced_initial_preincrement"), or 63 * `minSize`, or 0 depending on remaining available space. 64 */ 65 int64_t peakUsage; 66 67 // See `LSSnapshot::LoadState` in `LSSnapshot.h` 68 LoadState loadState; 69 70 /** 71 * Boolean indicating whether there where cross-process databases registered 72 * for this origin at the time the snapshot was created. 73 */ 74 bool hasOtherProcessDatabases; 75 76 /** 77 * Boolean indicating whether there where cross-process observers registered 78 * for this origin at the time the snapshot was created. 79 */ 80 bool hasOtherProcessObservers; 81 }; 82 83 /** 84 * This protocol is asynchronously created via constructor on PBackground but 85 * has synchronous semantics from the perspective of content on the main thread. 86 * The construction potentially involves waiting for disk I/O to load the 87 * LocalStorage data from disk as well as related QuotaManager checks, so async 88 * calls to PBackground are the only viable mechanism because blocking 89 * PBackground is not acceptable. (Note that an attempt is made to minimize any 90 * I/O latency by triggering preloading from 91 * ContentParent::AboutToLoadHttpDocumentForChild, the central place 92 * for pre-loading.) 93 */ 94 [ChildImpl=virtual, ParentImpl=virtual, ChildProc=anydom] 95 sync protocol PBackgroundLSDatabase 96 { 97 manages PBackgroundLSSnapshot; 98 99 parent: 100 /** 101 * Sent in response to a `RequestAllowToClose` message once the snapshot 102 * cleanup has happened OR from LSDatabase's destructor if AllowToClose has 103 * not already been reported. 104 */ 105 async AllowToClose(); 106 107 /** 108 * Invoked to create an LSSnapshot backed by a Snapshot in PBackground that 109 * presents an atomic and consistent view of the state of the authoritative 110 * Datastore state in the parent. 111 * 112 * This needs to be synchronous because LocalStorage's semantics are 113 * synchronous. Note that the Datastore in the PBackground parent already 114 * has the answers to this request immediately available without needing to 115 * consult any other threads or perform any I/O. Additionally, the response 116 * is explicitly bounded in size by the tunable snapshot prefill byte limit. 117 * 118 * @param key 119 * If key is non-void, then the snapshot is being triggered by a direct 120 * access to a localStorage key (get, set, or removal, with set/removal 121 * requiring the old value in order to properly populate the "storage" 122 * event), the key being requested. It's possible the key is not present in 123 * localStorage, in which case LSSnapshotInitInfo::addKeyToUnknownItems will 124 * be true indicating that there is no such key/value pair, otherwise it 125 * will be false. 126 * @param increasePeakUsage 127 * Whether the parent should increase initial peak uage of the Snapshot. 128 * See also the comment for LSSnapshotInitInfo::peakUsage above. 129 */ 130 sync PBackgroundLSSnapshot(nsString documentURI, 131 nsString key, 132 bool increasePeakUsage, 133 int64_t minSize) 134 returns (LSSnapshotInitInfo initInfo); 135 136 child: 137 /** 138 * Request to close the LSDatabase, checkpointing and finishing any 139 * outstanding snapshots so no state is lost. This request is issued when 140 * QuotaManager is shutting down or is aborting operations for an origin or 141 * process. Once the snapshot has cleaned up, AllowToClose will be sent to 142 * the parent. 143 * 144 * Note that the QuotaManager shutdown process is more likely to happen in 145 * unit tests where we explicitly reset the QuotaManager. At runtime, we 146 * expect windows to be closed and content processes terminated well before 147 * QuotaManager shutdown would actually occur. 148 * 149 * Also, Operations are usually aborted for an origin due to privacy API's 150 * clearing data for an origin. Operations are aborted for a process by 151 * ContentParent::ShutDownProcess. 152 */ 153 async RequestAllowToClose(); 154 }; 155 156 } // namespace dom 157 } // namespace mozilla