summaryrefslogtreecommitdiffstats
path: root/toolkit/components/asyncshutdown/nsIAsyncShutdown.idl
diff options
context:
space:
mode:
Diffstat (limited to 'toolkit/components/asyncshutdown/nsIAsyncShutdown.idl')
-rw-r--r--toolkit/components/asyncshutdown/nsIAsyncShutdown.idl229
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"
+%}