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/. */
5 include protocol PBackground;
7 using struct mozilla::null_t from "mozilla/ipc/IPCCore.h";
12 struct LSRequestPreloadDatastoreResponse
16 struct LSRequestPrepareDatastoreResponse
21 struct LSRequestPrepareObserverResponse
27 * Discriminated union which can contain an error code (`nsresult`) or
28 * particular request response.
30 union LSRequestResponse
33 LSRequestPreloadDatastoreResponse;
34 LSRequestPrepareDatastoreResponse;
35 LSRequestPrepareObserverResponse;
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.
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.
47 [ManualDealloc, ChildImpl=virtual, ParentImpl=virtual]
48 protocol PBackgroundLSRequest
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.
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.
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.
83 * The deletion is sent with the result of the request directly in response to
84 * either Cancel or Finish.
86 async __delete__(LSRequestResponse response);
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
103 } // namespace mozilla