xpcom/threads/nsIThreadInternal.idl@6474c204b198
xpcom/threads/nsIThreadInternal.idl
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* vim:set ts=2 sw=2 sts=2 et cindent: */
3 /* This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
7 #include "nsIThread.idl"
9 interface nsIRunnable;
10 interface nsIThreadObserver;
12 /**
13 * The XPCOM thread object implements this interface, which allows a consumer
14 * to observe dispatch activity on the thread.
15 */
16 [scriptable, uuid(b24c5af3-43c2-4d17-be14-94d6648a305f)]
17 interface nsIThreadInternal : nsIThread
18 {
19 /**
20 * Get/set the current thread observer (may be null). This attribute may be
21 * read from any thread, but must only be set on the thread corresponding to
22 * this thread object. The observer will be released on the thread
23 * corresponding to this thread object after all other events have been
24 * processed during a call to Shutdown.
25 */
26 attribute nsIThreadObserver observer;
28 /**
29 * The current recursion depth, 0 when no events are running, 1 when a single
30 * event is running, and higher when nested events are running. Must only be
31 * called on the target thread.
32 */
33 readonly attribute unsigned long recursionDepth;
35 /**
36 * Add an observer that will *only* receive onProcessNextEvent,
37 * beforeProcessNextEvent. and afterProcessNextEvent callbacks. Always called
38 * on the target thread, and the implementation does not have to be
39 * threadsafe. Order of callbacks is not guaranteed (i.e.
40 * afterProcessNextEvent may be called first depending on whether or not the
41 * observer is added in a nested loop). Holds a strong ref.
42 */
43 void addObserver(in nsIThreadObserver observer);
45 /**
46 * Remove an observer added via the addObserver call. Once removed the
47 * observer will never be called again by the thread.
48 */
49 void removeObserver(in nsIThreadObserver observer);
51 /**
52 * This method causes any events currently enqueued on the thread to be
53 * suppressed until PopEventQueue is called, and any event dispatched to this
54 * thread's nsIEventTarget will queue as well. Calls to PushEventQueue may be
55 * nested and must each be paired with a call to PopEventQueue in order to
56 * restore the original state of the thread. The returned nsIEventTarget may
57 * be used to push events onto the nested queue. Dispatching will be disabled
58 * once the event queue is popped. The thread will only ever process pending
59 * events for the innermost event queue. Must only be called on the target
60 * thread.
61 */
62 [noscript] nsIEventTarget pushEventQueue();
64 /**
65 * Revert a call to PushEventQueue. When an event queue is popped, any events
66 * remaining in the queue are appended to the elder queue. This also causes
67 * the nsIEventTarget returned from PushEventQueue to stop dispatching events.
68 * Must only be called on the target thread, and with the innermost event
69 * queue.
70 */
71 [noscript] void popEventQueue(in nsIEventTarget aInnermostTarget);
72 };
74 /**
75 * This interface provides the observer with hooks to implement a layered
76 * event queue. For example, it is possible to overlay processing events
77 * for a GUI toolkit on top of the events for a thread:
78 *
79 * var NativeQueue;
80 * Observer = {
81 * onDispatchedEvent(thread) {
82 * NativeQueue.signal();
83 * }
84 * onProcessNextEvent(thread, mayWait, recursionDepth) {
85 * if (NativeQueue.hasNextEvent())
86 * NativeQueue.processNextEvent();
87 * while (mayWait && !thread.hasPendingEvent()) {
88 * NativeQueue.wait();
89 * NativeQueue.processNextEvent();
90 * }
91 * }
92 * };
93 *
94 * NOTE: The implementation of this interface must be threadsafe.
95 *
96 * NOTE: It is valid to change the thread's observer during a call to an
97 * observer method.
98 *
99 * NOTE: Will be split into two interfaces soon: one for onProcessNextEvent and
100 * afterProcessNextEvent, then another that inherits the first and adds
101 * onDispatchedEvent.
102 */
103 [scriptable, uuid(09b424c3-26b0-4128-9039-d66f85b02c63)]
104 interface nsIThreadObserver : nsISupports
105 {
106 /**
107 * This method is called after an event has been dispatched to the thread.
108 * This method may be called from any thread.
109 *
110 * @param thread
111 * The thread where the event is being dispatched.
112 */
113 void onDispatchedEvent(in nsIThreadInternal thread);
115 /**
116 * This method is called when nsIThread::ProcessNextEvent is called. It does
117 * not guarantee that an event is actually going to be processed. This method
118 * is only called on the target thread.
119 *
120 * @param thread
121 * The thread being asked to process another event.
122 * @param mayWait
123 * Indicates whether or not the method is allowed to block the calling
124 * thread. For example, this parameter is false during thread shutdown.
125 * @param recursionDepth
126 * Indicates the number of calls to ProcessNextEvent on the call stack in
127 * addition to the current call.
128 */
129 void onProcessNextEvent(in nsIThreadInternal thread, in boolean mayWait,
130 in unsigned long recursionDepth);
132 /**
133 * This method is called (from nsIThread::ProcessNextEvent) after an event
134 * is processed. It does not guarantee that an event was actually processed
135 * (depends on the value of |eventWasProcessed|. This method is only called
136 * on the target thread.
137 *
138 * @param thread
139 * The thread that processed another event.
140 * @param recursionDepth
141 * Indicates the number of calls to ProcessNextEvent on the call stack in
142 * addition to the current call.
143 * @param eventWasProcessed
144 * Indicates whether an event was actually processed. May be false if the
145 * |mayWait| flag was false when calling nsIThread::ProcessNextEvent().
146 */
147 void afterProcessNextEvent(in nsIThreadInternal thread,
148 in unsigned long recursionDepth,
149 in bool eventWasProcessed);
150 };
