diff options
Diffstat (limited to '')
| -rw-r--r-- | toolkit/components/asyncshutdown/nsIAsyncShutdown.idl | 229 |
1 files changed, 229 insertions, 0 deletions
diff --git a/toolkit/components/asyncshutdown/nsIAsyncShutdown.idl b/toolkit/components/asyncshutdown/nsIAsyncShutdown.idl new file mode 100644 index 0000000000..945772bd51 --- /dev/null +++ b/toolkit/components/asyncshutdown/nsIAsyncShutdown.idl @@ -0,0 +1,229 @@ +/* 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/. */ + +/** + * A mechanism for specifying shutdown dependencies between + * asynchronous services. + * + * Note that this XPCOM component is designed primarily for C++ + * clients. JavaScript clients should rather use AsyncShutdown.sys.mjs, + * which provides a better API and better error reporting for them. + */ + + +#include "nsISupports.idl" +#include "nsIPropertyBag.idl" +#include "nsIVariant.idl" + +interface nsIAsyncShutdownClient; + +/** + * A blocker installed by a client to be informed during some stage of + * shutdown and block shutdown asynchronously until some condition is + * complete. + * + * If you wish to use AsyncShutdown, you will need to implement this + * interface (and only this interface). + */ +[scriptable, uuid(4ef43f29-6715-4b57-a750-2ff83695ddce)] +interface nsIAsyncShutdownBlocker: nsISupports { + /** + * The *unique* name of the blocker. + * + * By convention, it should respect the following format: + * "MyModuleName: Doing something while it's time" + * e.g. + * "OS.File: Flushing before profile-before-change" + * + * This attribute is uploaded as part of crash reports. + */ + readonly attribute AString name; + + /** + * Inform the blocker that the stage of shutdown has started. + * Shutdown will NOT proceed until `aBarrierClient.removeBlocker(this)` + * has been called. + */ + void blockShutdown(in nsIAsyncShutdownClient aBarrierClient); + + /** + * The current state of the blocker. + * + * In case of crash, this is converted to JSON and attached to + * the crash report. + * + * This field may be used to provide JSON-style data structures. + * For this purpose, use + * - nsIPropertyBag to represent objects; + * - nsIVariant to represent field values (which may hold nsIPropertyBag + * themselves). + */ + readonly attribute nsIPropertyBag state; +}; + +/** + * A client for a nsIAsyncShutdownBarrier. + */ +[scriptable, uuid(d2031049-b990-43a2-95be-59f8a3ca5954)] +interface nsIAsyncShutdownClient: nsISupports { + /** + * The name of the barrier. + */ + readonly attribute AString name; + + /** + * Whether the client is still open for new blockers. + * When this is true it is too late to add new blockers and addBlocker will + * throw an exception. + */ + readonly attribute boolean isClosed; + + /** + * Add a blocker. + * + * After a `blocker` has been added with `addBlocker`, if it is not + * removed with `removeBlocker`, this will, by design, eventually + * CAUSE A CRASH. + * + * Calling `addBlocker` once nsIAsyncShutdownBarrier::wait() has been + * called on the owning barrier returns an error. + * + * @param aBlocker The blocker to add. Once + * nsIAsyncShutdownBarrier::wait() has been called, it will not + * call its `aOnReady` callback until all blockers have been + * removed, each by a call to `removeBlocker`. + * @param aFileName The filename of the callsite, as given by `__FILE__`. + * @param aLineNumber The linenumber of the callsite, as given by `__LINE__`. + * @param aStack Information on the stack that lead to this call. Generally + * empty when called from C++. + * @throws If it's too late to add a blocker. + * @see isClosed. + */ + void addBlocker(in nsIAsyncShutdownBlocker aBlocker, + in AString aFileName, + in long aLineNumber, + in AString aStack); + + /** + * Remove a blocker. + * + * @param aBlocker A blocker previously added to this client through + * `addBlocker`. Noop if the blocker has never been added or has been + * removed already. + */ + void removeBlocker(in nsIAsyncShutdownBlocker aBlocker); + + /** + * The JS implementation of the client. + * + * It is strongly recommended that JS clients of this API use + * `jsclient` instead of the `nsIAsyncShutdownClient`. See + * AsyncShutdown.sys.mjs for more information on the JS version of + * this API. + */ + readonly attribute jsval jsclient; +}; + +/** + * Callback invoked once all blockers of a barrier have been removed. + */ +[scriptable, function, uuid(910c9309-1da0-4dd0-8bdb-a325a38c604e)] +interface nsIAsyncShutdownCompletionCallback: nsISupports { + /** + * The operation has been completed. + */ + void done(); +}; + +/** + * A stage of shutdown that supports blocker registration. + */ +[scriptable, uuid(50fa8a86-9c91-4256-8389-17d310adec90)] +interface nsIAsyncShutdownBarrier: nsISupports { + + /** + * The blocker registration capability. Most services may wish to + * publish this capability to let services that depend on it register + * blockers. + */ + readonly attribute nsIAsyncShutdownClient client; + + /** + * The state of all the blockers of the barrier. + * + * See the documentation of `nsIAsyncShutdownBlocker` for the + * format. + */ + readonly attribute nsIPropertyBag state; + + /** + * Wait for all blockers to complete. + * + * Method `aOnReady` will be called once all blockers have finished. + * The callback always receives NS_OK. + */ + void wait(in nsIAsyncShutdownCompletionCallback aOnReady); +}; + +/** + * A service that allows registering shutdown-time dependencies. + */ +[scriptable, uuid(db365c78-c860-4e64-9a63-25b73f89a016)] +interface nsIAsyncShutdownService: nsISupports { + /** + * Create a new barrier. + * + * By convention, the name should respect the following format: + * "MyModuleName: Doing something while it's time" + * e.g. + * "OS.File: Waiting for clients to flush before shutting down" + * + * This attribute is uploaded as part of crash reports. + */ + nsIAsyncShutdownBarrier makeBarrier(in AString aName); + + + // Barriers for global shutdown stages in the parent process. + + /** + * Barrier for notification profile-before-change. + */ + readonly attribute nsIAsyncShutdownClient profileBeforeChange; + + /** + * Barrier for notification profile-change-teardown. + */ + readonly attribute nsIAsyncShutdownClient profileChangeTeardown; + + /** + * Barrier for notification quit-application-granted. + */ + readonly attribute nsIAsyncShutdownClient quitApplicationGranted; + + /** + * Barrier for notification profile-before-change-telemetry. + */ + readonly attribute nsIAsyncShutdownClient sendTelemetry; + + + // Barriers for global shutdown stages in all processes. + + /** + * Barrier for notification web-workers-shutdown. + */ + readonly attribute nsIAsyncShutdownClient webWorkersShutdown; + + /** + * Barrier for notification xpcom-will-shutdown. + */ + readonly attribute nsIAsyncShutdownClient xpcomWillShutdown; + + // Don't add a barrier for content-child-shutdown because this + // makes it easier to cause shutdown hangs. + +}; + +%{C++ +#define NS_ASYNCSHUTDOWNSERVICE_CONTRACTID "@mozilla.org/async-shutdown-service;1" +%} |