||This module implements the content side of session restoration. The chrome
side is handled by SessionStore.jsm. The functions in this module are called
by content-sessionStore.js based on messages received from SessionStore.jsm
(or, in one case, based on a "load" event). Each tab has its own
ContentRestore instance, constructed by content-sessionStore.js.
In a typical restore, content-sessionStore.js will call the following based
on messages and events it receives:
restoreHistory(tabData, loadArguments, callbacks)
Restores the tab's history and session cookies.
Starts loading the data for the current page to restore.
Restore form and scroll data.
When the page has been loaded from the network, we call finishCallback. It
should send a message to SessionStore.jsm, which may cause other tabs to be
When the page has finished loading, a "load" event will trigger in
content-sessionStore.js, which will call restoreDocument. At that point,
form data is restored and the restore is complete.
At any time, SessionStore.jsm can cancel the ongoing restore by sending a
reset message, which causes resetRestore to be called. At that point it's
legal to begin another restore.
||Listens for state change notifcations from webProgress and notifies each
registered observer for either the start of a page load, or its completion.
||Module that contains global session data.
||Builds up a document fragment of UI items for the recently closed tabs.
The window that the tabs were closed in.
The tag name that will be used when creating the UI items.
@param aPrefixRestoreAll (defaults to false)
Whether the 'restore all tabs' item is suffixed or prefixed to the list.
If suffixed (the default) a separator will be inserted before it.
@param aRestoreAllLabel (defaults to "menuRestoreAllTabs.label")
Which localizable string to use for the 'restore all tabs' item.
@returns A document fragment with UI items for each recently closed tab.
||This module keeps track of SessionStore's current run state. We will
always start out at STATE_STOPPED. After the session was read from disk and
the initial browser window has loaded we switch to STATE_RUNNING. On the
first notice that a browser shutdown was granted we switch to STATE_QUITTING.
||The external API implemented by the SessionCookies module.
||Implementation of all the disk I/O required by the session store.
This is a private API, meant to be used only by the session store.
It will change. Do not use it for any other purpose.
Note that this module implicitly depends on one of two things:
1. either the asynchronous file I/O system enqueues its requests
and never attempts to simultaneously execute two I/O requests on
the files used by this module from two distinct threads; or
2. the clients of this API are well-behaved and do not place
concurrent requests to the files used by this module.
Otherwise, we could encounter bugs, especially under Windows,
e.g. if a request attempts to write sessionstore.js while
another attempts to copy that file.
This implementation uses OS.File, which guarantees property 1.
||Convert the original session restore state into a minimal state. It will
- open windows
- with tabs
- with history entries with only title, url, triggeringPrincipal
- with pinned state
- with tab group info (hidden + group id)
- with selected tab info
- with selected window info
The complete state is then wrapped into the "about:welcomeback" page as
form field info to be restored when restoring the state.
||Minimal interval between two save operations (in milliseconds).
To save system resources, we generally do not save changes immediately when
a change is detected. Rather, we wait a little to see if this change is
followed by other changes, in which case only the last write is necessary.
This delay is defined by "browser.sessionstore.interval".
Furthermore, when the user is not actively using the computer, webpages
may still perform changes that require (re)writing to sessionstore, e.g.
updating Session Cookies or DOM Session Storage, or refreshing, etc. We
expect that these changes are much less critical to the user and do not
need to be saved as often. In such cases, we increase the delay to
When the user returns to the computer, if a save is pending, we reschedule
it to happen soon, with "browser.sessionstore.interval".
||Session Storage and Restoration
This service reads user's session file at startup, and makes a determination
as to whether the session should be restored. It will restore the session
under the circumstances described below. If the auto-start Private Browsing
mode is active, however, the session is never restored.
The CrashMonitor is used to check if the final session state was successfully
written at shutdown of the last session. If we did not reach
'sessionstore-final-state-write-complete', then it's assumed that the browser
has previously crashed and we should restore the session.
In the event that a restart is required due to application update or extension
installation, set the browser.sessionstore.resume_session_once pref to true,
and the session will be restored the next time the browser starts.
This service will always resume the session if the integer pref
browser.startup.page is set to 3.
||Interface to a dedicated thread handling I/O
||Once we have finished restoring initial tabs, we broadcast on this topic.
||Module that contains tab state collection methods.
||A cache for tabs data.
This cache implements a weak map from tabs (as XUL elements)
to tab data (as objects).
Note that we should never cache private data, as:
- that data is used very seldom by SessionStore;
- caching private data in addition to public data is memory consuming.
||A module that enables async flushes. Updates from frame scripts are
throttled to be sent only once per second. If an action wants a tab's latest
state without waiting for a second then it can request an async flush and
wait until the frame scripts reported back. At this point the parent has the
latest data and the action can continue.