Source code

Revision control

Copy as Markdown

Other Tools

/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this file,
* You can obtain one at http://mozilla.org/MPL/2.0/. */
include protocol PBackground;
include protocol PBackgroundLSSnapshot;
include PBackgroundLSSharedTypes;
include "mozilla/dom/localstorage/SerializationHelpers.h";
using mozilla::dom::LSSnapshot::LoadState
from "mozilla/dom/LSSnapshot.h";
namespace mozilla {
namespace dom {
/**
* Initial LSSnapshot state as produced by Datastore::GetSnapshotLoadInfo. See
* `LSSnapshot::LoadState` for more details about the possible states and a
* high level overview.
*/
struct LSSnapshotInitInfo
{
/**
* Boolean indicating whether the `key` provided as an argument to the
* PBackgroundLSSnapshot constructor did not exist in the Datastore and should
* be treated as an unknown and therefore undefined value. Note that `key` may
* have been provided as a void string, in which case this value is forced to
* be false.
*/
bool addKeyToUnknownItems;
/**
* As many key/value or key/void pairs as the snapshot prefill byte budget
* allowed.
*/
LSItemInfo[] itemInfos;
/**
* The total number of key/value pairs in LocalStorage for this origin at the
* time the snapshot was created. (And the point of the snapshot is to
* conceptually freeze the state of the Datastore in time, so this value does
* not change despite what other LSDatabase objects get up to in other
* processes.)
*/
uint32_t totalLength;
/**
* The current amount of LocalStorage usage as measured by the summing the
* nsString Length() of both the key and the value over all stored pairs.
*/
int64_t usage;
/**
* The amount of storage allowed to be used by the Snapshot without requesting
* more storage space via IncreasePeakUsage. This is the `usage` plus 0 or
* more bytes of space. If space was available, the increase will be the
* `minSize` from the PBackgroundLSSnapshot constructor plus the configured
* pre-increment (via "dom.storage.snapshot_peak_usage.initial_preincrement").
* If the LocalStorage total usage was already close to the limit, then the
* fallback is either the `minSize` plus the configured reduced pre-increment
* (via "dom.storage.snapshot_peak_usage.reduced_initial_preincrement"), or
* `minSize`, or 0 depending on remaining available space.
*/
int64_t peakUsage;
// See `LSSnapshot::LoadState` in `LSSnapshot.h`
LoadState loadState;
/**
* Boolean indicating whether there where cross-process databases registered
* for this origin at the time the snapshot was created.
*/
bool hasOtherProcessDatabases;
/**
* Boolean indicating whether there where cross-process observers registered
* for this origin at the time the snapshot was created.
*/
bool hasOtherProcessObservers;
};
/**
* This protocol is asynchronously created via constructor on PBackground but
* has synchronous semantics from the perspective of content on the main thread.
* The construction potentially involves waiting for disk I/O to load the
* LocalStorage data from disk as well as related QuotaManager checks, so async
* calls to PBackground are the only viable mechanism because blocking
* PBackground is not acceptable. (Note that an attempt is made to minimize any
* I/O latency by triggering preloading from
* ContentParent::AboutToLoadHttpDocumentForChild, the central place
* for pre-loading.)
*/
[ChildImpl=virtual, ParentImpl=virtual]
sync protocol PBackgroundLSDatabase
{
manager PBackground;
manages PBackgroundLSSnapshot;
parent:
// The DeleteMe message is used to avoid a race condition between the parent
// actor and the child actor. The PBackgroundLSDatabase protocol could be
// simply destroyed by sending the __delete__ message from the child side.
// However, that would destroy the child actor immediatelly and the parent
// could be sending a message to the child at the same time resulting in a
// routing error since the child actor wouldn't exist anymore. A routing
// error typically causes a crash. The race can be prevented by doing the
// teardown in two steps. First, we send the DeleteMe message to the parent
// and the parent then sends the __delete__ message to the child.
async DeleteMe();
/**
* Sent in response to a `RequestAllowToClose` message once the snapshot
* cleanup has happened OR from LSDatabase's destructor if AllowToClose has
* not already been reported.
*/
async AllowToClose();
/**
* Invoked to create an LSSnapshot backed by a Snapshot in PBackground that
* presents an atomic and consistent view of the state of the authoritative
* Datastore state in the parent.
*
* This needs to be synchronous because LocalStorage's semantics are
* synchronous. Note that the Datastore in the PBackground parent already
* has the answers to this request immediately available without needing to
* consult any other threads or perform any I/O. Additionally, the response
* is explicitly bounded in size by the tunable snapshot prefill byte limit.
*
* @param key
* If key is non-void, then the snapshot is being triggered by a direct
* access to a localStorage key (get, set, or removal, with set/removal
* requiring the old value in order to properly populate the "storage"
* event), the key being requested. It's possible the key is not present in
* localStorage, in which case LSSnapshotInitInfo::addKeyToUnknownItems will
* be true indicating that there is no such key/value pair, otherwise it
* will be false.
* @param increasePeakUsage
* Whether the parent should increase initial peak uage of the Snapshot.
* See also the comment for LSSnapshotInitInfo::peakUsage above.
*/
sync PBackgroundLSSnapshot(nsString documentURI,
nsString key,
bool increasePeakUsage,
int64_t minSize)
returns (LSSnapshotInitInfo initInfo);
child:
/**
* Only sent by the parent in response to the child's DeleteMe request.
*/
async __delete__();
/**
* Request to close the LSDatabase, checkpointing and finishing any
* outstanding snapshots so no state is lost. This request is issued when
* QuotaManager is shutting down or is aborting operations for an origin or
* process. Once the snapshot has cleaned up, AllowToClose will be sent to
* the parent.
*
* Note that the QuotaManager shutdown process is more likely to happen in
* unit tests where we explicitly reset the QuotaManager. At runtime, we
* expect windows to be closed and content processes terminated well before
* QuotaManager shutdown would actually occur.
*
* Also, Operations are usually aborted for an origin due to privacy API's
* clearing data for an origin. Operations are aborted for a process by
* ContentParent::ShutDownProcess.
*/
async RequestAllowToClose();
};
} // namespace dom
} // namespace mozilla