• file
• revisions
• annotate
• diff
• comparison
• raw

xpcom/threads/nsIThreadInternal.idl@b8a032363ba2 (annotated)

xpcom/threads/nsIThreadInternal.idl

Thu, 22 Jan 2015 13:21:57 +0100

author

Michael Schloh von Bennewitz <michael@schloh.com>

date

Thu, 22 Jan 2015 13:21:57 +0100

branch

TOR_BUG_9701

changeset 15

b8a032363ba2

permissions

-rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

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