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"
10 interface nsIThreadObserver
;
13 * The XPCOM thread object implements this interface, which allows a consumer
14 * to observe dispatch activity on the thread.
16 [scriptable
, uuid(b24c5af3
-43c2
-4d17
-be14
-94d6648a305f
)]
17 interface nsIThreadInternal
: nsIThread
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.
26 attribute nsIThreadObserver observer
;
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.
33 readonly attribute
unsigned long recursionDepth
;
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.
43 void addObserver
(in nsIThreadObserver observer
);
46 * Remove an observer added via the addObserver call. Once removed the
47 * observer will never be called again by the thread.
49 void removeObserver
(in nsIThreadObserver observer
);
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
62 [noscript
] nsIEventTarget pushEventQueue
();
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
71 [noscript
] void popEventQueue
(in nsIEventTarget aInnermostTarget
);
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:
81 * onDispatchedEvent(thread) {
82 * NativeQueue.signal();
84 * onProcessNextEvent(thread, mayWait, recursionDepth) {
85 * if (NativeQueue.hasNextEvent())
86 * NativeQueue.processNextEvent();
87 * while (mayWait && !thread.hasPendingEvent()) {
89 * NativeQueue.processNextEvent();
94 * NOTE: The implementation of this interface must be threadsafe.
96 * NOTE: It is valid to change the thread's observer during a call to an
99 * NOTE: Will be split into two interfaces soon: one for onProcessNextEvent and
100 * afterProcessNextEvent, then another that inherits the first and adds
103 [scriptable
, uuid(09b424c3
-26b0
-4128-9039-d66f85b02c63
)]
104 interface nsIThreadObserver
: nsISupports
107 * This method is called after an event has been dispatched to the thread.
108 * This method may be called from any thread.
111 * The thread where the event is being dispatched.
113 void onDispatchedEvent
(in nsIThreadInternal thread
);
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.
121 * The thread being asked to process another event.
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.
129 void onProcessNextEvent
(in nsIThreadInternal thread
, in boolean mayWait
,
130 in unsigned long recursionDepth
);
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.
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().
147 void afterProcessNextEvent
(in nsIThreadInternal thread
,
148 in unsigned long recursionDepth
,
149 in bool eventWasProcessed
);