1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/xpcom/threads/nsIThreadInternal.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,150 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* vim:set ts=2 sw=2 sts=2 et cindent: */
1.6 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#include "nsIThread.idl"
1.11 +
1.12 +interface nsIRunnable;
1.13 +interface nsIThreadObserver;
1.14 +
1.15 +/**
1.16 + * The XPCOM thread object implements this interface, which allows a consumer
1.17 + * to observe dispatch activity on the thread.
1.18 + */
1.19 +[scriptable, uuid(b24c5af3-43c2-4d17-be14-94d6648a305f)]
1.20 +interface nsIThreadInternal : nsIThread
1.21 +{
1.22 + /**
1.23 + * Get/set the current thread observer (may be null). This attribute may be
1.24 + * read from any thread, but must only be set on the thread corresponding to
1.25 + * this thread object. The observer will be released on the thread
1.26 + * corresponding to this thread object after all other events have been
1.27 + * processed during a call to Shutdown.
1.28 + */
1.29 + attribute nsIThreadObserver observer;
1.30 +
1.31 + /**
1.32 + * The current recursion depth, 0 when no events are running, 1 when a single
1.33 + * event is running, and higher when nested events are running. Must only be
1.34 + * called on the target thread.
1.35 + */
1.36 + readonly attribute unsigned long recursionDepth;
1.37 +
1.38 + /**
1.39 + * Add an observer that will *only* receive onProcessNextEvent,
1.40 + * beforeProcessNextEvent. and afterProcessNextEvent callbacks. Always called
1.41 + * on the target thread, and the implementation does not have to be
1.42 + * threadsafe. Order of callbacks is not guaranteed (i.e.
1.43 + * afterProcessNextEvent may be called first depending on whether or not the
1.44 + * observer is added in a nested loop). Holds a strong ref.
1.45 + */
1.46 + void addObserver(in nsIThreadObserver observer);
1.47 +
1.48 + /**
1.49 + * Remove an observer added via the addObserver call. Once removed the
1.50 + * observer will never be called again by the thread.
1.51 + */
1.52 + void removeObserver(in nsIThreadObserver observer);
1.53 +
1.54 + /**
1.55 + * This method causes any events currently enqueued on the thread to be
1.56 + * suppressed until PopEventQueue is called, and any event dispatched to this
1.57 + * thread's nsIEventTarget will queue as well. Calls to PushEventQueue may be
1.58 + * nested and must each be paired with a call to PopEventQueue in order to
1.59 + * restore the original state of the thread. The returned nsIEventTarget may
1.60 + * be used to push events onto the nested queue. Dispatching will be disabled
1.61 + * once the event queue is popped. The thread will only ever process pending
1.62 + * events for the innermost event queue. Must only be called on the target
1.63 + * thread.
1.64 + */
1.65 + [noscript] nsIEventTarget pushEventQueue();
1.66 +
1.67 + /**
1.68 + * Revert a call to PushEventQueue. When an event queue is popped, any events
1.69 + * remaining in the queue are appended to the elder queue. This also causes
1.70 + * the nsIEventTarget returned from PushEventQueue to stop dispatching events.
1.71 + * Must only be called on the target thread, and with the innermost event
1.72 + * queue.
1.73 + */
1.74 + [noscript] void popEventQueue(in nsIEventTarget aInnermostTarget);
1.75 +};
1.76 +
1.77 +/**
1.78 + * This interface provides the observer with hooks to implement a layered
1.79 + * event queue. For example, it is possible to overlay processing events
1.80 + * for a GUI toolkit on top of the events for a thread:
1.81 + *
1.82 + * var NativeQueue;
1.83 + * Observer = {
1.84 + * onDispatchedEvent(thread) {
1.85 + * NativeQueue.signal();
1.86 + * }
1.87 + * onProcessNextEvent(thread, mayWait, recursionDepth) {
1.88 + * if (NativeQueue.hasNextEvent())
1.89 + * NativeQueue.processNextEvent();
1.90 + * while (mayWait && !thread.hasPendingEvent()) {
1.91 + * NativeQueue.wait();
1.92 + * NativeQueue.processNextEvent();
1.93 + * }
1.94 + * }
1.95 + * };
1.96 + *
1.97 + * NOTE: The implementation of this interface must be threadsafe.
1.98 + *
1.99 + * NOTE: It is valid to change the thread's observer during a call to an
1.100 + * observer method.
1.101 + *
1.102 + * NOTE: Will be split into two interfaces soon: one for onProcessNextEvent and
1.103 + * afterProcessNextEvent, then another that inherits the first and adds
1.104 + * onDispatchedEvent.
1.105 + */
1.106 +[scriptable, uuid(09b424c3-26b0-4128-9039-d66f85b02c63)]
1.107 +interface nsIThreadObserver : nsISupports
1.108 +{
1.109 + /**
1.110 + * This method is called after an event has been dispatched to the thread.
1.111 + * This method may be called from any thread.
1.112 + *
1.113 + * @param thread
1.114 + * The thread where the event is being dispatched.
1.115 + */
1.116 + void onDispatchedEvent(in nsIThreadInternal thread);
1.117 +
1.118 + /**
1.119 + * This method is called when nsIThread::ProcessNextEvent is called. It does
1.120 + * not guarantee that an event is actually going to be processed. This method
1.121 + * is only called on the target thread.
1.122 + *
1.123 + * @param thread
1.124 + * The thread being asked to process another event.
1.125 + * @param mayWait
1.126 + * Indicates whether or not the method is allowed to block the calling
1.127 + * thread. For example, this parameter is false during thread shutdown.
1.128 + * @param recursionDepth
1.129 + * Indicates the number of calls to ProcessNextEvent on the call stack in
1.130 + * addition to the current call.
1.131 + */
1.132 + void onProcessNextEvent(in nsIThreadInternal thread, in boolean mayWait,
1.133 + in unsigned long recursionDepth);
1.134 +
1.135 + /**
1.136 + * This method is called (from nsIThread::ProcessNextEvent) after an event
1.137 + * is processed. It does not guarantee that an event was actually processed
1.138 + * (depends on the value of |eventWasProcessed|. This method is only called
1.139 + * on the target thread.
1.140 + *
1.141 + * @param thread
1.142 + * The thread that processed another event.
1.143 + * @param recursionDepth
1.144 + * Indicates the number of calls to ProcessNextEvent on the call stack in
1.145 + * addition to the current call.
1.146 + * @param eventWasProcessed
1.147 + * Indicates whether an event was actually processed. May be false if the
1.148 + * |mayWait| flag was false when calling nsIThread::ProcessNextEvent().
1.149 + */
1.150 + void afterProcessNextEvent(in nsIThreadInternal thread,
1.151 + in unsigned long recursionDepth,
1.152 + in bool eventWasProcessed);
1.153 +};
