Bug 1695754 - Add developer documentation for the new --backgroundtask mode. r=bytesized DONTBUILD
authorNick Alexander <nalexander@mozilla.com>
Tue, 02 Mar 2021 21:44:27 +0000
changeset 569399 f39de5f81b7f137a55fd23ba2927808c255b6de7
parent 569398 dbdb08503b9b3941f13796a97a584c2f20fc72f3
child 569400 24a716464a6f6f4c84ee0d6aa28e917b358604ef
push id38256
push userbtara@mozilla.com
push dateWed, 03 Mar 2021 04:16:49 +0000
treeherdermozilla-central@c45b1e6bcd01 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersbytesized
bugs1695754
milestone88.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1695754 - Add developer documentation for the new --backgroundtask mode. r=bytesized DONTBUILD Differential Revision: https://phabricator.services.mozilla.com/D106840
toolkit/components/backgroundtasks/docs/index.md
toolkit/components/backgroundtasks/moz.build
toolkit/docs/index.rst
new file mode 100644
--- /dev/null
+++ b/toolkit/components/backgroundtasks/docs/index.md
@@ -0,0 +1,67 @@
+# Background Task Mode
+
+Gecko supports running privileged JavaScript in a special headless "background task" mode.  Background task mode is intended to be used for periodic maintenance tasks.  The first consumer will be checking for updates, even when Firefox is not running.
+
+Support for background task mode is gated on the build flag `MOZ_BACKGROUNDTASKS`.
+
+## Adding a new background task
+
+Background tasks are invoked with `--backgroundtask TASKNAME`.  Tasks must be packaged at build time; the background task runtime looks for regular JSM modules in the following locations (in order):
+
+1. (App-specific) `resource:///modules/backgroundtasks/BackgroundTask_TASKNAME.jsm`
+2. (Toolkit/general) `resource://gre/modules//backgroundtasks/BackgroundTask_TASKNAME.jsm`
+
+To add a new background task, add to your `moz.build` file a stanza like:
+
+```python
+EXTRA_JS_MODULES.backgroundtasks += [
+    "BackgroundTask_TASKNAME.jsm",
+]
+```
+
+## Implementing a background task
+
+In `BackgroundTask_TASKNAME.jsm`, define a function `runBackgroundTask` that returns a `Promise`.  `runBackgroundTask` will be awaited and the integer value it resolves to will be used as the exit code of the `--backgroundtask TASKNAME` invocation.  Optionally, `runBackgroundTask` can take an [`nsICommandLine` instance](https://searchfox.org/mozilla-central/source/toolkit/components/commandlines/nsICommandLine.idl) as a parameter.  For example:
+
+```javascript
+async function runBackgroundTask(commandLine) {
+    return Number.parseInt(commandLine.getArgument(0), 10);
+}
+```
+
+When invoked like `--backgroundtask TASKNAME EXITCODE`, this task will simply complete with the exit code given on the command line.
+
+## Special exit codes
+
+The exit codes 2 and 3 have special meaning:
+
+* Exit code 2 means the background task with the given `TASKNAME` was not found or could not be loaded.
+* Exit code 3 means the background task invocation rejected with an exception.
+
+See [`BackgroundTasksManager.jsm`](https://searchfox.org/mozilla-central/source/toolkit/components/backgroundtasks/BackgroundTasksManager.jsm) for details.
+
+## Test-only Background Tasks
+
+There is special support for test-only background tasks.  Add to your `moz.build` file a stanza like:
+
+```python
+TESTING_JS_MODULES.backgroundtasks += [
+    "BackgroundTask_TESTONLYTASKNAME.jsm",
+]
+```
+
+For more details, see [`XPCSHELL_TESTING_MODULES_URI`](https://searchfox.org/mozilla-central/search?q=XPCSHELL_TESTING_MODULES_URI).
+
+## The background task mode runtime environment
+
+### Background tasks run in temporary profiles
+
+Background tasks are intended for periodic maintenance tasks, especially global/per-installation maintenance tasks.  To allow background tasks to run at the same time as regular, headed Firefox browsing sessions, they run with a temporary profile.  This temporary profile is deleted when the background task main process exits.  Every background task applies the preferences in [`backgroundtasks/defaults/backgroundtasks.js`](https://searchfox.org/mozilla-central/source/toolkit/components/backgroundtasks/defaults/backgroundtasks.js), but any additional preference configuration must be handled by the individual task.  Over time, we anticipate a small library of background task functionality to grow to make it easier to lock and read specific prefs from the default browsing profile, to declare per-installation prefs, etc.
+
+### Background tasks limit the XPCOM instance graph by default
+
+The technical mechanism that keeps background tasks "lightweight" is very simple.  XPCOM declares a number of observer notifications for loosely coupling components via the observer service.   Some of those observer notifications are declared as category notifications which allow consumers to register themselves in static components.conf registration files (or in now deprecated chrome.manifest files).  In background task mode, category notifications are not registered by default.
+
+For Firefox in particular, this means that [`BrowserContentHandler.jsm`](https://searchfox.org/mozilla-central/source/browser/components/BrowserContentHandler.jsm) is not registered as a command-line-handler.  This means that [`BrowserGlue.jsm`](https://searchfox.org/mozilla-central/source/browser/components/BrowserGlue.jsm) is not loaded, and this short circuits regular headed browsing startup.
+
+See the [documentation for defining static components](https://firefox-source-docs.mozilla.org/build/buildsystem/defining-xpcom-components.html) for how to change this default behaviour, and [Bug 1675848](https://bugzilla.mozilla.org/show_bug.cgi?id=1675848) for details of the implementation.
--- a/toolkit/components/backgroundtasks/moz.build
+++ b/toolkit/components/backgroundtasks/moz.build
@@ -1,16 +1,21 @@
 # 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/.
 
 with Files("**"):
     # TODO: House this somewhere more specific?
     BUG_COMPONENT = ("Toolkit", "Startup and Profile System")
 
+SPHINX_TREES["/toolkit/components/backgroundtasks"] = "docs"
+
+with Files("docs/**"):
+    SCHEDULES.exclusive = ["docs"]
+
 FINAL_LIBRARY = "xul"
 
 UNIFIED_SOURCES += [
     "BackgroundTasks.cpp",
 ]
 
 EXPORTS.mozilla += [
     "BackgroundTasks.h",
--- a/toolkit/docs/index.rst
+++ b/toolkit/docs/index.rst
@@ -3,16 +3,17 @@ Toolkit
 =======
 
 This is the nascent documentation of the Toolkit code that is shared across Firefox, Firefox for Android and other applications.
 
 .. toctree::
    :maxdepth: 1
 
    mozapps/extensions/addon-manager/index
+   components/backgroundtasks/index
    crash-reporting/index
    components/crashes/crash-manager/index
    crashreporter/crashreporter/index
    components/featuregates/featuregates/index
    search/index
    components/normandy/normandy/index
    components/nimbus/docs/index
    components/messaging-system/docs/index