mozilla

Compare Revisions

AsyncShutdown.jsm

Change Revisions

Revision 523163:

Revision 523163 by Yoric on

Revision 523191:

Revision 523191 by Yoric on

Title:
AsyncShutdown.jsm
AsyncShutdown.jsm
Slug:
Mozilla/JavaScript_code_modules/AsyncShutdown.jsm
Mozilla/JavaScript_code_modules/AsyncShutdown.jsm
Content:

Revision 523163
Revision 523191
n13    <h3>n13    <h2 id="Example">
n15    </h3>n15    </h2>
n34      &nbsp;In this example, function |condition| will be called n34      In this example,&nbsp; at some point during phase <code>pro
>at some point during phase profileBeforeChange and phase profileB>fileBeforeChange</code>, function <code>condition</code> will be 
>eforeChange itself is guaranteed to not terminate until |promise|>called. Phase <code>profileBeforeChange</code> is guaranteed to n
> is either resolved or rejected. If, for some reason, promise is >ot terminate until <code>promise</code> is either resolved or rej
>never resolved/rejected, Firefox will crash during shutdown, to a>ected. If, for some reason, <code>promise</code> is never resolve
>void consuming battery, blocking operating system shutdown or pre>d/rejected, Firefox will crash during shutdown, to avoid consumin
>venting the user from restarting Firefox. In this case, a crash r>g battery, blocking operating system shutdown or preventing the u
>eport is produced, with information on all the shutdown blockers >ser from restarting Firefox. In this case, a crash report is prod
>that have not been resolved, and all the additional debug informa>uced, with information on all the shutdown blockers that have not
>tion returned by calls to info().<br>> been resolved, and all the additional debug information returned
 > by calls to <code>info()</code>.<br>
tt36    </p>
37    <h2>
38      Instances of Phase
39    </h2>
40    <p>
41      Note that you cannot create an instance of Phase yourself. 
 >See <a href="#Attributes">Attributes</a> for the instances of Pha
 >se. If you need a new Phase added to AsyncShutdown, please <a hre
 >f="https://bugzilla.mozilla.org/enter_bug.cgi?product=Toolkit&amp
 >;component=Async%20Tooling">file a bug</a>.
42    </p>
43    <h3>
44      Methods overview
45    </h3>
46    <table class="standard-table">
47      <tbody>
48        <tr>
49          <td>
50            <a href="#addBlocker">addBlocker</a>(string name, fun
 >ction|promise condition, optional function info)
51          </td>
52        </tr>
53      </tbody>
54    </table>
55    <h3>
56      Methods
57    </h3>
58    <h4>
59      <a name="addBlocker" id="addBlocker"></a>addBlocker ()
60    </h4>
61    <p>
62      Register a blocker for the completion of a phase.
63    </p>
64    <pre class="brush: js">
65addBlocker(
66  in string name,
67  in function|promise|* condition,
68  optional in function info
69)
70 
71</pre>
72    <h5>
73      Arguments
74    </h5>
75    <dl>
76      <dt>
77        name
78      </dt>
79      <dd>
80        The human-readable name of the blocker. Used for debuggin
 >g/error reporting. Please make sure that the name respects the fo
 >llowing model: "Some Service: some action in progress" - for inst
 >ance "OS.File: flushing all pending I/O".
81      </dd>
82      <dt>
83        condition
84      </dt>
85      <dd>
86        A condition blocking the completion of the phase. General
 >ly, this is a function returning a promise. This function is eval
 >uated during the phase and the phase is guaranteed to not termina
 >te until the resulting promise is either resolved or rejected. If
 > <code>condition</code> is not a function but another value <code
 >>v</code>, it behaves as if it were a function returning <code>v<
 >/code>.
87      </dd>
88      <dt>
89        info
90      </dt>
91      <dd>
92        Optionally, a function returning information about the cu
 >rrent state of the blocker as an object. Used for providing more 
 >details when logging errors or crashing.
93      </dd>
94    </dl>
95    <h5>
96      <br>
97      Examples
98    </h5>
99    <pre class="brush: js">
100AsyncShutdown.profileBeforeChange.addBlocker("Module: just a prom
 >ise",
101     promise); // profileBeforeChange will not complete until
102               // promise is resolved or rejected
103 
104AsyncShutdown.profileBeforeChange.addBlocker("Module: a callback"
 >,
105    function condition() {
106      // ...
107      // Execute this code during profileBeforeChange
108      return promise;
109      // profileBeforeChange will not complete until promise
110      // is resolved or rejected
111});
112 
113AsyncShutdown.profileBeforeChange.addBlocker("Module: trivial cal
 >lback",
114    function condition() {
115      // ...
116      // Execute this code during profileBeforeChange
117      // No specific guarantee about completion of profileBeforeC
 >hange
118});
119</pre>
120    <div class="warning">
121      <p>
122        If the promise returned by <code>condition</code> is not 
 >resolved/rejected within <strong>one minute</strong>, the process
 > will crash to avoid blocking system shutdown, preventing the use
 >r from restarting Firefox or burning through battery. This is by 
 >design. It is the caller's responsibility to ensure that the prom
 >ise is eventually resolved/rejected.
123      </p>
124    </div>
125    <h2>
126      <a name="Attributes" id="Attributes"></a>Attributes
127    </h2>
128    <h3>
129      profileBeforeChange
130    </h3>
131    <p>
132      The profile is about to be unmounted. This phase represents
 > the last chance to write data to the profile directory.
133    </p>
134    <h3>
135      sendTelemetry
136    </h3>
137    <p>
138      Telemetry is being sent. This phase represents the last cha
 >nce for Telemetry to write data.
139    </p>
140    <h3>
141      webWorkersShutdown
142    </h3>
143    <p>
144      JavaScript threads are about to be killed. This phase repre
 >sents the last chance to communicate with a JavaScript worker, in
 > particular with OS.File.

Back to History