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 [builtinclass
, scriptable
, rust_sync
, uuid(a3a72e5f
-71d9
-4add
-8f30
-59a78fb6d5eb
)]
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 * Add an observer that will *only* receive onProcessNextEvent,
30 * beforeProcessNextEvent. and afterProcessNextEvent callbacks. Always called
31 * on the target thread, and the implementation does not have to be
32 * threadsafe. Order of callbacks is not guaranteed (i.e.
33 * afterProcessNextEvent may be called first depending on whether or not the
34 * observer is added in a nested loop). Holds a strong ref.
36 void addObserver
(in nsIThreadObserver observer
);
39 * Remove an observer added via the addObserver call. Once removed the
40 * observer will never be called again by the thread.
42 void removeObserver
(in nsIThreadObserver observer
);
46 * This interface provides the observer with hooks to implement a layered
47 * event queue. For example, it is possible to overlay processing events
48 * for a GUI toolkit on top of the events for a thread:
52 * onDispatchedEvent() {
53 * NativeQueue.signal();
55 * onProcessNextEvent(thread, mayWait) {
56 * if (NativeQueue.hasNextEvent())
57 * NativeQueue.processNextEvent();
58 * while (mayWait && !thread.hasPendingEvent()) {
60 * NativeQueue.processNextEvent();
65 * NOTE: The implementation of this interface must be threadsafe.
67 * NOTE: It is valid to change the thread's observer during a call to an
70 * NOTE: Will be split into two interfaces soon: one for onProcessNextEvent and
71 * afterProcessNextEvent, then another that inherits the first and adds
74 [uuid(cc8da053
-1776-44c2
-9199-b5a629d0a19d
)]
75 interface nsIThreadObserver
: nsISupports
78 * This method is called after an event has been dispatched to the thread.
79 * This method may be called from any thread.
81 void onDispatchedEvent
();
84 * This method is called when nsIThread::ProcessNextEvent is called. It does
85 * not guarantee that an event is actually going to be processed. This method
86 * is only called on the target thread.
89 * The thread being asked to process another event.
91 * Indicates whether or not the method is allowed to block the calling
92 * thread. For example, this parameter is false during thread shutdown.
94 void onProcessNextEvent
(in nsIThreadInternal thread
, in boolean mayWait
);
97 * This method is called (from nsIThread::ProcessNextEvent) after an event
98 * is processed. It does not guarantee that an event was actually processed
99 * (depends on the value of |eventWasProcessed|. This method is only called
100 * on the target thread. DO NOT EVER RUN SCRIPT FROM THIS CALLBACK!!!
103 * The thread that processed another event.
104 * @param eventWasProcessed
105 * Indicates whether an event was actually processed. May be false if the
106 * |mayWait| flag was false when calling nsIThread::ProcessNextEvent().
108 void afterProcessNextEvent
(in nsIThreadInternal thread
,
109 in bool eventWasProcessed
);