MozillaWiki - User contributions [en]

Class:nsTDeque

2006-06-18T19:06:38Z

Darin:

template <class T>
class nsTDeque {
public:
/**
* @constructor
* @param objectsPerPage
* Optional parameter that specifies the number of objects per page
* in the deque.
*/
explicit nsTDeque(PRUint32 objectsPerPage = 32);
 
/**
* @destructor
*/
~nsTDeque();
 
/**
* Clear all elements from the deque.
*/
void Clear();
 
/**
* @returns
* PR_TRUE if the deque contains no elements and PR_FALSE otherwise.
*/
PRBool IsEmpty();
 
/**
* Adds a new element to the front of the deque.
* @param obj
* The object to be added.
*/
void PushFront(const T& obj);
 
/**
* Adds a new element using T's default constructor to the front of the
* deque.
* @returns
* The address of the newly added element or null if the object
* could not be allocated.
*/
T* PushFront();
 
/**
* Adds a new element to the back of the deque.
* @param obj
* The object to be added.
*/
void PushBack(const T& obj);
 
/**
* Adds a new element using T's default constructor to the back of the
* deque.
* @returns
* The address of the newly added element or null if the object
* could not be allocated.
*/
T* PushBack();
 
/**
* @returns
* A const reference to the element at the front of the deque.
* It is an error to call this method on an empty deque.
*/
const T& Front() const;
 
/**
* @returns
* A reference to the element at the front of the deque.
* It is an error to call this method on an empty deque.
*/
T& Front();
 
/**
* @returns
* A const reference to the element at the back of the deque.
* It is an error to call this method on an empty deque.
*/
const T& Back() const;
 
/**
* @returns
* A reference to the element at the back of the deque.
* It is an error to call this method on an empty deque.
*/
T& Back();
 
/**
* Removes the element at the front of the deque. This method
* has no effect if the deque is empty.
*/
void PopFront();
 
/**
* Removes the element at the back of the deque. This method
* has no effect if the deque is empty.
*/
void PopBack();
};

Class:nsTDeque

2006-06-15T17:51:08Z

Darin:

template <class T>
class nsTDeque {
public:
/**
* @constructor
* @param objectsPerPage
* Optional parameter that specifies the number of objects per page
* in the deque.
*/
explicit nsTDeque(PRUint32 objectsPerPage = 32);
 
/**
* @destructor
*/
~nsTDeque();
 
/**
* Clear all elements from the deque.
*/
void Clear();
 
/**
* @returns
* The number of elements in the deque.
*/
PRUint32 Length(); // or Count() ?
 
/**
* @returns
* PR_TRUE if the deque contains no elements and PR_FALSE otherwise.
*/
PRBool IsEmpty();
 
/**
* Adds a new element to the front of the deque.
* @param obj
* The object to be added.
*/
void PushFront(const T& obj);
 
/**
* Adds a new element using T's default constructor to the front of the
* deque.
* @returns
* The address of the newly added element or null if the object
* could not be allocated.
*/
T* PushFront();
 
/**
* Adds a new element to the back of the deque.
* @param obj
* The object to be added.
*/
void PushBack(const T& obj);
 
/**
* Adds a new element using T's default constructor to the back of the
* deque.
* @returns
* The address of the newly added element or null if the object
* could not be allocated.
*/
T* PushBack();
 
/**
* @returns
* A const reference to the element at the front of the deque.
* It is an error to call this method on an empty deque.
*/
const T& Front() const;
 
/**
* @returns
* A reference to the element at the front of the deque.
* It is an error to call this method on an empty deque.
*/
T& Front();
 
/**
* @returns
* A const reference to the element at the back of the deque.
* It is an error to call this method on an empty deque.
*/
const T& Back() const;
 
/**
* @returns
* A reference to the element at the back of the deque.
* It is an error to call this method on an empty deque.
*/
T& Back();
 
/**
* Removes the element at the front of the deque. This method
* has no effect if the deque is empty.
*/
void PopFront();
 
/**
* Removes the element at the back of the deque. This method
* has no effect if the deque is empty.
*/
void PopBack();
};

Class:nsTDeque

2006-06-15T15:34:10Z

Darin:

Necko:UnitTests

2006-06-05T20:17:44Z

Darin:

= Overview =

Unit tests for the networking library live under [http://lxr.mozilla.org/mozilla/source/netwerk/test/unit/ netwerk/test/unit/]. The test files are javascript files that are executed using xpcshell (via the [http://lxr.mozilla.org/mozilla/source/tools/test-harness/xpcshell-simple/ xpcshell test harness]).

Unit tests are files named with the prefix <code>'''test_'''</code>. Code may be shared across unit tests by adding it to a file named with the prefix <code>'''head_'''</code>.

= Basics =

Each test file must define a function named <code>'''run_test'''</code> that will be called to execute the test. Any exception thrown from this function causes the test to fail. If the function runs to completely without throwing an exception then the test succeeds.

However, for tests that require asynchronous operations, completion of the test can be deferred by calling <code>'''do_test_pending'''</code>, which must be paired with a call to <code>'''do_test_finished'''</code> when the asynchronous operation completes.

When the test is run, a log file is generated. That log file will contain the output from the test, plus any error messages with call stacks.

= Functions =

; <code>'''do_throw(messageText)'''</code>
: Call this function to report an error and exit the test. The argument is a string that will be reported in the test's log file.

; <code>'''do_check_eq(a, b)'''</code>
: Call this function to assert that two objects are equal. If not equal, an exception is logged and the test case is halted.

; <code>'''do_check_neq(a, b)'''</code>
: Call this function to assert that two objects are not equal. If equal, an exception is logged and the test case is halted.

; <code>'''do_timeout(delay, expr)'''</code>
: Call this function to schedule a timeout. The given expression will be evaluated after the specified delay (in milliseconds).

; <code>'''do_test_pending()'''</code>
: Delay exit of the test until <code>'''do_test_finished()'''</code> is called. <code>'''do_test_pending()'''</code> may be called multiple times, and <code>'''do_test_finished()'''</code> must be paired with each before the unit test will exit.

; <code>'''do_test_finished()'''</code>
: Call this function to inform the test framework that an asychronous operation has completed. If all asynchronous operations have completed, then the unit test will exit.

Firefox3/Gecko Feature List

2006-06-02T21:47:40Z

Darin: /* Gecko 1.9 Feature List */

__NOTOC__

= Gecko 1.9 Feature List =

This page is intended to collect the set of features that either have gone in to Gecko 1.9 since Gecko 1.8 was branched, features that people are working on, or features that people intend to work on for Gecko 1.9. It will eventually be migrated into the [[Firefox3/Gecko_Requirements|Gecko 1.9 Requirements]] document.

Please use this template when adding entries to this list:

{{statusitem
|name=Feature name
|owner=owner(s)
|status=
Status notes: completed, development in progress, spec finished (but no implementation started yet), spec in progress, not started.
}}

=== GFX/Widget ===

{{statusitem
|name=Cairo Graphics
|owner=vlad, stuart
|status=
In progress; 90% on windows, 75% on linux, 25% on mac
}}

{{statusitem
|name=Cocoa Widgets
|owner=josh
|status=
In progress
}}

=== Layout ===

{{statusitem
|name=Reflow branch
|owner=dbaron
|status=
}}

{{statusitem
|name=CSS box model
|owner=
|status=
}}

=== XUL ===

=== Core/XML ===

{{statusitem
|name=XBL2
|owner=sicking
|status=
}}

=== JavaScript ===

{{statusitem
|name=JavaScript 2
|owner=brendan
|status=
}}

{{statusitem
|name=E4X4DOM
|owner=brendan?
|status=
}}

=== DOM ===

{{statusitem
|name=Language-agnostic DOM
|owner=
|status=
}}

=== SVG ===

{{statusitem
|name=SVG images
|owner=
|status=
}}

=== Networking ===

{{statusitem
|name=Cross-domain XMLHttpRequest
|owner=darin
|status=
}}

Runway/Queue

2006-05-11T00:52:07Z

Darin:

Add your bugs here to have them scheduled for landing on the [[Runway|runway]]. Be sure to ping the [[Sheriff_Schedule|sheriff on duty]] to let them know once you've added your entry to the list.
* use { { bug | #} } to add your bug
* the pilot must be around to check in the code and help it land
* include a summary so the sheriff can prioritize
* include the pilot's availability

{|cellpadding="3"
|- style="background-color: #efefef"
| '''Bug'''
| '''Pilot'''
| '''Summary'''
| '''requested time'''
|-
| <del>{{bug|336945}}</del>
| beng
| Fix web handler selection options on windows. Not so scary.
| evening EDT
|-
| {{bug|336609}}
| smontagu
| DeCOMtaminate utils in intl/uconv. Moderately scary, and I will need help from a CVS admin to preserve history of files being moved
| after 10pm PDT
|-
| {{bug|337178}}
| mconnor
| Enable suggest search on trunk. Not so scary, but original landing leaked.
| flexible with an hour's notice
|-
| {{bug|337305}}
| myk
| unbreak adding bookmark from scratch; trivial fix
| early afternoon PDT
|-
| {{bug|337113}}
| myk
| make the microsummary service grab generators from the cache instead of the network in more cases; low risk, already checked in on branch
| early afternoon PDT
|-
| {{bug|336857}}
| myk
| fix bookmark display regressions in bookmarks menu/toolbar; low risk, possible slight performance win (but probably negligible)
| early afternoon PDT
|}

XPCOM:nsIThreadManager

2006-05-05T07:03:38Z

Darin: /* nsRunnable */

In a world without nested event queues, the concept of a thread and an event queue merge...

== Interfaces ==
=== nsIThreadManager ===
[scriptable, uuid(...)]
interface nsIThreadManager : nsISupports {
/**
* Create a new thread (a global, user PRThread). Currently, flags is
* an unused parameter, that must be 0.
*/
nsIThread newThread(in unsigned long flags);
 
/**
* Get the nsIThread object (if any) corresponding to the given PRThread.
* This method returns null if there is no corresponding nsIThread.
*/
[noscript] nsIThread getThreadFromPRThread(in PRThread thread);
 
/**
* Get the main thread.
*/
readonly attribute nsIThread mainThread;
 
/**
* Get the current thread.
*/
readonly attribute nsIThread currentThread;
 
/**
* This attribute is true if the calling thread is the main thread of the
* application process.
*/
readonly attribute boolean isMainThread;
};

=== nsIEventTarget ===
[scriptable, uuid(...)]
interface nsIEventTarget : nsISupports {
/**
* Dispatch an event to the target. This function may be called from any
* thread. If flags specifies DISPATCH_SYNC, then the dispatch method
* will not return until the event has been processed. NOTE: Calling
* dispatch with DISPATCH_SYNC, may have the side-effect of running other
* events on the current thread while waiting for the given event to run
* to completion. This function is thread-safe and re-entrant.
*/
void dispatch(in nsIRunnable event, in unsigned long flags);
const unsigned long DISPATCH_NORMAL = 0;
const unsigned long DISPATCH_SYNC = 1;
 
/**
* Returns true if events dispatched to this target will run on the
* current thread (i.e., the thread calling this method).
*/
boolean isOnCurrentThread();
};
 
%{C++
// convenient aliases:
#define NS_DISPATCH_NORMAL nsIEventTarget::DISPATCH_NORMAL
#define NS_DISPATCH_SYNC nsIEventTarget::DISPATCH_SYNC
%}

=== nsIThread ===
[scriptable, uuid(...)]
interface nsIThread : nsIEventTarget {
/**
* Returns the PRThread object corresponding to this nsIThread.
*/
[noscript] readonly attribute PRThread PRThread;
 
/**
* Shutdown the thread. This method may not be executed from the thread
* itself. Instead, it is meant to be executed from another thread (usually
* the thread that created this thread). When this function returns, the
* thread will be shutdown, and it will no longer be possible to dispatch
* events to the thread.
*/
void shutdown();
 
/**
* Returns true if this thread has one or more pending events.
*/
boolean hasPendingEvents();
 
/**
* Process the next event. If there are no pending events, then this
* method may wait -- provided mayWait is true -- until an event is
* dispatched to this thread. This method is re-entrant but may only be
* called if this thread is the current thread.
*
* @return A boolean value that is "true" if an event was processed.
*/
boolean processNextEvent(in boolean mayWait);
};

=== nsIThreadInternal ===
[scriptable, uuid(...)]
interface nsIThreadInternal : nsIThread {
/**
* Get/set an observer for this thread (may be null). This attribute may
* be read from any thread, but must only be set on the thread corresponding
* to this thread object.
*/
attribute nsIThreadObserver observer;
 
/**
* This method causes any events currently enqueued on the thread to be
* suppressed until PopEventQueue is called. Additionally, any new events
* dispatched to the thread will only be processed if they are accepted by
* the given filter. If the filter is null, then new events are accepted.
* Calls to PushEventQueue may be nested and must each be paired with a call
* to PopEventQueue in order to restore the original state of the thread.
*/
void pushEventQueue(in nsIThreadEventFilter filter);
 
/**
* Revert a call to PushEventQueue. When an event queue is popped, any
* events remaining in the queue are appended to the elder queue.
*/
void popEventQueue();
};

=== nsIThreadObserver ===
[scriptable, uuid(...)]
interface nsIThreadObserver : nsISupports {
/**
* This method is called after an event has been dispatched to the thread.
* This method may be called from any thread.
*/
void onDispatchedEvent(in nsIThreadInternal thread);
 
/**
* This method is called (from nsIThread::ProcessNextEvent) before an event
* is processed. This method is only called on the target thread.
*
* @param thread
* The thread being asked to process another event.
* @param mayWait
* Indicates whether or not the method is allowed to block the calling
* thread. For example, this parameter is false during thread shutdown.
* @param recursionDepth
* Indicates the number of calls to ProcessNextEvent on the call stack
* in addition to the current call.
*/
void onProcessNextEvent(in nsIThreadInternal thread, in boolean mayWait,
in unsigned long recursionDepth);
};

=== nsIThreadEventFilter ===
[scriptable, uuid(...)]
interface nsIThreadEventFilter : nsISupports {
/**
* This method is called to determine whether or not an event may be accepted
* by a "nested" event queue (see nsIThreadInternal::PushEventQueue).
*
* WARNING: This method must not make any calls on the thread object.
*/
[notxpcom] boolean AcceptEvent(in nsIRunnable event);
};

=== nsIThreadPool ===
[scriptable, uuid(...)]
interface nsIThreadPool : nsIEventTarget
{
/**
* Shutdown the thread pool. This method may not be executed from any
* thread in the thread pool. Instead, it is meant to be executed from
* another thread (usually the thread that created this thread pool).
* When this function returns, the thread pool and all of its threads will
* be shutdown, and it will no longer be possible to dispatch tasks to the
* thread pool.
*/
void shutdown()
 
/**
* Get/set the maximum number of threads allowed at one time in this pool.
*/
attribute unsigned long threadLimit;
 
/**
* Get/set the maximum number of idle threads kept alive.
*/
attribute unsigned long idleThreadLimit;
 
/**
* Get/set the amount of time in milliseconds before an idle thread is
* destroyed.
*/
attribute unsigned long idleThreadTimeout;
};

== C++ Utilities ==

=== Functions ===
nsThreadUtils.h defines the following helper functions:

/**
* Create a new thread.
*
* @param result
* The resulting nsIThread object.
* @param event
* The initial event to run on this thread. This can be null.
*/
NS_METHOD NS_NewThread(nsIThread **result, nsIRunnable *event);
 
/**
* Get a reference to the current thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetCurrentThread(nsIThread **result);
 
/**
* Get a reference to the main thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetMainThread(nsIThread **result);
 
/**
* Test to see if the current thread is the main thread.
*
* @returns PR_TRUE if the current thread is the main thread, and PR_FALSE
* otherwise.
*/
PRBool NS_IsMainThread();
 
/**
* Dispatch the given event to the current thread.
*
* @param event
* The event to dispatch.
*/
NS_METHOD NS_DispatchToCurrentThread(nsIRunnable *event);
 
/**
* Dispatch the given event to the main thread.
*
* @param event
* The event to dispatch.
* @param dispatchFlags
* The flags to pass to the main thread's dispatch method.
*/
NS_METHOD NS_DispatchToMainThread(nsIRunnable *event,
PRUint32 dispatchFlags = NS_DISPATCH_NORMAL);
 
/**
* Process all pending events for the given thread before returning. This
* method simply calls ProcessNextEvent on the thread while HasPendingEvents
* continues to return true and the time spent in NS_ProcessPendingEvents
* does not exceed the given timeout value.
*
* @param thread
* The thread object for which to process pending events. If null,
* then events will be processed for the current thread.
* @param timeout
* The maximum number of milliseconds to spend processing pending
* events. Events are not pre-empted to honor this timeout. Rather,
* the timeout value is simply used to determine whether or not to
* process another event. Pass PR_INTERVAL_NO_TIMEOUT to specify no
* timeout.
*/
NS_METHOD NS_ProcessPendingEvents(nsIThread *thread = nsnull,
PRIntervalTime timeout = PR_INTERVAL_NO_TIMEOUT);

=== nsCOMPtr helpers ===
The following nsCOMPtr helpers are defined to simplify things further:

already_AddRefed<nsIThread> do_GetCurrentThread();
 
already_AddRefed<nsIThread> do_GetMainThread();

=== nsRunnable ===
The class <code>nsRunnable</code> is also defined to simplify the
implementation of new event types. For example, to define a new
event all you need to do is write code like this:

class MyEvent : public nsRunnable {
public:
MyEvent(... params ...);
 
NS_IMETHOD Run() {
// do stuff
return NS_OK;
}
};

Dispatching <code>MyEvent</code> is then as simple as:

nsCOMPtr<nsIRunnable> event = new MyEvent();
rv = NS_DispatchToCurrentThread(event);
NS_ENSURE_SUCCESS(rv, rv);

== From JS ==

=== Event Dispatch ===
Threads and Thread Manager implement <code>nsIClassInfo</code>:

function MyEvent() {
}
MyEvent.prototype = {
QueryInterface: function(iid) {
if (iid.equals(Components.interfaces.nsIRunnable) ||
iid.equals(Components.interfaces.nsISupports))
return this;
throw Components.results.NS_ERROR_NO_INTERFACE;
},
run: function() {
// do stuff
}
};
 
function DispatchMyEvent() {
var target =
Components.classes["@mozilla.org/thread-manager;1"].
getService().currentThread;
 
target.dispatch(new MyEvent(), target.DISPATCH_NORMAL);
}

== Remarks ==

* Thread priority for native threads can be exposed via <code>nsISupportsPriority</code>.
* Thread names must be unique.
* The Necko I/O thread pool will be replaced by a generic thread pool implementation provided by XPCOM. The thread pool will implement <code>nsIEventTarget</code>, allowing events to be dispatched to any thread in the thread pool. We may even wish to define a <code>nsIThreadPool</code> interface and have it implement that as well. That interface would define methods to adjust the limits on the number of threads in the thread pool and so on.
* We will need an alternative for <code>nsIEventQueue::RevokeEvents</code>. There are several possibilities: (1) make consumers hold references to their nsIRunnable's so they can "disconnect" them manually, or (2) expose an enumeration/visitor API that allows consumers to walk the list of pending tasks and remove arbitrary tasks. I'm not sure what is best yet. The first option or something similar based on weak references is probably best as it avoids the costly O(n) <code>RevokeEvents</code> call.
* The following interfaces/classes would go away or be modified heavily: <code>nsIEventQueue</code>, <code>nsIEventQueueService</code>, <code>nsIEventTarget</code>, <code>nsIThread</code>, <code>PLEvent</code>.
* Issue: Perhaps we should support calling <code>nsIThread::Shutdown</code> from the thread itself. That would probably have to be implemented by posting an event to the main thread, and having that thread call shutdown. However, <code>Shutdown</code> also has the property that it does not return until the thread is gone. That obvious can't happen if <code>Shutdown</code> is called on the thread itself.

=== What about "native" event queues? ===
The main thread where UI events are processed and the socket transport thread will use the observer interface defined by <code>nsIThreadInternal</code>. The main thread will interact with the "native" event system during calls to <code>ProcessNextEvent</code> and <code>Dispatch</code>. Likewise, the socket transport thread will similarly need to poll sockets and perform I/O operations. By observing calls to <code>ProcessNextEvent</code>, observers can wait on a native event queue (or poll on a set of file descriptors) instead of waiting on the thread's internal event queue monitor. When they observe a call to <code>Dispatch</code>, they can use whatever mechanism is appropriate to unblock the thread that is waiting on the native event queue.

=== How do synchronous events work? ===

When <code>Dispatch(event, DISPATCH_SYNC)</code> is called on a <code>nsIEventTarget</code>, it first checks to see if the current thread is the same as the thread where the event would be run. If it is, then it just runs the event directly without queuing it up. However, if not, then it must queue the event to be run when the dispatch target next processes its events. To avoid returning to the caller immediately, the method gets the current thread and calls its <code>ProcessNextEvent</code> method in a loop until it receives acknowledgement that the queued event has been run.

== Development ==

Development is occuring on the THREADS_20060307_BRANCH. See also {{bug|326273}}.

== Comments ==

=== biesi: ===
* What happens if shutdown is called while an event is being processed? I assume that this event will be processed to its end, no further events are accepted, and then the thread is shut down. right?
** What happens to events that were already dispatched to this thread, but not run?
* Is it a good idea to allow other events to run on the current thread while in dispatch?
* Who is expected to call ProcessNextEvent?

==== darin: ====
* When asked to shutdown, a thread would finish dispatching all queued events, and refuse to accept any new events. Once all queued events run to completion, the thread would terminate. This is consistent with how event queues work today.
* If you are sync dispatching, then it is necessary to pump events on the calling thread or else you could end up in a dead-lock situation. For example, if thread A sync dispatches an event to thread B, which cannot complete its job without dispatching an event back to thread A, then the system will dead-lock unless thread A continues to dispatch pending events.
* <code>ProcessNextEvent</code> may be called by anybody that wishes to implement the concept of a "modal event loop." For example, XMLHttpRequest (in sync configuration) would sit in a loop calling <code>ProcessNextEvent</code> while waiting for the underlying HTTP transaction to complete. The key difference between <code>ProcessNextEvent</code> and <code>nsIEventQueue::ProcessPendingEvents</code> is that <code>ProcessNextEvent</code>, when called on the UI thread, will process UI events as well. And, it will also wait (block the thread of execution) if there are no UI events or pending <code>nsIRunnable</code> events.

=== dbaron: ===
So mrbkap was telling me at lunch about what's essentially the third bullet point of your comment to biesi above -- that you're making the concept of "modal event loop" even more powerful. This actually scares me a good bit, because these modal event loops happen within another event -- an event that may have state on the stack (e.g., |this| parameters) that could be destroyed by the processing of further events, or may have posted events that rely on the event completing. I really don't like the mix of programming models here that makes it very hard to write robust code, and I wish we could avoid this whole concept altogether rather than making it even more powerful, and thus more dangerous. We already have crashes where frame trees get destroyed while processing an event that are related to the Windows API's way of doing the same thing, though (for, e.g., a DestroyWindow call or whatever it's called).

==== darin: ====
Yup, I'm aware of that issue. In fact, the problem already exists today. There are some places in the code where WaitPLEvent + HandleEvent are called in a loop waiting for an event to process. That bypasses PL_ProcessPendingEvents recursion restriction. PopThreadEventQueue does not behave as you would expect either. It can cause ProcessPendingEvents to run for all but the PLEventQueue that is the subject of the current call to PL_ProcessPendingEvents on the stack. That defeats the purpose of the nested event queue in the first place.

The problem you describe with layout events also occurs for nsIStreamListener implementations. It would be really wierd if OnDataAvailable were called recursively, or if OnDataAvailable were called while the consumer is calling nsIChannel::AsyncOpen. These specific problems are dealt with in nsBaseChannel.cpp by temporarily suspending the channel during callbacks. That suppresses recusive stream listener calls.

Do you have a suggestion that would allow us to prevent this problem? Is there a better way to make XMLHttpRequest.send, document.load, window.alert, etc. appear modal to the calling Javascript?

For C++ consumers, we'd have to basically eliminate modal dialogs altogether to avoid this problem. Today, we have bugs where downloads stall and get disconnected all because the browser popped up a modal dialog and the dialog was not closed promptly enough by the user. That's just unacceptable. And, nsIPromptService is frozen.

I think the answer is to be careful about making callbacks across XPCOM boundaries where event queues may be pumped. Maybe the layout code needs to unwind the stack more before allowing such callbacks to happen so that it can be sure that event processing won't be the end of the world.

dbaron: Also, with the new push/popEventQueue API defined on nsIThreadInternal, it is possible to suppress event dispatch for a particular scope. That is needed to implement synchronous XPCOM proxy calls. I'm assuming that any proper use of synchronous XPCOM proxy calls will be one that completes relatively quickly so as to negate the effects of locking up the browser. We should probably be very careful about calling PushEventQueue on the main thread, where it would potentially disrupt the browser UI. Native events would still be dispatched as always, but without application level events, the UI isn't very useful.

XPCOM:nsIThreadManager

2006-05-05T07:02:41Z

Darin: /* nsCOMPtr helpers */

In a world without nested event queues, the concept of a thread and an event queue merge...

== Interfaces ==
=== nsIThreadManager ===
[scriptable, uuid(...)]
interface nsIThreadManager : nsISupports {
/**
* Create a new thread (a global, user PRThread). Currently, flags is
* an unused parameter, that must be 0.
*/
nsIThread newThread(in unsigned long flags);
 
/**
* Get the nsIThread object (if any) corresponding to the given PRThread.
* This method returns null if there is no corresponding nsIThread.
*/
[noscript] nsIThread getThreadFromPRThread(in PRThread thread);
 
/**
* Get the main thread.
*/
readonly attribute nsIThread mainThread;
 
/**
* Get the current thread.
*/
readonly attribute nsIThread currentThread;
 
/**
* This attribute is true if the calling thread is the main thread of the
* application process.
*/
readonly attribute boolean isMainThread;
};

=== nsIEventTarget ===
[scriptable, uuid(...)]
interface nsIEventTarget : nsISupports {
/**
* Dispatch an event to the target. This function may be called from any
* thread. If flags specifies DISPATCH_SYNC, then the dispatch method
* will not return until the event has been processed. NOTE: Calling
* dispatch with DISPATCH_SYNC, may have the side-effect of running other
* events on the current thread while waiting for the given event to run
* to completion. This function is thread-safe and re-entrant.
*/
void dispatch(in nsIRunnable event, in unsigned long flags);
const unsigned long DISPATCH_NORMAL = 0;
const unsigned long DISPATCH_SYNC = 1;
 
/**
* Returns true if events dispatched to this target will run on the
* current thread (i.e., the thread calling this method).
*/
boolean isOnCurrentThread();
};
 
%{C++
// convenient aliases:
#define NS_DISPATCH_NORMAL nsIEventTarget::DISPATCH_NORMAL
#define NS_DISPATCH_SYNC nsIEventTarget::DISPATCH_SYNC
%}

=== nsIThread ===
[scriptable, uuid(...)]
interface nsIThread : nsIEventTarget {
/**
* Returns the PRThread object corresponding to this nsIThread.
*/
[noscript] readonly attribute PRThread PRThread;
 
/**
* Shutdown the thread. This method may not be executed from the thread
* itself. Instead, it is meant to be executed from another thread (usually
* the thread that created this thread). When this function returns, the
* thread will be shutdown, and it will no longer be possible to dispatch
* events to the thread.
*/
void shutdown();
 
/**
* Returns true if this thread has one or more pending events.
*/
boolean hasPendingEvents();
 
/**
* Process the next event. If there are no pending events, then this
* method may wait -- provided mayWait is true -- until an event is
* dispatched to this thread. This method is re-entrant but may only be
* called if this thread is the current thread.
*
* @return A boolean value that is "true" if an event was processed.
*/
boolean processNextEvent(in boolean mayWait);
};

=== nsIThreadInternal ===
[scriptable, uuid(...)]
interface nsIThreadInternal : nsIThread {
/**
* Get/set an observer for this thread (may be null). This attribute may
* be read from any thread, but must only be set on the thread corresponding
* to this thread object.
*/
attribute nsIThreadObserver observer;
 
/**
* This method causes any events currently enqueued on the thread to be
* suppressed until PopEventQueue is called. Additionally, any new events
* dispatched to the thread will only be processed if they are accepted by
* the given filter. If the filter is null, then new events are accepted.
* Calls to PushEventQueue may be nested and must each be paired with a call
* to PopEventQueue in order to restore the original state of the thread.
*/
void pushEventQueue(in nsIThreadEventFilter filter);
 
/**
* Revert a call to PushEventQueue. When an event queue is popped, any
* events remaining in the queue are appended to the elder queue.
*/
void popEventQueue();
};

=== nsIThreadObserver ===
[scriptable, uuid(...)]
interface nsIThreadObserver : nsISupports {
/**
* This method is called after an event has been dispatched to the thread.
* This method may be called from any thread.
*/
void onDispatchedEvent(in nsIThreadInternal thread);
 
/**
* This method is called (from nsIThread::ProcessNextEvent) before an event
* is processed. This method is only called on the target thread.
*
* @param thread
* The thread being asked to process another event.
* @param mayWait
* Indicates whether or not the method is allowed to block the calling
* thread. For example, this parameter is false during thread shutdown.
* @param recursionDepth
* Indicates the number of calls to ProcessNextEvent on the call stack
* in addition to the current call.
*/
void onProcessNextEvent(in nsIThreadInternal thread, in boolean mayWait,
in unsigned long recursionDepth);
};

=== nsIThreadEventFilter ===
[scriptable, uuid(...)]
interface nsIThreadEventFilter : nsISupports {
/**
* This method is called to determine whether or not an event may be accepted
* by a "nested" event queue (see nsIThreadInternal::PushEventQueue).
*
* WARNING: This method must not make any calls on the thread object.
*/
[notxpcom] boolean AcceptEvent(in nsIRunnable event);
};

=== nsIThreadPool ===
[scriptable, uuid(...)]
interface nsIThreadPool : nsIEventTarget
{
/**
* Shutdown the thread pool. This method may not be executed from any
* thread in the thread pool. Instead, it is meant to be executed from
* another thread (usually the thread that created this thread pool).
* When this function returns, the thread pool and all of its threads will
* be shutdown, and it will no longer be possible to dispatch tasks to the
* thread pool.
*/
void shutdown()
 
/**
* Get/set the maximum number of threads allowed at one time in this pool.
*/
attribute unsigned long threadLimit;
 
/**
* Get/set the maximum number of idle threads kept alive.
*/
attribute unsigned long idleThreadLimit;
 
/**
* Get/set the amount of time in milliseconds before an idle thread is
* destroyed.
*/
attribute unsigned long idleThreadTimeout;
};

== C++ Utilities ==

=== Functions ===
nsThreadUtils.h defines the following helper functions:

/**
* Create a new thread.
*
* @param result
* The resulting nsIThread object.
* @param event
* The initial event to run on this thread. This can be null.
*/
NS_METHOD NS_NewThread(nsIThread **result, nsIRunnable *event);
 
/**
* Get a reference to the current thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetCurrentThread(nsIThread **result);
 
/**
* Get a reference to the main thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetMainThread(nsIThread **result);
 
/**
* Test to see if the current thread is the main thread.
*
* @returns PR_TRUE if the current thread is the main thread, and PR_FALSE
* otherwise.
*/
PRBool NS_IsMainThread();
 
/**
* Dispatch the given event to the current thread.
*
* @param event
* The event to dispatch.
*/
NS_METHOD NS_DispatchToCurrentThread(nsIRunnable *event);
 
/**
* Dispatch the given event to the main thread.
*
* @param event
* The event to dispatch.
* @param dispatchFlags
* The flags to pass to the main thread's dispatch method.
*/
NS_METHOD NS_DispatchToMainThread(nsIRunnable *event,
PRUint32 dispatchFlags = NS_DISPATCH_NORMAL);
 
/**
* Process all pending events for the given thread before returning. This
* method simply calls ProcessNextEvent on the thread while HasPendingEvents
* continues to return true and the time spent in NS_ProcessPendingEvents
* does not exceed the given timeout value.
*
* @param thread
* The thread object for which to process pending events. If null,
* then events will be processed for the current thread.
* @param timeout
* The maximum number of milliseconds to spend processing pending
* events. Events are not pre-empted to honor this timeout. Rather,
* the timeout value is simply used to determine whether or not to
* process another event. Pass PR_INTERVAL_NO_TIMEOUT to specify no
* timeout.
*/
NS_METHOD NS_ProcessPendingEvents(nsIThread *thread = nsnull,
PRIntervalTime timeout = PR_INTERVAL_NO_TIMEOUT);

=== nsCOMPtr helpers ===
The following nsCOMPtr helpers are defined to simplify things further:

already_AddRefed<nsIThread> do_GetCurrentThread();
 
already_AddRefed<nsIThread> do_GetMainThread();

=== nsRunnable ===
The class <code>nsRunnable</code> is also defined to simplify the
implementation of new event types. For example, to define a new
event all you need to do is write code like this:

class MyEvent : public nsRunnable {
public:
MyEvent(... params ...);
 
NS_IMETHOD Run() {
// do stuff
return NS_OK;
}
};

Dispatching <code>MyEvent</code> is then as simple as:

nsCOMPtr<nsIThread> thread = do_GetCurrentThread();
NS_ENSURE_STATE(thread);
 
nsCOMPtr<nsIRunnable> event = new MyEvent();
NS_ENSURE_STATE(event);
 
thread->Dispatch(event, NS_DISPATCH_NORMAL);

== From JS ==

=== Event Dispatch ===
Threads and Thread Manager implement <code>nsIClassInfo</code>:

function MyEvent() {
}
MyEvent.prototype = {
QueryInterface: function(iid) {
if (iid.equals(Components.interfaces.nsIRunnable) ||
iid.equals(Components.interfaces.nsISupports))
return this;
throw Components.results.NS_ERROR_NO_INTERFACE;
},
run: function() {
// do stuff
}
};
 
function DispatchMyEvent() {
var target =
Components.classes["@mozilla.org/thread-manager;1"].
getService().currentThread;
 
target.dispatch(new MyEvent(), target.DISPATCH_NORMAL);
}

== Remarks ==

* Thread priority for native threads can be exposed via <code>nsISupportsPriority</code>.
* Thread names must be unique.
* The Necko I/O thread pool will be replaced by a generic thread pool implementation provided by XPCOM. The thread pool will implement <code>nsIEventTarget</code>, allowing events to be dispatched to any thread in the thread pool. We may even wish to define a <code>nsIThreadPool</code> interface and have it implement that as well. That interface would define methods to adjust the limits on the number of threads in the thread pool and so on.
* We will need an alternative for <code>nsIEventQueue::RevokeEvents</code>. There are several possibilities: (1) make consumers hold references to their nsIRunnable's so they can "disconnect" them manually, or (2) expose an enumeration/visitor API that allows consumers to walk the list of pending tasks and remove arbitrary tasks. I'm not sure what is best yet. The first option or something similar based on weak references is probably best as it avoids the costly O(n) <code>RevokeEvents</code> call.
* The following interfaces/classes would go away or be modified heavily: <code>nsIEventQueue</code>, <code>nsIEventQueueService</code>, <code>nsIEventTarget</code>, <code>nsIThread</code>, <code>PLEvent</code>.
* Issue: Perhaps we should support calling <code>nsIThread::Shutdown</code> from the thread itself. That would probably have to be implemented by posting an event to the main thread, and having that thread call shutdown. However, <code>Shutdown</code> also has the property that it does not return until the thread is gone. That obvious can't happen if <code>Shutdown</code> is called on the thread itself.

=== What about "native" event queues? ===
The main thread where UI events are processed and the socket transport thread will use the observer interface defined by <code>nsIThreadInternal</code>. The main thread will interact with the "native" event system during calls to <code>ProcessNextEvent</code> and <code>Dispatch</code>. Likewise, the socket transport thread will similarly need to poll sockets and perform I/O operations. By observing calls to <code>ProcessNextEvent</code>, observers can wait on a native event queue (or poll on a set of file descriptors) instead of waiting on the thread's internal event queue monitor. When they observe a call to <code>Dispatch</code>, they can use whatever mechanism is appropriate to unblock the thread that is waiting on the native event queue.

=== How do synchronous events work? ===

When <code>Dispatch(event, DISPATCH_SYNC)</code> is called on a <code>nsIEventTarget</code>, it first checks to see if the current thread is the same as the thread where the event would be run. If it is, then it just runs the event directly without queuing it up. However, if not, then it must queue the event to be run when the dispatch target next processes its events. To avoid returning to the caller immediately, the method gets the current thread and calls its <code>ProcessNextEvent</code> method in a loop until it receives acknowledgement that the queued event has been run.

== Development ==

Development is occuring on the THREADS_20060307_BRANCH. See also {{bug|326273}}.

== Comments ==

=== biesi: ===
* What happens if shutdown is called while an event is being processed? I assume that this event will be processed to its end, no further events are accepted, and then the thread is shut down. right?
** What happens to events that were already dispatched to this thread, but not run?
* Is it a good idea to allow other events to run on the current thread while in dispatch?
* Who is expected to call ProcessNextEvent?

==== darin: ====
* When asked to shutdown, a thread would finish dispatching all queued events, and refuse to accept any new events. Once all queued events run to completion, the thread would terminate. This is consistent with how event queues work today.
* If you are sync dispatching, then it is necessary to pump events on the calling thread or else you could end up in a dead-lock situation. For example, if thread A sync dispatches an event to thread B, which cannot complete its job without dispatching an event back to thread A, then the system will dead-lock unless thread A continues to dispatch pending events.
* <code>ProcessNextEvent</code> may be called by anybody that wishes to implement the concept of a "modal event loop." For example, XMLHttpRequest (in sync configuration) would sit in a loop calling <code>ProcessNextEvent</code> while waiting for the underlying HTTP transaction to complete. The key difference between <code>ProcessNextEvent</code> and <code>nsIEventQueue::ProcessPendingEvents</code> is that <code>ProcessNextEvent</code>, when called on the UI thread, will process UI events as well. And, it will also wait (block the thread of execution) if there are no UI events or pending <code>nsIRunnable</code> events.

=== dbaron: ===
So mrbkap was telling me at lunch about what's essentially the third bullet point of your comment to biesi above -- that you're making the concept of "modal event loop" even more powerful. This actually scares me a good bit, because these modal event loops happen within another event -- an event that may have state on the stack (e.g., |this| parameters) that could be destroyed by the processing of further events, or may have posted events that rely on the event completing. I really don't like the mix of programming models here that makes it very hard to write robust code, and I wish we could avoid this whole concept altogether rather than making it even more powerful, and thus more dangerous. We already have crashes where frame trees get destroyed while processing an event that are related to the Windows API's way of doing the same thing, though (for, e.g., a DestroyWindow call or whatever it's called).

==== darin: ====
Yup, I'm aware of that issue. In fact, the problem already exists today. There are some places in the code where WaitPLEvent + HandleEvent are called in a loop waiting for an event to process. That bypasses PL_ProcessPendingEvents recursion restriction. PopThreadEventQueue does not behave as you would expect either. It can cause ProcessPendingEvents to run for all but the PLEventQueue that is the subject of the current call to PL_ProcessPendingEvents on the stack. That defeats the purpose of the nested event queue in the first place.

The problem you describe with layout events also occurs for nsIStreamListener implementations. It would be really wierd if OnDataAvailable were called recursively, or if OnDataAvailable were called while the consumer is calling nsIChannel::AsyncOpen. These specific problems are dealt with in nsBaseChannel.cpp by temporarily suspending the channel during callbacks. That suppresses recusive stream listener calls.

Do you have a suggestion that would allow us to prevent this problem? Is there a better way to make XMLHttpRequest.send, document.load, window.alert, etc. appear modal to the calling Javascript?

For C++ consumers, we'd have to basically eliminate modal dialogs altogether to avoid this problem. Today, we have bugs where downloads stall and get disconnected all because the browser popped up a modal dialog and the dialog was not closed promptly enough by the user. That's just unacceptable. And, nsIPromptService is frozen.

I think the answer is to be careful about making callbacks across XPCOM boundaries where event queues may be pumped. Maybe the layout code needs to unwind the stack more before allowing such callbacks to happen so that it can be sure that event processing won't be the end of the world.

dbaron: Also, with the new push/popEventQueue API defined on nsIThreadInternal, it is possible to suppress event dispatch for a particular scope. That is needed to implement synchronous XPCOM proxy calls. I'm assuming that any proper use of synchronous XPCOM proxy calls will be one that completes relatively quickly so as to negate the effects of locking up the browser. We should probably be very careful about calling PushEventQueue on the main thread, where it would potentially disrupt the browser UI. Native events would still be dispatched as always, but without application level events, the UI isn't very useful.

XPCOM:nsIThreadManager

2006-05-05T07:02:27Z

Darin: /* Functions */

In a world without nested event queues, the concept of a thread and an event queue merge...

== Interfaces ==
=== nsIThreadManager ===
[scriptable, uuid(...)]
interface nsIThreadManager : nsISupports {
/**
* Create a new thread (a global, user PRThread). Currently, flags is
* an unused parameter, that must be 0.
*/
nsIThread newThread(in unsigned long flags);
 
/**
* Get the nsIThread object (if any) corresponding to the given PRThread.
* This method returns null if there is no corresponding nsIThread.
*/
[noscript] nsIThread getThreadFromPRThread(in PRThread thread);
 
/**
* Get the main thread.
*/
readonly attribute nsIThread mainThread;
 
/**
* Get the current thread.
*/
readonly attribute nsIThread currentThread;
 
/**
* This attribute is true if the calling thread is the main thread of the
* application process.
*/
readonly attribute boolean isMainThread;
};

=== nsIEventTarget ===
[scriptable, uuid(...)]
interface nsIEventTarget : nsISupports {
/**
* Dispatch an event to the target. This function may be called from any
* thread. If flags specifies DISPATCH_SYNC, then the dispatch method
* will not return until the event has been processed. NOTE: Calling
* dispatch with DISPATCH_SYNC, may have the side-effect of running other
* events on the current thread while waiting for the given event to run
* to completion. This function is thread-safe and re-entrant.
*/
void dispatch(in nsIRunnable event, in unsigned long flags);
const unsigned long DISPATCH_NORMAL = 0;
const unsigned long DISPATCH_SYNC = 1;
 
/**
* Returns true if events dispatched to this target will run on the
* current thread (i.e., the thread calling this method).
*/
boolean isOnCurrentThread();
};
 
%{C++
// convenient aliases:
#define NS_DISPATCH_NORMAL nsIEventTarget::DISPATCH_NORMAL
#define NS_DISPATCH_SYNC nsIEventTarget::DISPATCH_SYNC
%}

=== nsIThread ===
[scriptable, uuid(...)]
interface nsIThread : nsIEventTarget {
/**
* Returns the PRThread object corresponding to this nsIThread.
*/
[noscript] readonly attribute PRThread PRThread;
 
/**
* Shutdown the thread. This method may not be executed from the thread
* itself. Instead, it is meant to be executed from another thread (usually
* the thread that created this thread). When this function returns, the
* thread will be shutdown, and it will no longer be possible to dispatch
* events to the thread.
*/
void shutdown();
 
/**
* Returns true if this thread has one or more pending events.
*/
boolean hasPendingEvents();
 
/**
* Process the next event. If there are no pending events, then this
* method may wait -- provided mayWait is true -- until an event is
* dispatched to this thread. This method is re-entrant but may only be
* called if this thread is the current thread.
*
* @return A boolean value that is "true" if an event was processed.
*/
boolean processNextEvent(in boolean mayWait);
};

=== nsIThreadInternal ===
[scriptable, uuid(...)]
interface nsIThreadInternal : nsIThread {
/**
* Get/set an observer for this thread (may be null). This attribute may
* be read from any thread, but must only be set on the thread corresponding
* to this thread object.
*/
attribute nsIThreadObserver observer;
 
/**
* This method causes any events currently enqueued on the thread to be
* suppressed until PopEventQueue is called. Additionally, any new events
* dispatched to the thread will only be processed if they are accepted by
* the given filter. If the filter is null, then new events are accepted.
* Calls to PushEventQueue may be nested and must each be paired with a call
* to PopEventQueue in order to restore the original state of the thread.
*/
void pushEventQueue(in nsIThreadEventFilter filter);
 
/**
* Revert a call to PushEventQueue. When an event queue is popped, any
* events remaining in the queue are appended to the elder queue.
*/
void popEventQueue();
};

=== nsIThreadObserver ===
[scriptable, uuid(...)]
interface nsIThreadObserver : nsISupports {
/**
* This method is called after an event has been dispatched to the thread.
* This method may be called from any thread.
*/
void onDispatchedEvent(in nsIThreadInternal thread);
 
/**
* This method is called (from nsIThread::ProcessNextEvent) before an event
* is processed. This method is only called on the target thread.
*
* @param thread
* The thread being asked to process another event.
* @param mayWait
* Indicates whether or not the method is allowed to block the calling
* thread. For example, this parameter is false during thread shutdown.
* @param recursionDepth
* Indicates the number of calls to ProcessNextEvent on the call stack
* in addition to the current call.
*/
void onProcessNextEvent(in nsIThreadInternal thread, in boolean mayWait,
in unsigned long recursionDepth);
};

=== nsIThreadEventFilter ===
[scriptable, uuid(...)]
interface nsIThreadEventFilter : nsISupports {
/**
* This method is called to determine whether or not an event may be accepted
* by a "nested" event queue (see nsIThreadInternal::PushEventQueue).
*
* WARNING: This method must not make any calls on the thread object.
*/
[notxpcom] boolean AcceptEvent(in nsIRunnable event);
};

=== nsIThreadPool ===
[scriptable, uuid(...)]
interface nsIThreadPool : nsIEventTarget
{
/**
* Shutdown the thread pool. This method may not be executed from any
* thread in the thread pool. Instead, it is meant to be executed from
* another thread (usually the thread that created this thread pool).
* When this function returns, the thread pool and all of its threads will
* be shutdown, and it will no longer be possible to dispatch tasks to the
* thread pool.
*/
void shutdown()
 
/**
* Get/set the maximum number of threads allowed at one time in this pool.
*/
attribute unsigned long threadLimit;
 
/**
* Get/set the maximum number of idle threads kept alive.
*/
attribute unsigned long idleThreadLimit;
 
/**
* Get/set the amount of time in milliseconds before an idle thread is
* destroyed.
*/
attribute unsigned long idleThreadTimeout;
};

== C++ Utilities ==

=== Functions ===
nsThreadUtils.h defines the following helper functions:

/**
* Create a new thread.
*
* @param result
* The resulting nsIThread object.
* @param event
* The initial event to run on this thread. This can be null.
*/
NS_METHOD NS_NewThread(nsIThread **result, nsIRunnable *event);
 
/**
* Get a reference to the current thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetCurrentThread(nsIThread **result);
 
/**
* Get a reference to the main thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetMainThread(nsIThread **result);
 
/**
* Test to see if the current thread is the main thread.
*
* @returns PR_TRUE if the current thread is the main thread, and PR_FALSE
* otherwise.
*/
PRBool NS_IsMainThread();
 
/**
* Dispatch the given event to the current thread.
*
* @param event
* The event to dispatch.
*/
NS_METHOD NS_DispatchToCurrentThread(nsIRunnable *event);
 
/**
* Dispatch the given event to the main thread.
*
* @param event
* The event to dispatch.
* @param dispatchFlags
* The flags to pass to the main thread's dispatch method.
*/
NS_METHOD NS_DispatchToMainThread(nsIRunnable *event,
PRUint32 dispatchFlags = NS_DISPATCH_NORMAL);
 
/**
* Process all pending events for the given thread before returning. This
* method simply calls ProcessNextEvent on the thread while HasPendingEvents
* continues to return true and the time spent in NS_ProcessPendingEvents
* does not exceed the given timeout value.
*
* @param thread
* The thread object for which to process pending events. If null,
* then events will be processed for the current thread.
* @param timeout
* The maximum number of milliseconds to spend processing pending
* events. Events are not pre-empted to honor this timeout. Rather,
* the timeout value is simply used to determine whether or not to
* process another event. Pass PR_INTERVAL_NO_TIMEOUT to specify no
* timeout.
*/
NS_METHOD NS_ProcessPendingEvents(nsIThread *thread = nsnull,
PRIntervalTime timeout = PR_INTERVAL_NO_TIMEOUT);

=== nsCOMPtr helpers ===
The following nsCOMPtr helpers are defined to simplify things further:

already_AddRefed<nsIThread> do_GetCurrentThread();
 
already_AddRefed<nsIThread> do_GetMainThread();
 
already_AddRefed<nsIThread> do_GetThread(const nsACString &name);

=== nsRunnable ===
The class <code>nsRunnable</code> is also defined to simplify the
implementation of new event types. For example, to define a new
event all you need to do is write code like this:

class MyEvent : public nsRunnable {
public:
MyEvent(... params ...);
 
NS_IMETHOD Run() {
// do stuff
return NS_OK;
}
};

Dispatching <code>MyEvent</code> is then as simple as:

nsCOMPtr<nsIThread> thread = do_GetCurrentThread();
NS_ENSURE_STATE(thread);
 
nsCOMPtr<nsIRunnable> event = new MyEvent();
NS_ENSURE_STATE(event);
 
thread->Dispatch(event, NS_DISPATCH_NORMAL);

== From JS ==

=== Event Dispatch ===
Threads and Thread Manager implement <code>nsIClassInfo</code>:

function MyEvent() {
}
MyEvent.prototype = {
QueryInterface: function(iid) {
if (iid.equals(Components.interfaces.nsIRunnable) ||
iid.equals(Components.interfaces.nsISupports))
return this;
throw Components.results.NS_ERROR_NO_INTERFACE;
},
run: function() {
// do stuff
}
};
 
function DispatchMyEvent() {
var target =
Components.classes["@mozilla.org/thread-manager;1"].
getService().currentThread;
 
target.dispatch(new MyEvent(), target.DISPATCH_NORMAL);
}

== Remarks ==

* Thread priority for native threads can be exposed via <code>nsISupportsPriority</code>.
* Thread names must be unique.
* The Necko I/O thread pool will be replaced by a generic thread pool implementation provided by XPCOM. The thread pool will implement <code>nsIEventTarget</code>, allowing events to be dispatched to any thread in the thread pool. We may even wish to define a <code>nsIThreadPool</code> interface and have it implement that as well. That interface would define methods to adjust the limits on the number of threads in the thread pool and so on.
* We will need an alternative for <code>nsIEventQueue::RevokeEvents</code>. There are several possibilities: (1) make consumers hold references to their nsIRunnable's so they can "disconnect" them manually, or (2) expose an enumeration/visitor API that allows consumers to walk the list of pending tasks and remove arbitrary tasks. I'm not sure what is best yet. The first option or something similar based on weak references is probably best as it avoids the costly O(n) <code>RevokeEvents</code> call.
* The following interfaces/classes would go away or be modified heavily: <code>nsIEventQueue</code>, <code>nsIEventQueueService</code>, <code>nsIEventTarget</code>, <code>nsIThread</code>, <code>PLEvent</code>.
* Issue: Perhaps we should support calling <code>nsIThread::Shutdown</code> from the thread itself. That would probably have to be implemented by posting an event to the main thread, and having that thread call shutdown. However, <code>Shutdown</code> also has the property that it does not return until the thread is gone. That obvious can't happen if <code>Shutdown</code> is called on the thread itself.

=== What about "native" event queues? ===
The main thread where UI events are processed and the socket transport thread will use the observer interface defined by <code>nsIThreadInternal</code>. The main thread will interact with the "native" event system during calls to <code>ProcessNextEvent</code> and <code>Dispatch</code>. Likewise, the socket transport thread will similarly need to poll sockets and perform I/O operations. By observing calls to <code>ProcessNextEvent</code>, observers can wait on a native event queue (or poll on a set of file descriptors) instead of waiting on the thread's internal event queue monitor. When they observe a call to <code>Dispatch</code>, they can use whatever mechanism is appropriate to unblock the thread that is waiting on the native event queue.

=== How do synchronous events work? ===

When <code>Dispatch(event, DISPATCH_SYNC)</code> is called on a <code>nsIEventTarget</code>, it first checks to see if the current thread is the same as the thread where the event would be run. If it is, then it just runs the event directly without queuing it up. However, if not, then it must queue the event to be run when the dispatch target next processes its events. To avoid returning to the caller immediately, the method gets the current thread and calls its <code>ProcessNextEvent</code> method in a loop until it receives acknowledgement that the queued event has been run.

== Development ==

Development is occuring on the THREADS_20060307_BRANCH. See also {{bug|326273}}.

== Comments ==

=== biesi: ===
* What happens if shutdown is called while an event is being processed? I assume that this event will be processed to its end, no further events are accepted, and then the thread is shut down. right?
** What happens to events that were already dispatched to this thread, but not run?
* Is it a good idea to allow other events to run on the current thread while in dispatch?
* Who is expected to call ProcessNextEvent?

==== darin: ====
* When asked to shutdown, a thread would finish dispatching all queued events, and refuse to accept any new events. Once all queued events run to completion, the thread would terminate. This is consistent with how event queues work today.
* If you are sync dispatching, then it is necessary to pump events on the calling thread or else you could end up in a dead-lock situation. For example, if thread A sync dispatches an event to thread B, which cannot complete its job without dispatching an event back to thread A, then the system will dead-lock unless thread A continues to dispatch pending events.
* <code>ProcessNextEvent</code> may be called by anybody that wishes to implement the concept of a "modal event loop." For example, XMLHttpRequest (in sync configuration) would sit in a loop calling <code>ProcessNextEvent</code> while waiting for the underlying HTTP transaction to complete. The key difference between <code>ProcessNextEvent</code> and <code>nsIEventQueue::ProcessPendingEvents</code> is that <code>ProcessNextEvent</code>, when called on the UI thread, will process UI events as well. And, it will also wait (block the thread of execution) if there are no UI events or pending <code>nsIRunnable</code> events.

=== dbaron: ===
So mrbkap was telling me at lunch about what's essentially the third bullet point of your comment to biesi above -- that you're making the concept of "modal event loop" even more powerful. This actually scares me a good bit, because these modal event loops happen within another event -- an event that may have state on the stack (e.g., |this| parameters) that could be destroyed by the processing of further events, or may have posted events that rely on the event completing. I really don't like the mix of programming models here that makes it very hard to write robust code, and I wish we could avoid this whole concept altogether rather than making it even more powerful, and thus more dangerous. We already have crashes where frame trees get destroyed while processing an event that are related to the Windows API's way of doing the same thing, though (for, e.g., a DestroyWindow call or whatever it's called).

==== darin: ====
Yup, I'm aware of that issue. In fact, the problem already exists today. There are some places in the code where WaitPLEvent + HandleEvent are called in a loop waiting for an event to process. That bypasses PL_ProcessPendingEvents recursion restriction. PopThreadEventQueue does not behave as you would expect either. It can cause ProcessPendingEvents to run for all but the PLEventQueue that is the subject of the current call to PL_ProcessPendingEvents on the stack. That defeats the purpose of the nested event queue in the first place.

The problem you describe with layout events also occurs for nsIStreamListener implementations. It would be really wierd if OnDataAvailable were called recursively, or if OnDataAvailable were called while the consumer is calling nsIChannel::AsyncOpen. These specific problems are dealt with in nsBaseChannel.cpp by temporarily suspending the channel during callbacks. That suppresses recusive stream listener calls.

Do you have a suggestion that would allow us to prevent this problem? Is there a better way to make XMLHttpRequest.send, document.load, window.alert, etc. appear modal to the calling Javascript?

For C++ consumers, we'd have to basically eliminate modal dialogs altogether to avoid this problem. Today, we have bugs where downloads stall and get disconnected all because the browser popped up a modal dialog and the dialog was not closed promptly enough by the user. That's just unacceptable. And, nsIPromptService is frozen.

I think the answer is to be careful about making callbacks across XPCOM boundaries where event queues may be pumped. Maybe the layout code needs to unwind the stack more before allowing such callbacks to happen so that it can be sure that event processing won't be the end of the world.

dbaron: Also, with the new push/popEventQueue API defined on nsIThreadInternal, it is possible to suppress event dispatch for a particular scope. That is needed to implement synchronous XPCOM proxy calls. I'm assuming that any proper use of synchronous XPCOM proxy calls will be one that completes relatively quickly so as to negate the effects of locking up the browser. We should probably be very careful about calling PushEventQueue on the main thread, where it would potentially disrupt the browser UI. Native events would still be dispatched as always, but without application level events, the UI isn't very useful.

XPCOM:nsIThreadManager

2006-05-05T06:57:18Z

Darin: /* nsIThread */

In a world without nested event queues, the concept of a thread and an event queue merge...

== Interfaces ==
=== nsIThreadManager ===
[scriptable, uuid(...)]
interface nsIThreadManager : nsISupports {
/**
* Create a new thread (a global, user PRThread). Currently, flags is
* an unused parameter, that must be 0.
*/
nsIThread newThread(in unsigned long flags);
 
/**
* Get the nsIThread object (if any) corresponding to the given PRThread.
* This method returns null if there is no corresponding nsIThread.
*/
[noscript] nsIThread getThreadFromPRThread(in PRThread thread);
 
/**
* Get the main thread.
*/
readonly attribute nsIThread mainThread;
 
/**
* Get the current thread.
*/
readonly attribute nsIThread currentThread;
 
/**
* This attribute is true if the calling thread is the main thread of the
* application process.
*/
readonly attribute boolean isMainThread;
};

=== nsIEventTarget ===
[scriptable, uuid(...)]
interface nsIEventTarget : nsISupports {
/**
* Dispatch an event to the target. This function may be called from any
* thread. If flags specifies DISPATCH_SYNC, then the dispatch method
* will not return until the event has been processed. NOTE: Calling
* dispatch with DISPATCH_SYNC, may have the side-effect of running other
* events on the current thread while waiting for the given event to run
* to completion. This function is thread-safe and re-entrant.
*/
void dispatch(in nsIRunnable event, in unsigned long flags);
const unsigned long DISPATCH_NORMAL = 0;
const unsigned long DISPATCH_SYNC = 1;
 
/**
* Returns true if events dispatched to this target will run on the
* current thread (i.e., the thread calling this method).
*/
boolean isOnCurrentThread();
};
 
%{C++
// convenient aliases:
#define NS_DISPATCH_NORMAL nsIEventTarget::DISPATCH_NORMAL
#define NS_DISPATCH_SYNC nsIEventTarget::DISPATCH_SYNC
%}

=== nsIThread ===
[scriptable, uuid(...)]
interface nsIThread : nsIEventTarget {
/**
* Returns the PRThread object corresponding to this nsIThread.
*/
[noscript] readonly attribute PRThread PRThread;
 
/**
* Shutdown the thread. This method may not be executed from the thread
* itself. Instead, it is meant to be executed from another thread (usually
* the thread that created this thread). When this function returns, the
* thread will be shutdown, and it will no longer be possible to dispatch
* events to the thread.
*/
void shutdown();
 
/**
* Returns true if this thread has one or more pending events.
*/
boolean hasPendingEvents();
 
/**
* Process the next event. If there are no pending events, then this
* method may wait -- provided mayWait is true -- until an event is
* dispatched to this thread. This method is re-entrant but may only be
* called if this thread is the current thread.
*
* @return A boolean value that is "true" if an event was processed.
*/
boolean processNextEvent(in boolean mayWait);
};

=== nsIThreadInternal ===
[scriptable, uuid(...)]
interface nsIThreadInternal : nsIThread {
/**
* Get/set an observer for this thread (may be null). This attribute may
* be read from any thread, but must only be set on the thread corresponding
* to this thread object.
*/
attribute nsIThreadObserver observer;
 
/**
* This method causes any events currently enqueued on the thread to be
* suppressed until PopEventQueue is called. Additionally, any new events
* dispatched to the thread will only be processed if they are accepted by
* the given filter. If the filter is null, then new events are accepted.
* Calls to PushEventQueue may be nested and must each be paired with a call
* to PopEventQueue in order to restore the original state of the thread.
*/
void pushEventQueue(in nsIThreadEventFilter filter);
 
/**
* Revert a call to PushEventQueue. When an event queue is popped, any
* events remaining in the queue are appended to the elder queue.
*/
void popEventQueue();
};

=== nsIThreadObserver ===
[scriptable, uuid(...)]
interface nsIThreadObserver : nsISupports {
/**
* This method is called after an event has been dispatched to the thread.
* This method may be called from any thread.
*/
void onDispatchedEvent(in nsIThreadInternal thread);
 
/**
* This method is called (from nsIThread::ProcessNextEvent) before an event
* is processed. This method is only called on the target thread.
*
* @param thread
* The thread being asked to process another event.
* @param mayWait
* Indicates whether or not the method is allowed to block the calling
* thread. For example, this parameter is false during thread shutdown.
* @param recursionDepth
* Indicates the number of calls to ProcessNextEvent on the call stack
* in addition to the current call.
*/
void onProcessNextEvent(in nsIThreadInternal thread, in boolean mayWait,
in unsigned long recursionDepth);
};

=== nsIThreadEventFilter ===
[scriptable, uuid(...)]
interface nsIThreadEventFilter : nsISupports {
/**
* This method is called to determine whether or not an event may be accepted
* by a "nested" event queue (see nsIThreadInternal::PushEventQueue).
*
* WARNING: This method must not make any calls on the thread object.
*/
[notxpcom] boolean AcceptEvent(in nsIRunnable event);
};

=== nsIThreadPool ===
[scriptable, uuid(...)]
interface nsIThreadPool : nsIEventTarget
{
/**
* Shutdown the thread pool. This method may not be executed from any
* thread in the thread pool. Instead, it is meant to be executed from
* another thread (usually the thread that created this thread pool).
* When this function returns, the thread pool and all of its threads will
* be shutdown, and it will no longer be possible to dispatch tasks to the
* thread pool.
*/
void shutdown()
 
/**
* Get/set the maximum number of threads allowed at one time in this pool.
*/
attribute unsigned long threadLimit;
 
/**
* Get/set the maximum number of idle threads kept alive.
*/
attribute unsigned long idleThreadLimit;
 
/**
* Get/set the amount of time in milliseconds before an idle thread is
* destroyed.
*/
attribute unsigned long idleThreadTimeout;
};

== C++ Utilities ==

=== Functions ===
nsThreadUtils.h defines the following helper functions:

/**
* Create a new thread.
*
* @param name
* The name of the thread (must be unique) or the empty string to
* create an anonymous thread.
* @param event
* The initial event to run on this thread. This can be null.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_NewThread(const nsACString &name, nsIRunnable *event,
nsIThread **result);
 
/**
* Get a reference to the current thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetCurrentThread(nsIThread **result);
 
/**
* Get a reference to the main thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetMainThread(nsIThread **result);
 
/**
* Get a reference to the thread with the given name.
*
* @param name
* The name of the requested thread. Must be non-empty.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetThread(const nsACString &name, nsIThread **result);
 
/**
* Test to see if the current thread is the main thread.
*
* @returns PR_TRUE if the current thread is the main thread, and PR_FALSE
* otherwise.
*/
PRBool NS_IsMainThread();
 
/**
* Dispatch the given event to the current thread.
*
* @param event
* The event to dispatch.
*/
NS_METHOD NS_DispatchToCurrentThread(nsIRunnable *event);
 
/**
* Dispatch the given event to the main thread.
*
* @param event
* The event to dispatch.
* @param dispatchFlags
* The flags to pass to the main thread's dispatch method.
*/
NS_METHOD NS_DispatchToMainThread(nsIRunnable *event,
PRUint32 dispatchFlags = NS_DISPATCH_NORMAL);
 
/**
* Process all pending events for the given thread before returning. This
* method simply calls ProcessNextEvent on the thread while HasPendingEvents
* continues to return true and the time spent in NS_ProcessPendingEvents
* does not exceed the given timeout value.
*
* @param thread
* The thread object for which to process pending events. If null,
* then events will be processed for the current thread.
* @param timeout
* The maximum number of milliseconds to spend processing pending
* events. Events are not pre-empted to honor this timeout. Rather,
* the timeout value is simply used to determine whether or not to
* process another event. Pass PR_INTERVAL_NO_TIMEOUT to specify no
* timeout.
*/
NS_METHOD NS_ProcessPendingEvents(nsIThread *thread = nsnull,
PRIntervalTime timeout = PR_INTERVAL_NO_TIMEOUT);

=== nsCOMPtr helpers ===
The following nsCOMPtr helpers are defined to simplify things further:

already_AddRefed<nsIThread> do_GetCurrentThread();
 
already_AddRefed<nsIThread> do_GetMainThread();
 
already_AddRefed<nsIThread> do_GetThread(const nsACString &name);

=== nsRunnable ===
The class <code>nsRunnable</code> is also defined to simplify the
implementation of new event types. For example, to define a new
event all you need to do is write code like this:

class MyEvent : public nsRunnable {
public:
MyEvent(... params ...);
 
NS_IMETHOD Run() {
// do stuff
return NS_OK;
}
};

Dispatching <code>MyEvent</code> is then as simple as:

nsCOMPtr<nsIThread> thread = do_GetCurrentThread();
NS_ENSURE_STATE(thread);
 
nsCOMPtr<nsIRunnable> event = new MyEvent();
NS_ENSURE_STATE(event);
 
thread->Dispatch(event, NS_DISPATCH_NORMAL);

== From JS ==

=== Event Dispatch ===
Threads and Thread Manager implement <code>nsIClassInfo</code>:

function MyEvent() {
}
MyEvent.prototype = {
QueryInterface: function(iid) {
if (iid.equals(Components.interfaces.nsIRunnable) ||
iid.equals(Components.interfaces.nsISupports))
return this;
throw Components.results.NS_ERROR_NO_INTERFACE;
},
run: function() {
// do stuff
}
};
 
function DispatchMyEvent() {
var target =
Components.classes["@mozilla.org/thread-manager;1"].
getService().currentThread;
 
target.dispatch(new MyEvent(), target.DISPATCH_NORMAL);
}

== Remarks ==

* Thread priority for native threads can be exposed via <code>nsISupportsPriority</code>.
* Thread names must be unique.
* The Necko I/O thread pool will be replaced by a generic thread pool implementation provided by XPCOM. The thread pool will implement <code>nsIEventTarget</code>, allowing events to be dispatched to any thread in the thread pool. We may even wish to define a <code>nsIThreadPool</code> interface and have it implement that as well. That interface would define methods to adjust the limits on the number of threads in the thread pool and so on.
* We will need an alternative for <code>nsIEventQueue::RevokeEvents</code>. There are several possibilities: (1) make consumers hold references to their nsIRunnable's so they can "disconnect" them manually, or (2) expose an enumeration/visitor API that allows consumers to walk the list of pending tasks and remove arbitrary tasks. I'm not sure what is best yet. The first option or something similar based on weak references is probably best as it avoids the costly O(n) <code>RevokeEvents</code> call.
* The following interfaces/classes would go away or be modified heavily: <code>nsIEventQueue</code>, <code>nsIEventQueueService</code>, <code>nsIEventTarget</code>, <code>nsIThread</code>, <code>PLEvent</code>.
* Issue: Perhaps we should support calling <code>nsIThread::Shutdown</code> from the thread itself. That would probably have to be implemented by posting an event to the main thread, and having that thread call shutdown. However, <code>Shutdown</code> also has the property that it does not return until the thread is gone. That obvious can't happen if <code>Shutdown</code> is called on the thread itself.

=== What about "native" event queues? ===
The main thread where UI events are processed and the socket transport thread will use the observer interface defined by <code>nsIThreadInternal</code>. The main thread will interact with the "native" event system during calls to <code>ProcessNextEvent</code> and <code>Dispatch</code>. Likewise, the socket transport thread will similarly need to poll sockets and perform I/O operations. By observing calls to <code>ProcessNextEvent</code>, observers can wait on a native event queue (or poll on a set of file descriptors) instead of waiting on the thread's internal event queue monitor. When they observe a call to <code>Dispatch</code>, they can use whatever mechanism is appropriate to unblock the thread that is waiting on the native event queue.

=== How do synchronous events work? ===

When <code>Dispatch(event, DISPATCH_SYNC)</code> is called on a <code>nsIEventTarget</code>, it first checks to see if the current thread is the same as the thread where the event would be run. If it is, then it just runs the event directly without queuing it up. However, if not, then it must queue the event to be run when the dispatch target next processes its events. To avoid returning to the caller immediately, the method gets the current thread and calls its <code>ProcessNextEvent</code> method in a loop until it receives acknowledgement that the queued event has been run.

== Development ==

Development is occuring on the THREADS_20060307_BRANCH. See also {{bug|326273}}.

== Comments ==

=== biesi: ===
* What happens if shutdown is called while an event is being processed? I assume that this event will be processed to its end, no further events are accepted, and then the thread is shut down. right?
** What happens to events that were already dispatched to this thread, but not run?
* Is it a good idea to allow other events to run on the current thread while in dispatch?
* Who is expected to call ProcessNextEvent?

==== darin: ====
* When asked to shutdown, a thread would finish dispatching all queued events, and refuse to accept any new events. Once all queued events run to completion, the thread would terminate. This is consistent with how event queues work today.
* If you are sync dispatching, then it is necessary to pump events on the calling thread or else you could end up in a dead-lock situation. For example, if thread A sync dispatches an event to thread B, which cannot complete its job without dispatching an event back to thread A, then the system will dead-lock unless thread A continues to dispatch pending events.
* <code>ProcessNextEvent</code> may be called by anybody that wishes to implement the concept of a "modal event loop." For example, XMLHttpRequest (in sync configuration) would sit in a loop calling <code>ProcessNextEvent</code> while waiting for the underlying HTTP transaction to complete. The key difference between <code>ProcessNextEvent</code> and <code>nsIEventQueue::ProcessPendingEvents</code> is that <code>ProcessNextEvent</code>, when called on the UI thread, will process UI events as well. And, it will also wait (block the thread of execution) if there are no UI events or pending <code>nsIRunnable</code> events.

=== dbaron: ===
So mrbkap was telling me at lunch about what's essentially the third bullet point of your comment to biesi above -- that you're making the concept of "modal event loop" even more powerful. This actually scares me a good bit, because these modal event loops happen within another event -- an event that may have state on the stack (e.g., |this| parameters) that could be destroyed by the processing of further events, or may have posted events that rely on the event completing. I really don't like the mix of programming models here that makes it very hard to write robust code, and I wish we could avoid this whole concept altogether rather than making it even more powerful, and thus more dangerous. We already have crashes where frame trees get destroyed while processing an event that are related to the Windows API's way of doing the same thing, though (for, e.g., a DestroyWindow call or whatever it's called).

==== darin: ====
Yup, I'm aware of that issue. In fact, the problem already exists today. There are some places in the code where WaitPLEvent + HandleEvent are called in a loop waiting for an event to process. That bypasses PL_ProcessPendingEvents recursion restriction. PopThreadEventQueue does not behave as you would expect either. It can cause ProcessPendingEvents to run for all but the PLEventQueue that is the subject of the current call to PL_ProcessPendingEvents on the stack. That defeats the purpose of the nested event queue in the first place.

The problem you describe with layout events also occurs for nsIStreamListener implementations. It would be really wierd if OnDataAvailable were called recursively, or if OnDataAvailable were called while the consumer is calling nsIChannel::AsyncOpen. These specific problems are dealt with in nsBaseChannel.cpp by temporarily suspending the channel during callbacks. That suppresses recusive stream listener calls.

Do you have a suggestion that would allow us to prevent this problem? Is there a better way to make XMLHttpRequest.send, document.load, window.alert, etc. appear modal to the calling Javascript?

For C++ consumers, we'd have to basically eliminate modal dialogs altogether to avoid this problem. Today, we have bugs where downloads stall and get disconnected all because the browser popped up a modal dialog and the dialog was not closed promptly enough by the user. That's just unacceptable. And, nsIPromptService is frozen.

I think the answer is to be careful about making callbacks across XPCOM boundaries where event queues may be pumped. Maybe the layout code needs to unwind the stack more before allowing such callbacks to happen so that it can be sure that event processing won't be the end of the world.

dbaron: Also, with the new push/popEventQueue API defined on nsIThreadInternal, it is possible to suppress event dispatch for a particular scope. That is needed to implement synchronous XPCOM proxy calls. I'm assuming that any proper use of synchronous XPCOM proxy calls will be one that completes relatively quickly so as to negate the effects of locking up the browser. We should probably be very careful about calling PushEventQueue on the main thread, where it would potentially disrupt the browser UI. Native events would still be dispatched as always, but without application level events, the UI isn't very useful.

XPCOM:nsIThreadManager

2006-05-05T06:56:58Z

Darin: /* nsIThread */

In a world without nested event queues, the concept of a thread and an event queue merge...

== Interfaces ==
=== nsIThreadManager ===
[scriptable, uuid(...)]
interface nsIThreadManager : nsISupports {
/**
* Create a new thread (a global, user PRThread). Currently, flags is
* an unused parameter, that must be 0.
*/
nsIThread newThread(in unsigned long flags);
 
/**
* Get the nsIThread object (if any) corresponding to the given PRThread.
* This method returns null if there is no corresponding nsIThread.
*/
[noscript] nsIThread getThreadFromPRThread(in PRThread thread);
 
/**
* Get the main thread.
*/
readonly attribute nsIThread mainThread;
 
/**
* Get the current thread.
*/
readonly attribute nsIThread currentThread;
 
/**
* This attribute is true if the calling thread is the main thread of the
* application process.
*/
readonly attribute boolean isMainThread;
};

=== nsIEventTarget ===
[scriptable, uuid(...)]
interface nsIEventTarget : nsISupports {
/**
* Dispatch an event to the target. This function may be called from any
* thread. If flags specifies DISPATCH_SYNC, then the dispatch method
* will not return until the event has been processed. NOTE: Calling
* dispatch with DISPATCH_SYNC, may have the side-effect of running other
* events on the current thread while waiting for the given event to run
* to completion. This function is thread-safe and re-entrant.
*/
void dispatch(in nsIRunnable event, in unsigned long flags);
const unsigned long DISPATCH_NORMAL = 0;
const unsigned long DISPATCH_SYNC = 1;
 
/**
* Returns true if events dispatched to this target will run on the
* current thread (i.e., the thread calling this method).
*/
boolean isOnCurrentThread();
};
 
%{C++
// convenient aliases:
#define NS_DISPATCH_NORMAL nsIEventTarget::DISPATCH_NORMAL
#define NS_DISPATCH_SYNC nsIEventTarget::DISPATCH_SYNC
%}

=== nsIThread ===
[scriptable, uuid(...)]
interface nsIThread : nsIEventTarget {
/**
* Returns the PRThread object corresponding to this nsIThread.
*/
[noscript] PRThread getPRThread();
 
/**
* Shutdown the thread. This method may not be executed from the thread
* itself. Instead, it is meant to be executed from another thread (usually
* the thread that created this thread). When this function returns, the
* thread will be shutdown, and it will no longer be possible to dispatch
* events to the thread.
*/
void shutdown();
 
/**
* Returns true if this thread has one or more pending events.
*/
boolean hasPendingEvents();
 
/**
* Process the next event. If there are no pending events, then this
* method may wait -- provided mayWait is true -- until an event is
* dispatched to this thread. This method is re-entrant but may only be
* called if this thread is the current thread.
*
* @return A boolean value that is "true" if an event was processed.
*/
boolean processNextEvent(in boolean mayWait);
};

=== nsIThreadInternal ===
[scriptable, uuid(...)]
interface nsIThreadInternal : nsIThread {
/**
* Get/set an observer for this thread (may be null). This attribute may
* be read from any thread, but must only be set on the thread corresponding
* to this thread object.
*/
attribute nsIThreadObserver observer;
 
/**
* This method causes any events currently enqueued on the thread to be
* suppressed until PopEventQueue is called. Additionally, any new events
* dispatched to the thread will only be processed if they are accepted by
* the given filter. If the filter is null, then new events are accepted.
* Calls to PushEventQueue may be nested and must each be paired with a call
* to PopEventQueue in order to restore the original state of the thread.
*/
void pushEventQueue(in nsIThreadEventFilter filter);
 
/**
* Revert a call to PushEventQueue. When an event queue is popped, any
* events remaining in the queue are appended to the elder queue.
*/
void popEventQueue();
};

=== nsIThreadObserver ===
[scriptable, uuid(...)]
interface nsIThreadObserver : nsISupports {
/**
* This method is called after an event has been dispatched to the thread.
* This method may be called from any thread.
*/
void onDispatchedEvent(in nsIThreadInternal thread);
 
/**
* This method is called (from nsIThread::ProcessNextEvent) before an event
* is processed. This method is only called on the target thread.
*
* @param thread
* The thread being asked to process another event.
* @param mayWait
* Indicates whether or not the method is allowed to block the calling
* thread. For example, this parameter is false during thread shutdown.
* @param recursionDepth
* Indicates the number of calls to ProcessNextEvent on the call stack
* in addition to the current call.
*/
void onProcessNextEvent(in nsIThreadInternal thread, in boolean mayWait,
in unsigned long recursionDepth);
};

=== nsIThreadEventFilter ===
[scriptable, uuid(...)]
interface nsIThreadEventFilter : nsISupports {
/**
* This method is called to determine whether or not an event may be accepted
* by a "nested" event queue (see nsIThreadInternal::PushEventQueue).
*
* WARNING: This method must not make any calls on the thread object.
*/
[notxpcom] boolean AcceptEvent(in nsIRunnable event);
};

=== nsIThreadPool ===
[scriptable, uuid(...)]
interface nsIThreadPool : nsIEventTarget
{
/**
* Shutdown the thread pool. This method may not be executed from any
* thread in the thread pool. Instead, it is meant to be executed from
* another thread (usually the thread that created this thread pool).
* When this function returns, the thread pool and all of its threads will
* be shutdown, and it will no longer be possible to dispatch tasks to the
* thread pool.
*/
void shutdown()
 
/**
* Get/set the maximum number of threads allowed at one time in this pool.
*/
attribute unsigned long threadLimit;
 
/**
* Get/set the maximum number of idle threads kept alive.
*/
attribute unsigned long idleThreadLimit;
 
/**
* Get/set the amount of time in milliseconds before an idle thread is
* destroyed.
*/
attribute unsigned long idleThreadTimeout;
};

== C++ Utilities ==

=== Functions ===
nsThreadUtils.h defines the following helper functions:

/**
* Create a new thread.
*
* @param name
* The name of the thread (must be unique) or the empty string to
* create an anonymous thread.
* @param event
* The initial event to run on this thread. This can be null.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_NewThread(const nsACString &name, nsIRunnable *event,
nsIThread **result);
 
/**
* Get a reference to the current thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetCurrentThread(nsIThread **result);
 
/**
* Get a reference to the main thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetMainThread(nsIThread **result);
 
/**
* Get a reference to the thread with the given name.
*
* @param name
* The name of the requested thread. Must be non-empty.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetThread(const nsACString &name, nsIThread **result);
 
/**
* Test to see if the current thread is the main thread.
*
* @returns PR_TRUE if the current thread is the main thread, and PR_FALSE
* otherwise.
*/
PRBool NS_IsMainThread();
 
/**
* Dispatch the given event to the current thread.
*
* @param event
* The event to dispatch.
*/
NS_METHOD NS_DispatchToCurrentThread(nsIRunnable *event);
 
/**
* Dispatch the given event to the main thread.
*
* @param event
* The event to dispatch.
* @param dispatchFlags
* The flags to pass to the main thread's dispatch method.
*/
NS_METHOD NS_DispatchToMainThread(nsIRunnable *event,
PRUint32 dispatchFlags = NS_DISPATCH_NORMAL);
 
/**
* Process all pending events for the given thread before returning. This
* method simply calls ProcessNextEvent on the thread while HasPendingEvents
* continues to return true and the time spent in NS_ProcessPendingEvents
* does not exceed the given timeout value.
*
* @param thread
* The thread object for which to process pending events. If null,
* then events will be processed for the current thread.
* @param timeout
* The maximum number of milliseconds to spend processing pending
* events. Events are not pre-empted to honor this timeout. Rather,
* the timeout value is simply used to determine whether or not to
* process another event. Pass PR_INTERVAL_NO_TIMEOUT to specify no
* timeout.
*/
NS_METHOD NS_ProcessPendingEvents(nsIThread *thread = nsnull,
PRIntervalTime timeout = PR_INTERVAL_NO_TIMEOUT);

=== nsCOMPtr helpers ===
The following nsCOMPtr helpers are defined to simplify things further:

already_AddRefed<nsIThread> do_GetCurrentThread();
 
already_AddRefed<nsIThread> do_GetMainThread();
 
already_AddRefed<nsIThread> do_GetThread(const nsACString &name);

=== nsRunnable ===
The class <code>nsRunnable</code> is also defined to simplify the
implementation of new event types. For example, to define a new
event all you need to do is write code like this:

class MyEvent : public nsRunnable {
public:
MyEvent(... params ...);
 
NS_IMETHOD Run() {
// do stuff
return NS_OK;
}
};

Dispatching <code>MyEvent</code> is then as simple as:

nsCOMPtr<nsIThread> thread = do_GetCurrentThread();
NS_ENSURE_STATE(thread);
 
nsCOMPtr<nsIRunnable> event = new MyEvent();
NS_ENSURE_STATE(event);
 
thread->Dispatch(event, NS_DISPATCH_NORMAL);

== From JS ==

=== Event Dispatch ===
Threads and Thread Manager implement <code>nsIClassInfo</code>:

function MyEvent() {
}
MyEvent.prototype = {
QueryInterface: function(iid) {
if (iid.equals(Components.interfaces.nsIRunnable) ||
iid.equals(Components.interfaces.nsISupports))
return this;
throw Components.results.NS_ERROR_NO_INTERFACE;
},
run: function() {
// do stuff
}
};
 
function DispatchMyEvent() {
var target =
Components.classes["@mozilla.org/thread-manager;1"].
getService().currentThread;
 
target.dispatch(new MyEvent(), target.DISPATCH_NORMAL);
}

== Remarks ==

* Thread priority for native threads can be exposed via <code>nsISupportsPriority</code>.
* Thread names must be unique.
* The Necko I/O thread pool will be replaced by a generic thread pool implementation provided by XPCOM. The thread pool will implement <code>nsIEventTarget</code>, allowing events to be dispatched to any thread in the thread pool. We may even wish to define a <code>nsIThreadPool</code> interface and have it implement that as well. That interface would define methods to adjust the limits on the number of threads in the thread pool and so on.
* We will need an alternative for <code>nsIEventQueue::RevokeEvents</code>. There are several possibilities: (1) make consumers hold references to their nsIRunnable's so they can "disconnect" them manually, or (2) expose an enumeration/visitor API that allows consumers to walk the list of pending tasks and remove arbitrary tasks. I'm not sure what is best yet. The first option or something similar based on weak references is probably best as it avoids the costly O(n) <code>RevokeEvents</code> call.
* The following interfaces/classes would go away or be modified heavily: <code>nsIEventQueue</code>, <code>nsIEventQueueService</code>, <code>nsIEventTarget</code>, <code>nsIThread</code>, <code>PLEvent</code>.
* Issue: Perhaps we should support calling <code>nsIThread::Shutdown</code> from the thread itself. That would probably have to be implemented by posting an event to the main thread, and having that thread call shutdown. However, <code>Shutdown</code> also has the property that it does not return until the thread is gone. That obvious can't happen if <code>Shutdown</code> is called on the thread itself.

=== What about "native" event queues? ===
The main thread where UI events are processed and the socket transport thread will use the observer interface defined by <code>nsIThreadInternal</code>. The main thread will interact with the "native" event system during calls to <code>ProcessNextEvent</code> and <code>Dispatch</code>. Likewise, the socket transport thread will similarly need to poll sockets and perform I/O operations. By observing calls to <code>ProcessNextEvent</code>, observers can wait on a native event queue (or poll on a set of file descriptors) instead of waiting on the thread's internal event queue monitor. When they observe a call to <code>Dispatch</code>, they can use whatever mechanism is appropriate to unblock the thread that is waiting on the native event queue.

=== How do synchronous events work? ===

When <code>Dispatch(event, DISPATCH_SYNC)</code> is called on a <code>nsIEventTarget</code>, it first checks to see if the current thread is the same as the thread where the event would be run. If it is, then it just runs the event directly without queuing it up. However, if not, then it must queue the event to be run when the dispatch target next processes its events. To avoid returning to the caller immediately, the method gets the current thread and calls its <code>ProcessNextEvent</code> method in a loop until it receives acknowledgement that the queued event has been run.

== Development ==

Development is occuring on the THREADS_20060307_BRANCH. See also {{bug|326273}}.

== Comments ==

=== biesi: ===
* What happens if shutdown is called while an event is being processed? I assume that this event will be processed to its end, no further events are accepted, and then the thread is shut down. right?
** What happens to events that were already dispatched to this thread, but not run?
* Is it a good idea to allow other events to run on the current thread while in dispatch?
* Who is expected to call ProcessNextEvent?

==== darin: ====
* When asked to shutdown, a thread would finish dispatching all queued events, and refuse to accept any new events. Once all queued events run to completion, the thread would terminate. This is consistent with how event queues work today.
* If you are sync dispatching, then it is necessary to pump events on the calling thread or else you could end up in a dead-lock situation. For example, if thread A sync dispatches an event to thread B, which cannot complete its job without dispatching an event back to thread A, then the system will dead-lock unless thread A continues to dispatch pending events.
* <code>ProcessNextEvent</code> may be called by anybody that wishes to implement the concept of a "modal event loop." For example, XMLHttpRequest (in sync configuration) would sit in a loop calling <code>ProcessNextEvent</code> while waiting for the underlying HTTP transaction to complete. The key difference between <code>ProcessNextEvent</code> and <code>nsIEventQueue::ProcessPendingEvents</code> is that <code>ProcessNextEvent</code>, when called on the UI thread, will process UI events as well. And, it will also wait (block the thread of execution) if there are no UI events or pending <code>nsIRunnable</code> events.

=== dbaron: ===
So mrbkap was telling me at lunch about what's essentially the third bullet point of your comment to biesi above -- that you're making the concept of "modal event loop" even more powerful. This actually scares me a good bit, because these modal event loops happen within another event -- an event that may have state on the stack (e.g., |this| parameters) that could be destroyed by the processing of further events, or may have posted events that rely on the event completing. I really don't like the mix of programming models here that makes it very hard to write robust code, and I wish we could avoid this whole concept altogether rather than making it even more powerful, and thus more dangerous. We already have crashes where frame trees get destroyed while processing an event that are related to the Windows API's way of doing the same thing, though (for, e.g., a DestroyWindow call or whatever it's called).

==== darin: ====
Yup, I'm aware of that issue. In fact, the problem already exists today. There are some places in the code where WaitPLEvent + HandleEvent are called in a loop waiting for an event to process. That bypasses PL_ProcessPendingEvents recursion restriction. PopThreadEventQueue does not behave as you would expect either. It can cause ProcessPendingEvents to run for all but the PLEventQueue that is the subject of the current call to PL_ProcessPendingEvents on the stack. That defeats the purpose of the nested event queue in the first place.

The problem you describe with layout events also occurs for nsIStreamListener implementations. It would be really wierd if OnDataAvailable were called recursively, or if OnDataAvailable were called while the consumer is calling nsIChannel::AsyncOpen. These specific problems are dealt with in nsBaseChannel.cpp by temporarily suspending the channel during callbacks. That suppresses recusive stream listener calls.

Do you have a suggestion that would allow us to prevent this problem? Is there a better way to make XMLHttpRequest.send, document.load, window.alert, etc. appear modal to the calling Javascript?

For C++ consumers, we'd have to basically eliminate modal dialogs altogether to avoid this problem. Today, we have bugs where downloads stall and get disconnected all because the browser popped up a modal dialog and the dialog was not closed promptly enough by the user. That's just unacceptable. And, nsIPromptService is frozen.

I think the answer is to be careful about making callbacks across XPCOM boundaries where event queues may be pumped. Maybe the layout code needs to unwind the stack more before allowing such callbacks to happen so that it can be sure that event processing won't be the end of the world.

dbaron: Also, with the new push/popEventQueue API defined on nsIThreadInternal, it is possible to suppress event dispatch for a particular scope. That is needed to implement synchronous XPCOM proxy calls. I'm assuming that any proper use of synchronous XPCOM proxy calls will be one that completes relatively quickly so as to negate the effects of locking up the browser. We should probably be very careful about calling PushEventQueue on the main thread, where it would potentially disrupt the browser UI. Native events would still be dispatched as always, but without application level events, the UI isn't very useful.

XPCOM:nsIThreadManager

2006-05-05T06:56:42Z

Darin: /* nsIThreadManager */

In a world without nested event queues, the concept of a thread and an event queue merge...

== Interfaces ==
=== nsIThreadManager ===
[scriptable, uuid(...)]
interface nsIThreadManager : nsISupports {
/**
* Create a new thread (a global, user PRThread). Currently, flags is
* an unused parameter, that must be 0.
*/
nsIThread newThread(in unsigned long flags);
 
/**
* Get the nsIThread object (if any) corresponding to the given PRThread.
* This method returns null if there is no corresponding nsIThread.
*/
[noscript] nsIThread getThreadFromPRThread(in PRThread thread);
 
/**
* Get the main thread.
*/
readonly attribute nsIThread mainThread;
 
/**
* Get the current thread.
*/
readonly attribute nsIThread currentThread;
 
/**
* This attribute is true if the calling thread is the main thread of the
* application process.
*/
readonly attribute boolean isMainThread;
};

=== nsIEventTarget ===
[scriptable, uuid(...)]
interface nsIEventTarget : nsISupports {
/**
* Dispatch an event to the target. This function may be called from any
* thread. If flags specifies DISPATCH_SYNC, then the dispatch method
* will not return until the event has been processed. NOTE: Calling
* dispatch with DISPATCH_SYNC, may have the side-effect of running other
* events on the current thread while waiting for the given event to run
* to completion. This function is thread-safe and re-entrant.
*/
void dispatch(in nsIRunnable event, in unsigned long flags);
const unsigned long DISPATCH_NORMAL = 0;
const unsigned long DISPATCH_SYNC = 1;
 
/**
* Returns true if events dispatched to this target will run on the
* current thread (i.e., the thread calling this method).
*/
boolean isOnCurrentThread();
};
 
%{C++
// convenient aliases:
#define NS_DISPATCH_NORMAL nsIEventTarget::DISPATCH_NORMAL
#define NS_DISPATCH_SYNC nsIEventTarget::DISPATCH_SYNC
%}

=== nsIThread ===
[scriptable, uuid(...)]
interface nsIThread : nsIEventTarget {
/**
* Returns the name of the thread, which may be empty if this thread is
* anonymous.
*/
readonly attribute ACString name;
 
/**
* Returns the PRThread object corresponding to this nsIThread.
*/
[noscript] PRThread getPRThread();
 
/**
* Shutdown the thread. This method may not be executed from the thread
* itself. Instead, it is meant to be executed from another thread (usually
* the thread that created this thread). When this function returns, the
* thread will be shutdown, and it will no longer be possible to dispatch
* events to the thread.
*/
void shutdown();
 
/**
* Returns true if this thread has one or more pending events.
*/
boolean hasPendingEvents();
 
/**
* Process the next event. If there are no pending events, then this
* method may wait -- provided mayWait is true -- until an event is
* dispatched to this thread. This method is re-entrant but may only be
* called if this thread is the current thread.
*
* @return A boolean value that is "true" if an event was processed.
*/
boolean processNextEvent(in boolean mayWait);
};

=== nsIThreadInternal ===
[scriptable, uuid(...)]
interface nsIThreadInternal : nsIThread {
/**
* Get/set an observer for this thread (may be null). This attribute may
* be read from any thread, but must only be set on the thread corresponding
* to this thread object.
*/
attribute nsIThreadObserver observer;
 
/**
* This method causes any events currently enqueued on the thread to be
* suppressed until PopEventQueue is called. Additionally, any new events
* dispatched to the thread will only be processed if they are accepted by
* the given filter. If the filter is null, then new events are accepted.
* Calls to PushEventQueue may be nested and must each be paired with a call
* to PopEventQueue in order to restore the original state of the thread.
*/
void pushEventQueue(in nsIThreadEventFilter filter);
 
/**
* Revert a call to PushEventQueue. When an event queue is popped, any
* events remaining in the queue are appended to the elder queue.
*/
void popEventQueue();
};

=== nsIThreadObserver ===
[scriptable, uuid(...)]
interface nsIThreadObserver : nsISupports {
/**
* This method is called after an event has been dispatched to the thread.
* This method may be called from any thread.
*/
void onDispatchedEvent(in nsIThreadInternal thread);
 
/**
* This method is called (from nsIThread::ProcessNextEvent) before an event
* is processed. This method is only called on the target thread.
*
* @param thread
* The thread being asked to process another event.
* @param mayWait
* Indicates whether or not the method is allowed to block the calling
* thread. For example, this parameter is false during thread shutdown.
* @param recursionDepth
* Indicates the number of calls to ProcessNextEvent on the call stack
* in addition to the current call.
*/
void onProcessNextEvent(in nsIThreadInternal thread, in boolean mayWait,
in unsigned long recursionDepth);
};

=== nsIThreadEventFilter ===
[scriptable, uuid(...)]
interface nsIThreadEventFilter : nsISupports {
/**
* This method is called to determine whether or not an event may be accepted
* by a "nested" event queue (see nsIThreadInternal::PushEventQueue).
*
* WARNING: This method must not make any calls on the thread object.
*/
[notxpcom] boolean AcceptEvent(in nsIRunnable event);
};

=== nsIThreadPool ===
[scriptable, uuid(...)]
interface nsIThreadPool : nsIEventTarget
{
/**
* Shutdown the thread pool. This method may not be executed from any
* thread in the thread pool. Instead, it is meant to be executed from
* another thread (usually the thread that created this thread pool).
* When this function returns, the thread pool and all of its threads will
* be shutdown, and it will no longer be possible to dispatch tasks to the
* thread pool.
*/
void shutdown()
 
/**
* Get/set the maximum number of threads allowed at one time in this pool.
*/
attribute unsigned long threadLimit;
 
/**
* Get/set the maximum number of idle threads kept alive.
*/
attribute unsigned long idleThreadLimit;
 
/**
* Get/set the amount of time in milliseconds before an idle thread is
* destroyed.
*/
attribute unsigned long idleThreadTimeout;
};

== C++ Utilities ==

=== Functions ===
nsThreadUtils.h defines the following helper functions:

/**
* Create a new thread.
*
* @param name
* The name of the thread (must be unique) or the empty string to
* create an anonymous thread.
* @param event
* The initial event to run on this thread. This can be null.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_NewThread(const nsACString &name, nsIRunnable *event,
nsIThread **result);
 
/**
* Get a reference to the current thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetCurrentThread(nsIThread **result);
 
/**
* Get a reference to the main thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetMainThread(nsIThread **result);
 
/**
* Get a reference to the thread with the given name.
*
* @param name
* The name of the requested thread. Must be non-empty.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetThread(const nsACString &name, nsIThread **result);
 
/**
* Test to see if the current thread is the main thread.
*
* @returns PR_TRUE if the current thread is the main thread, and PR_FALSE
* otherwise.
*/
PRBool NS_IsMainThread();
 
/**
* Dispatch the given event to the current thread.
*
* @param event
* The event to dispatch.
*/
NS_METHOD NS_DispatchToCurrentThread(nsIRunnable *event);
 
/**
* Dispatch the given event to the main thread.
*
* @param event
* The event to dispatch.
* @param dispatchFlags
* The flags to pass to the main thread's dispatch method.
*/
NS_METHOD NS_DispatchToMainThread(nsIRunnable *event,
PRUint32 dispatchFlags = NS_DISPATCH_NORMAL);
 
/**
* Process all pending events for the given thread before returning. This
* method simply calls ProcessNextEvent on the thread while HasPendingEvents
* continues to return true and the time spent in NS_ProcessPendingEvents
* does not exceed the given timeout value.
*
* @param thread
* The thread object for which to process pending events. If null,
* then events will be processed for the current thread.
* @param timeout
* The maximum number of milliseconds to spend processing pending
* events. Events are not pre-empted to honor this timeout. Rather,
* the timeout value is simply used to determine whether or not to
* process another event. Pass PR_INTERVAL_NO_TIMEOUT to specify no
* timeout.
*/
NS_METHOD NS_ProcessPendingEvents(nsIThread *thread = nsnull,
PRIntervalTime timeout = PR_INTERVAL_NO_TIMEOUT);

=== nsCOMPtr helpers ===
The following nsCOMPtr helpers are defined to simplify things further:

already_AddRefed<nsIThread> do_GetCurrentThread();
 
already_AddRefed<nsIThread> do_GetMainThread();
 
already_AddRefed<nsIThread> do_GetThread(const nsACString &name);

=== nsRunnable ===
The class <code>nsRunnable</code> is also defined to simplify the
implementation of new event types. For example, to define a new
event all you need to do is write code like this:

class MyEvent : public nsRunnable {
public:
MyEvent(... params ...);
 
NS_IMETHOD Run() {
// do stuff
return NS_OK;
}
};

Dispatching <code>MyEvent</code> is then as simple as:

nsCOMPtr<nsIThread> thread = do_GetCurrentThread();
NS_ENSURE_STATE(thread);
 
nsCOMPtr<nsIRunnable> event = new MyEvent();
NS_ENSURE_STATE(event);
 
thread->Dispatch(event, NS_DISPATCH_NORMAL);

== From JS ==

=== Event Dispatch ===
Threads and Thread Manager implement <code>nsIClassInfo</code>:

function MyEvent() {
}
MyEvent.prototype = {
QueryInterface: function(iid) {
if (iid.equals(Components.interfaces.nsIRunnable) ||
iid.equals(Components.interfaces.nsISupports))
return this;
throw Components.results.NS_ERROR_NO_INTERFACE;
},
run: function() {
// do stuff
}
};
 
function DispatchMyEvent() {
var target =
Components.classes["@mozilla.org/thread-manager;1"].
getService().currentThread;
 
target.dispatch(new MyEvent(), target.DISPATCH_NORMAL);
}

== Remarks ==

* Thread priority for native threads can be exposed via <code>nsISupportsPriority</code>.
* Thread names must be unique.
* The Necko I/O thread pool will be replaced by a generic thread pool implementation provided by XPCOM. The thread pool will implement <code>nsIEventTarget</code>, allowing events to be dispatched to any thread in the thread pool. We may even wish to define a <code>nsIThreadPool</code> interface and have it implement that as well. That interface would define methods to adjust the limits on the number of threads in the thread pool and so on.
* We will need an alternative for <code>nsIEventQueue::RevokeEvents</code>. There are several possibilities: (1) make consumers hold references to their nsIRunnable's so they can "disconnect" them manually, or (2) expose an enumeration/visitor API that allows consumers to walk the list of pending tasks and remove arbitrary tasks. I'm not sure what is best yet. The first option or something similar based on weak references is probably best as it avoids the costly O(n) <code>RevokeEvents</code> call.
* The following interfaces/classes would go away or be modified heavily: <code>nsIEventQueue</code>, <code>nsIEventQueueService</code>, <code>nsIEventTarget</code>, <code>nsIThread</code>, <code>PLEvent</code>.
* Issue: Perhaps we should support calling <code>nsIThread::Shutdown</code> from the thread itself. That would probably have to be implemented by posting an event to the main thread, and having that thread call shutdown. However, <code>Shutdown</code> also has the property that it does not return until the thread is gone. That obvious can't happen if <code>Shutdown</code> is called on the thread itself.

=== What about "native" event queues? ===
The main thread where UI events are processed and the socket transport thread will use the observer interface defined by <code>nsIThreadInternal</code>. The main thread will interact with the "native" event system during calls to <code>ProcessNextEvent</code> and <code>Dispatch</code>. Likewise, the socket transport thread will similarly need to poll sockets and perform I/O operations. By observing calls to <code>ProcessNextEvent</code>, observers can wait on a native event queue (or poll on a set of file descriptors) instead of waiting on the thread's internal event queue monitor. When they observe a call to <code>Dispatch</code>, they can use whatever mechanism is appropriate to unblock the thread that is waiting on the native event queue.

=== How do synchronous events work? ===

When <code>Dispatch(event, DISPATCH_SYNC)</code> is called on a <code>nsIEventTarget</code>, it first checks to see if the current thread is the same as the thread where the event would be run. If it is, then it just runs the event directly without queuing it up. However, if not, then it must queue the event to be run when the dispatch target next processes its events. To avoid returning to the caller immediately, the method gets the current thread and calls its <code>ProcessNextEvent</code> method in a loop until it receives acknowledgement that the queued event has been run.

== Development ==

Development is occuring on the THREADS_20060307_BRANCH. See also {{bug|326273}}.

== Comments ==

=== biesi: ===
* What happens if shutdown is called while an event is being processed? I assume that this event will be processed to its end, no further events are accepted, and then the thread is shut down. right?
** What happens to events that were already dispatched to this thread, but not run?
* Is it a good idea to allow other events to run on the current thread while in dispatch?
* Who is expected to call ProcessNextEvent?

==== darin: ====
* When asked to shutdown, a thread would finish dispatching all queued events, and refuse to accept any new events. Once all queued events run to completion, the thread would terminate. This is consistent with how event queues work today.
* If you are sync dispatching, then it is necessary to pump events on the calling thread or else you could end up in a dead-lock situation. For example, if thread A sync dispatches an event to thread B, which cannot complete its job without dispatching an event back to thread A, then the system will dead-lock unless thread A continues to dispatch pending events.
* <code>ProcessNextEvent</code> may be called by anybody that wishes to implement the concept of a "modal event loop." For example, XMLHttpRequest (in sync configuration) would sit in a loop calling <code>ProcessNextEvent</code> while waiting for the underlying HTTP transaction to complete. The key difference between <code>ProcessNextEvent</code> and <code>nsIEventQueue::ProcessPendingEvents</code> is that <code>ProcessNextEvent</code>, when called on the UI thread, will process UI events as well. And, it will also wait (block the thread of execution) if there are no UI events or pending <code>nsIRunnable</code> events.

=== dbaron: ===
So mrbkap was telling me at lunch about what's essentially the third bullet point of your comment to biesi above -- that you're making the concept of "modal event loop" even more powerful. This actually scares me a good bit, because these modal event loops happen within another event -- an event that may have state on the stack (e.g., |this| parameters) that could be destroyed by the processing of further events, or may have posted events that rely on the event completing. I really don't like the mix of programming models here that makes it very hard to write robust code, and I wish we could avoid this whole concept altogether rather than making it even more powerful, and thus more dangerous. We already have crashes where frame trees get destroyed while processing an event that are related to the Windows API's way of doing the same thing, though (for, e.g., a DestroyWindow call or whatever it's called).

==== darin: ====
Yup, I'm aware of that issue. In fact, the problem already exists today. There are some places in the code where WaitPLEvent + HandleEvent are called in a loop waiting for an event to process. That bypasses PL_ProcessPendingEvents recursion restriction. PopThreadEventQueue does not behave as you would expect either. It can cause ProcessPendingEvents to run for all but the PLEventQueue that is the subject of the current call to PL_ProcessPendingEvents on the stack. That defeats the purpose of the nested event queue in the first place.

The problem you describe with layout events also occurs for nsIStreamListener implementations. It would be really wierd if OnDataAvailable were called recursively, or if OnDataAvailable were called while the consumer is calling nsIChannel::AsyncOpen. These specific problems are dealt with in nsBaseChannel.cpp by temporarily suspending the channel during callbacks. That suppresses recusive stream listener calls.

Do you have a suggestion that would allow us to prevent this problem? Is there a better way to make XMLHttpRequest.send, document.load, window.alert, etc. appear modal to the calling Javascript?

For C++ consumers, we'd have to basically eliminate modal dialogs altogether to avoid this problem. Today, we have bugs where downloads stall and get disconnected all because the browser popped up a modal dialog and the dialog was not closed promptly enough by the user. That's just unacceptable. And, nsIPromptService is frozen.

I think the answer is to be careful about making callbacks across XPCOM boundaries where event queues may be pumped. Maybe the layout code needs to unwind the stack more before allowing such callbacks to happen so that it can be sure that event processing won't be the end of the world.

dbaron: Also, with the new push/popEventQueue API defined on nsIThreadInternal, it is possible to suppress event dispatch for a particular scope. That is needed to implement synchronous XPCOM proxy calls. I'm assuming that any proper use of synchronous XPCOM proxy calls will be one that completes relatively quickly so as to negate the effects of locking up the browser. We should probably be very careful about calling PushEventQueue on the main thread, where it would potentially disrupt the browser UI. Native events would still be dispatched as always, but without application level events, the UI isn't very useful.

Sheriff Schedule

2006-05-02T01:59:25Z

Darin: /* Schedule */

= Schedule =
{|
|Saturday || 2006-04-22 || #developers
|-
|Sunday || 2006-04-23 || #developers
|-
|Monday || 2006-04-24 || #developers
|-
|Tuesday || 2006-04-25 || #developers
|-
|Wednesday || 2006-04-26 || #developers
|-
|Thursday || 2006-04-27 || '''available'''
|-
|Friday || 2006-04-28 || '''available'''
|-
|Saturday || 2006-04-29 || #developers
|-
|Sunday || 2006-04-30 || #developers
|-
|Monday || 2006-05-01 || stuart
|-
|Tuesday || 2006-05-02 || vlad
|-
|Wednesday || 2006-05-03 || biesi
|-
|Thursday || 2006-05-04 || dveditz
|-
|Friday || 2006-05-05 || darin
|-
|Saturday || 2006-05-06 || #developers
|-
|Sunday || 2006-05-07 || #developers
|-
|Monday || 2006-05-08 || sicking
|-
|Tuesday || 2006-05-09 || brettw
|-
|Wednesday || 2006-05-10 || '''available'''
|-
|Thursday || 2006-05-11 || roc
|-
|Friday || 2006-05-12 || '''available'''
|-
|Saturday || 2006-05-13 || #developers
|-
|Sunday || 2006-05-14 || #developers
|-
|Monday || 2006-05-15 || '''available'''
|-
|Tuesday || 2006-05-16 || '''available'''
|-
|Wednesday || 2006-05-17 || '''available'''
|-
|Thursday || 2006-05-18 || '''available'''
|-
|Friday || 2006-05-19 || '''available'''
|-
|Saturday || 2006-05-20 || #developers
|-
|Sunday || 2006-05-21 || #developers
|-
|Monday || 2006-05-22 || '''available'''
|-
|Tuesday || 2006-05-23 || bryner
|-
|Wednesday || 2006-05-24 || [[User:Dbaron|David Baron]]
|-
|Thursday || 2006-05-25 || [[User:Robert_Strong|Robert Strong]]
|-
|Friday || 2006-05-26 || '''available'''
|-
|Saturday || 2006-05-27 || #developers
|-
|Sunday || 2006-05-28 || #developers
|}

WhatwgStorage Whiteboard

2006-04-13T22:47:42Z

Darin:

Neil to impl core storage system, jst to impl security/access/scoping. vlad to advise, shaver to cheerlead.

* Can we track "browser context" well enough?
** https://bugzilla.mozilla.org/show_bug.cgi?id=117222#c125
* UI requirements?
** need a storage limit (by domain and subdomain) -- global limit for A2
** expiration policy? (after A2)
* domain hierarchy stuff? (see [http://groups.google.com/group/mozilla.dev.platform/browse_frm/thread/aafd263e23666ee/0a2c54c8c6c5754e?q=domain&rnum=1#0a2c54c8c6c5754e m.d.platform posting])

* What subset?
** no DOM object or JS object auto-serialization
** jst to propose the removal of key enumeration to whatwg list (security reasons)

* sessionStorage using in-memory hash or just another table?
** vlad: no on-disk storage for security reasons?
** shaver: what about session saver? (what does it do for session cookies?)
** spec suggests persistence of session data in this case: [http://www.whatwg.org/specs/web-apps/current-work/#the-sessionstorage 4.9.3]
** darin: cookies have the notion of session only, which is not persisted. the web cache has the concept of "no-store". this storage system needs something like that too. web apps should be given a way to restrict storage to in-memory only.
* globalStorage using mozStorage, simple table
** look at what history guys did for fast domain-based lookup?

XPCOM:nsIThreadManager

2006-04-07T18:55:02Z

Darin: /* nsIThread */

In a world without nested event queues, the concept of a thread and an event queue merge...

== Interfaces ==
=== nsIThreadManager ===
[scriptable, uuid(...)]
interface nsIThreadManager : nsISupports {
/**
* Create a new named thread (a global, user PRThread). If the name is
* non-empty, then the name of the thread must be unique. Specifying an
* empty name results in an anonymous thread that cannot be found later on
* using the getThread method.
*/
nsIThread newThread(in ACString name);
 
/**
* Find a named thread. If no thread exists by the given name, then null
* is returned.
*/
nsIThread getThread(in ACString name);
 
/**
* Get the nsIThread object (if any) corresponding to the given PRThread.
* This method returns null if there is no corresponding nsIThread.
*/
[noscript] nsIThread getThreadFromPRThread(in PRThread thread);
 
/**
* Get the main thread.
*/
readonly attribute nsIThread mainThread;
 
/**
* Get the current thread.
*/
readonly attribute nsIThread currentThread;
 
/**
* This attribute is true if the calling thread is the main thread of the
* application process.
*/
readonly attribute boolean isMainThread;
};

=== nsIEventTarget ===
[scriptable, uuid(...)]
interface nsIEventTarget : nsISupports {
/**
* Dispatch an event to the target. This function may be called from any
* thread. If flags specifies DISPATCH_SYNC, then the dispatch method
* will not return until the event has been processed. NOTE: Calling
* dispatch with DISPATCH_SYNC, may have the side-effect of running other
* events on the current thread while waiting for the given event to run
* to completion. This function is thread-safe and re-entrant.
*/
void dispatch(in nsIRunnable event, in unsigned long flags);
const unsigned long DISPATCH_NORMAL = 0;
const unsigned long DISPATCH_SYNC = 1;
 
/**
* Returns true if events dispatched to this target will run on the
* current thread (i.e., the thread calling this method).
*/
boolean isOnCurrentThread();
};
 
%{C++
// convenient aliases:
#define NS_DISPATCH_NORMAL nsIEventTarget::DISPATCH_NORMAL
#define NS_DISPATCH_SYNC nsIEventTarget::DISPATCH_SYNC
%}

=== nsIThread ===
[scriptable, uuid(...)]
interface nsIThread : nsIEventTarget {
/**
* Returns the name of the thread, which may be empty if this thread is
* anonymous.
*/
readonly attribute ACString name;
 
/**
* Returns the PRThread object corresponding to this nsIThread.
*/
[noscript] PRThread getPRThread();
 
/**
* Shutdown the thread. This method may not be executed from the thread
* itself. Instead, it is meant to be executed from another thread (usually
* the thread that created this thread). When this function returns, the
* thread will be shutdown, and it will no longer be possible to dispatch
* events to the thread.
*/
void shutdown();
 
/**
* Returns true if this thread has one or more pending events.
*/
boolean hasPendingEvents();
 
/**
* Process the next event. If there are no pending events, then this
* method may wait -- provided mayWait is true -- until an event is
* dispatched to this thread. This method is re-entrant but may only be
* called if this thread is the current thread.
*
* @return A boolean value that is "true" if an event was processed.
*/
boolean processNextEvent(in boolean mayWait);
};

=== nsIThreadInternal ===
[scriptable, uuid(...)]
interface nsIThreadInternal : nsIThread {
/**
* Get/set an observer for this thread (may be null). This attribute may
* be read from any thread, but must only be set on the thread corresponding
* to this thread object.
*/
attribute nsIThreadObserver observer;
 
/**
* This method causes any events currently enqueued on the thread to be
* suppressed until PopEventQueue is called. Additionally, any new events
* dispatched to the thread will only be processed if they are accepted by
* the given filter. If the filter is null, then new events are accepted.
* Calls to PushEventQueue may be nested and must each be paired with a call
* to PopEventQueue in order to restore the original state of the thread.
*/
void pushEventQueue(in nsIThreadEventFilter filter);
 
/**
* Revert a call to PushEventQueue. When an event queue is popped, any
* events remaining in the queue are appended to the elder queue.
*/
void popEventQueue();
};

=== nsIThreadObserver ===
[scriptable, uuid(...)]
interface nsIThreadObserver : nsISupports {
/**
* This method is called after an event has been dispatched to the thread.
* This method may be called from any thread.
*/
void onDispatchedEvent(in nsIThreadInternal thread);
 
/**
* This method is called (from nsIThread::ProcessNextEvent) before an event
* is processed. This method is only called on the target thread.
*
* @param thread
* The thread being asked to process another event.
* @param mayWait
* Indicates whether or not the method is allowed to block the calling
* thread. For example, this parameter is false during thread shutdown.
* @param recursionDepth
* Indicates the number of calls to ProcessNextEvent on the call stack
* in addition to the current call.
*/
void onProcessNextEvent(in nsIThreadInternal thread, in boolean mayWait,
in unsigned long recursionDepth);
};

=== nsIThreadEventFilter ===
[scriptable, uuid(...)]
interface nsIThreadEventFilter : nsISupports {
/**
* This method is called to determine whether or not an event may be accepted
* by a "nested" event queue (see nsIThreadInternal::PushEventQueue).
*
* WARNING: This method must not make any calls on the thread object.
*/
[notxpcom] boolean AcceptEvent(in nsIRunnable event);
};

=== nsIThreadPool ===
[scriptable, uuid(...)]
interface nsIThreadPool : nsIEventTarget
{
/**
* Shutdown the thread pool. This method may not be executed from any
* thread in the thread pool. Instead, it is meant to be executed from
* another thread (usually the thread that created this thread pool).
* When this function returns, the thread pool and all of its threads will
* be shutdown, and it will no longer be possible to dispatch tasks to the
* thread pool.
*/
void shutdown()
 
/**
* Get/set the maximum number of threads allowed at one time in this pool.
*/
attribute unsigned long threadLimit;
 
/**
* Get/set the maximum number of idle threads kept alive.
*/
attribute unsigned long idleThreadLimit;
 
/**
* Get/set the amount of time in milliseconds before an idle thread is
* destroyed.
*/
attribute unsigned long idleThreadTimeout;
};

== C++ Utilities ==

=== Functions ===
nsThreadUtils.h defines the following helper functions:

/**
* Create a new thread.
*
* @param name
* The name of the thread (must be unique) or the empty string to
* create an anonymous thread.
* @param event
* The initial event to run on this thread. This can be null.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_NewThread(const nsACString &name, nsIRunnable *event,
nsIThread **result);
 
/**
* Get a reference to the current thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetCurrentThread(nsIThread **result);
 
/**
* Get a reference to the main thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetMainThread(nsIThread **result);
 
/**
* Get a reference to the thread with the given name.
*
* @param name
* The name of the requested thread. Must be non-empty.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetThread(const nsACString &name, nsIThread **result);
 
/**
* Test to see if the current thread is the main thread.
*
* @returns PR_TRUE if the current thread is the main thread, and PR_FALSE
* otherwise.
*/
PRBool NS_IsMainThread();
 
/**
* Dispatch the given event to the current thread.
*
* @param event
* The event to dispatch.
*/
NS_METHOD NS_DispatchToCurrentThread(nsIRunnable *event);
 
/**
* Dispatch the given event to the main thread.
*
* @param event
* The event to dispatch.
* @param dispatchFlags
* The flags to pass to the main thread's dispatch method.
*/
NS_METHOD NS_DispatchToMainThread(nsIRunnable *event,
PRUint32 dispatchFlags = NS_DISPATCH_NORMAL);
 
/**
* Process all pending events for the given thread before returning. This
* method simply calls ProcessNextEvent on the thread while HasPendingEvents
* continues to return true and the time spent in NS_ProcessPendingEvents
* does not exceed the given timeout value.
*
* @param thread
* The thread object for which to process pending events. If null,
* then events will be processed for the current thread.
* @param timeout
* The maximum number of milliseconds to spend processing pending
* events. Events are not pre-empted to honor this timeout. Rather,
* the timeout value is simply used to determine whether or not to
* process another event. Pass PR_INTERVAL_NO_TIMEOUT to specify no
* timeout.
*/
NS_METHOD NS_ProcessPendingEvents(nsIThread *thread = nsnull,
PRIntervalTime timeout = PR_INTERVAL_NO_TIMEOUT);

=== nsCOMPtr helpers ===
The following nsCOMPtr helpers are defined to simplify things further:

already_AddRefed<nsIThread> do_GetCurrentThread();
 
already_AddRefed<nsIThread> do_GetMainThread();
 
already_AddRefed<nsIThread> do_GetThread(const nsACString &name);

=== nsRunnable ===
The class <code>nsRunnable</code> is also defined to simplify the
implementation of new event types. For example, to define a new
event all you need to do is write code like this:

class MyEvent : public nsRunnable {
public:
MyEvent(... params ...);
 
NS_IMETHOD Run() {
// do stuff
return NS_OK;
}
};

Dispatching <code>MyEvent</code> is then as simple as:

nsCOMPtr<nsIThread> thread = do_GetCurrentThread();
NS_ENSURE_STATE(thread);
 
nsCOMPtr<nsIRunnable> event = new MyEvent();
NS_ENSURE_STATE(event);
 
thread->Dispatch(event, NS_DISPATCH_NORMAL);

== From JS ==

=== Event Dispatch ===
Threads and Thread Manager implement <code>nsIClassInfo</code>:

function MyEvent() {
}
MyEvent.prototype = {
QueryInterface: function(iid) {
if (iid.equals(Components.interfaces.nsIRunnable) ||
iid.equals(Components.interfaces.nsISupports))
return this;
throw Components.results.NS_ERROR_NO_INTERFACE;
},
run: function() {
// do stuff
}
};
 
function DispatchMyEvent() {
var target =
Components.classes["@mozilla.org/thread-manager;1"].
getService().currentThread;
 
target.dispatch(new MyEvent(), target.DISPATCH_NORMAL);
}

== Remarks ==

* Thread priority for native threads can be exposed via <code>nsISupportsPriority</code>.
* Thread names must be unique.
* The Necko I/O thread pool will be replaced by a generic thread pool implementation provided by XPCOM. The thread pool will implement <code>nsIEventTarget</code>, allowing events to be dispatched to any thread in the thread pool. We may even wish to define a <code>nsIThreadPool</code> interface and have it implement that as well. That interface would define methods to adjust the limits on the number of threads in the thread pool and so on.
* We will need an alternative for <code>nsIEventQueue::RevokeEvents</code>. There are several possibilities: (1) make consumers hold references to their nsIRunnable's so they can "disconnect" them manually, or (2) expose an enumeration/visitor API that allows consumers to walk the list of pending tasks and remove arbitrary tasks. I'm not sure what is best yet. The first option or something similar based on weak references is probably best as it avoids the costly O(n) <code>RevokeEvents</code> call.
* The following interfaces/classes would go away or be modified heavily: <code>nsIEventQueue</code>, <code>nsIEventQueueService</code>, <code>nsIEventTarget</code>, <code>nsIThread</code>, <code>PLEvent</code>.
* Issue: Perhaps we should support calling <code>nsIThread::Shutdown</code> from the thread itself. That would probably have to be implemented by posting an event to the main thread, and having that thread call shutdown. However, <code>Shutdown</code> also has the property that it does not return until the thread is gone. That obvious can't happen if <code>Shutdown</code> is called on the thread itself.

=== What about "native" event queues? ===
The main thread where UI events are processed and the socket transport thread will use the observer interface defined by <code>nsIThreadInternal</code>. The main thread will interact with the "native" event system during calls to <code>ProcessNextEvent</code> and <code>Dispatch</code>. Likewise, the socket transport thread will similarly need to poll sockets and perform I/O operations. By observing calls to <code>ProcessNextEvent</code>, observers can wait on a native event queue (or poll on a set of file descriptors) instead of waiting on the thread's internal event queue monitor. When they observe a call to <code>Dispatch</code>, they can use whatever mechanism is appropriate to unblock the thread that is waiting on the native event queue.

=== How do synchronous events work? ===

When <code>Dispatch(event, DISPATCH_SYNC)</code> is called on a <code>nsIEventTarget</code>, it first checks to see if the current thread is the same as the thread where the event would be run. If it is, then it just runs the event directly without queuing it up. However, if not, then it must queue the event to be run when the dispatch target next processes its events. To avoid returning to the caller immediately, the method gets the current thread and calls its <code>ProcessNextEvent</code> method in a loop until it receives acknowledgement that the queued event has been run.

== Development ==

Development is occuring on the THREADS_20060307_BRANCH. See also {{bug|326273}}.

== Comments ==

=== biesi: ===
* What happens if shutdown is called while an event is being processed? I assume that this event will be processed to its end, no further events are accepted, and then the thread is shut down. right?
** What happens to events that were already dispatched to this thread, but not run?
* Is it a good idea to allow other events to run on the current thread while in dispatch?
* Who is expected to call ProcessNextEvent?

==== darin: ====
* When asked to shutdown, a thread would finish dispatching all queued events, and refuse to accept any new events. Once all queued events run to completion, the thread would terminate. This is consistent with how event queues work today.
* If you are sync dispatching, then it is necessary to pump events on the calling thread or else you could end up in a dead-lock situation. For example, if thread A sync dispatches an event to thread B, which cannot complete its job without dispatching an event back to thread A, then the system will dead-lock unless thread A continues to dispatch pending events.
* <code>ProcessNextEvent</code> may be called by anybody that wishes to implement the concept of a "modal event loop." For example, XMLHttpRequest (in sync configuration) would sit in a loop calling <code>ProcessNextEvent</code> while waiting for the underlying HTTP transaction to complete. The key difference between <code>ProcessNextEvent</code> and <code>nsIEventQueue::ProcessPendingEvents</code> is that <code>ProcessNextEvent</code>, when called on the UI thread, will process UI events as well. And, it will also wait (block the thread of execution) if there are no UI events or pending <code>nsIRunnable</code> events.

=== dbaron: ===
So mrbkap was telling me at lunch about what's essentially the third bullet point of your comment to biesi above -- that you're making the concept of "modal event loop" even more powerful. This actually scares me a good bit, because these modal event loops happen within another event -- an event that may have state on the stack (e.g., |this| parameters) that could be destroyed by the processing of further events, or may have posted events that rely on the event completing. I really don't like the mix of programming models here that makes it very hard to write robust code, and I wish we could avoid this whole concept altogether rather than making it even more powerful, and thus more dangerous. We already have crashes where frame trees get destroyed while processing an event that are related to the Windows API's way of doing the same thing, though (for, e.g., a DestroyWindow call or whatever it's called).

==== darin: ====
Yup, I'm aware of that issue. In fact, the problem already exists today. There are some places in the code where WaitPLEvent + HandleEvent are called in a loop waiting for an event to process. That bypasses PL_ProcessPendingEvents recursion restriction. PopThreadEventQueue does not behave as you would expect either. It can cause ProcessPendingEvents to run for all but the PLEventQueue that is the subject of the current call to PL_ProcessPendingEvents on the stack. That defeats the purpose of the nested event queue in the first place.

The problem you describe with layout events also occurs for nsIStreamListener implementations. It would be really wierd if OnDataAvailable were called recursively, or if OnDataAvailable were called while the consumer is calling nsIChannel::AsyncOpen. These specific problems are dealt with in nsBaseChannel.cpp by temporarily suspending the channel during callbacks. That suppresses recusive stream listener calls.

Do you have a suggestion that would allow us to prevent this problem? Is there a better way to make XMLHttpRequest.send, document.load, window.alert, etc. appear modal to the calling Javascript?

For C++ consumers, we'd have to basically eliminate modal dialogs altogether to avoid this problem. Today, we have bugs where downloads stall and get disconnected all because the browser popped up a modal dialog and the dialog was not closed promptly enough by the user. That's just unacceptable. And, nsIPromptService is frozen.

I think the answer is to be careful about making callbacks across XPCOM boundaries where event queues may be pumped. Maybe the layout code needs to unwind the stack more before allowing such callbacks to happen so that it can be sure that event processing won't be the end of the world.

dbaron: Also, with the new push/popEventQueue API defined on nsIThreadInternal, it is possible to suppress event dispatch for a particular scope. That is needed to implement synchronous XPCOM proxy calls. I'm assuming that any proper use of synchronous XPCOM proxy calls will be one that completes relatively quickly so as to negate the effects of locking up the browser. We should probably be very careful about calling PushEventQueue on the main thread, where it would potentially disrupt the browser UI. Native events would still be dispatched as always, but without application level events, the UI isn't very useful.

XPCOM:nsIThreadManager

2006-04-07T18:54:01Z

Darin: /* nsIThread */

In a world without nested event queues, the concept of a thread and an event queue merge...

== Interfaces ==
=== nsIThreadManager ===
[scriptable, uuid(...)]
interface nsIThreadManager : nsISupports {
/**
* Create a new named thread (a global, user PRThread). If the name is
* non-empty, then the name of the thread must be unique. Specifying an
* empty name results in an anonymous thread that cannot be found later on
* using the getThread method.
*/
nsIThread newThread(in ACString name);
 
/**
* Find a named thread. If no thread exists by the given name, then null
* is returned.
*/
nsIThread getThread(in ACString name);
 
/**
* Get the nsIThread object (if any) corresponding to the given PRThread.
* This method returns null if there is no corresponding nsIThread.
*/
[noscript] nsIThread getThreadFromPRThread(in PRThread thread);
 
/**
* Get the main thread.
*/
readonly attribute nsIThread mainThread;
 
/**
* Get the current thread.
*/
readonly attribute nsIThread currentThread;
 
/**
* This attribute is true if the calling thread is the main thread of the
* application process.
*/
readonly attribute boolean isMainThread;
};

=== nsIEventTarget ===
[scriptable, uuid(...)]
interface nsIEventTarget : nsISupports {
/**
* Dispatch an event to the target. This function may be called from any
* thread. If flags specifies DISPATCH_SYNC, then the dispatch method
* will not return until the event has been processed. NOTE: Calling
* dispatch with DISPATCH_SYNC, may have the side-effect of running other
* events on the current thread while waiting for the given event to run
* to completion. This function is thread-safe and re-entrant.
*/
void dispatch(in nsIRunnable event, in unsigned long flags);
const unsigned long DISPATCH_NORMAL = 0;
const unsigned long DISPATCH_SYNC = 1;
 
/**
* Returns true if events dispatched to this target will run on the
* current thread (i.e., the thread calling this method).
*/
boolean isOnCurrentThread();
};
 
%{C++
// convenient aliases:
#define NS_DISPATCH_NORMAL nsIEventTarget::DISPATCH_NORMAL
#define NS_DISPATCH_SYNC nsIEventTarget::DISPATCH_SYNC
%}

=== nsIThread ===
[scriptable, uuid(...)]
interface nsIThread : nsIEventTarget {
/**
* Returns the name of the thread, which may be empty if this thread is
* anonymous.
*/
readonly attribute ACString name;
 
/**
* Returns the PRThread object corresponding to this nsIThread.
*/
[noscript] PRThread getPRThread();
 
/**
* Shutdown the thread. This method may not be executed from the thread
* itself. Instead, it is meant to be executed from another thread (usually
* the thread that created this thread). When this function returns, the
* thread will be shutdown, and it will no longer be possible to dispatch
* events to the thread.
*/
void shutdown();
 
/**
* Returns true if this thread has one or more pending events.
*/
boolean hasPendingEvents();
 
/**
* Process the next event. If there are no pending events, then this
* method will wait until an event is dispatched to this thread. This
* method is re-entrant but may only be called if this thread is the
* current thread.
*/
boolean processNextEvent(in boolean mayWait);
};

=== nsIThreadInternal ===
[scriptable, uuid(...)]
interface nsIThreadInternal : nsIThread {
/**
* Get/set an observer for this thread (may be null). This attribute may
* be read from any thread, but must only be set on the thread corresponding
* to this thread object.
*/
attribute nsIThreadObserver observer;
 
/**
* This method causes any events currently enqueued on the thread to be
* suppressed until PopEventQueue is called. Additionally, any new events
* dispatched to the thread will only be processed if they are accepted by
* the given filter. If the filter is null, then new events are accepted.
* Calls to PushEventQueue may be nested and must each be paired with a call
* to PopEventQueue in order to restore the original state of the thread.
*/
void pushEventQueue(in nsIThreadEventFilter filter);
 
/**
* Revert a call to PushEventQueue. When an event queue is popped, any
* events remaining in the queue are appended to the elder queue.
*/
void popEventQueue();
};

=== nsIThreadObserver ===
[scriptable, uuid(...)]
interface nsIThreadObserver : nsISupports {
/**
* This method is called after an event has been dispatched to the thread.
* This method may be called from any thread.
*/
void onDispatchedEvent(in nsIThreadInternal thread);
 
/**
* This method is called (from nsIThread::ProcessNextEvent) before an event
* is processed. This method is only called on the target thread.
*
* @param thread
* The thread being asked to process another event.
* @param mayWait
* Indicates whether or not the method is allowed to block the calling
* thread. For example, this parameter is false during thread shutdown.
* @param recursionDepth
* Indicates the number of calls to ProcessNextEvent on the call stack
* in addition to the current call.
*/
void onProcessNextEvent(in nsIThreadInternal thread, in boolean mayWait,
in unsigned long recursionDepth);
};

=== nsIThreadEventFilter ===
[scriptable, uuid(...)]
interface nsIThreadEventFilter : nsISupports {
/**
* This method is called to determine whether or not an event may be accepted
* by a "nested" event queue (see nsIThreadInternal::PushEventQueue).
*
* WARNING: This method must not make any calls on the thread object.
*/
[notxpcom] boolean AcceptEvent(in nsIRunnable event);
};

=== nsIThreadPool ===
[scriptable, uuid(...)]
interface nsIThreadPool : nsIEventTarget
{
/**
* Shutdown the thread pool. This method may not be executed from any
* thread in the thread pool. Instead, it is meant to be executed from
* another thread (usually the thread that created this thread pool).
* When this function returns, the thread pool and all of its threads will
* be shutdown, and it will no longer be possible to dispatch tasks to the
* thread pool.
*/
void shutdown()
 
/**
* Get/set the maximum number of threads allowed at one time in this pool.
*/
attribute unsigned long threadLimit;
 
/**
* Get/set the maximum number of idle threads kept alive.
*/
attribute unsigned long idleThreadLimit;
 
/**
* Get/set the amount of time in milliseconds before an idle thread is
* destroyed.
*/
attribute unsigned long idleThreadTimeout;
};

== C++ Utilities ==

=== Functions ===
nsThreadUtils.h defines the following helper functions:

/**
* Create a new thread.
*
* @param name
* The name of the thread (must be unique) or the empty string to
* create an anonymous thread.
* @param event
* The initial event to run on this thread. This can be null.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_NewThread(const nsACString &name, nsIRunnable *event,
nsIThread **result);
 
/**
* Get a reference to the current thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetCurrentThread(nsIThread **result);
 
/**
* Get a reference to the main thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetMainThread(nsIThread **result);
 
/**
* Get a reference to the thread with the given name.
*
* @param name
* The name of the requested thread. Must be non-empty.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetThread(const nsACString &name, nsIThread **result);
 
/**
* Test to see if the current thread is the main thread.
*
* @returns PR_TRUE if the current thread is the main thread, and PR_FALSE
* otherwise.
*/
PRBool NS_IsMainThread();
 
/**
* Dispatch the given event to the current thread.
*
* @param event
* The event to dispatch.
*/
NS_METHOD NS_DispatchToCurrentThread(nsIRunnable *event);
 
/**
* Dispatch the given event to the main thread.
*
* @param event
* The event to dispatch.
* @param dispatchFlags
* The flags to pass to the main thread's dispatch method.
*/
NS_METHOD NS_DispatchToMainThread(nsIRunnable *event,
PRUint32 dispatchFlags = NS_DISPATCH_NORMAL);
 
/**
* Process all pending events for the given thread before returning. This
* method simply calls ProcessNextEvent on the thread while HasPendingEvents
* continues to return true and the time spent in NS_ProcessPendingEvents
* does not exceed the given timeout value.
*
* @param thread
* The thread object for which to process pending events. If null,
* then events will be processed for the current thread.
* @param timeout
* The maximum number of milliseconds to spend processing pending
* events. Events are not pre-empted to honor this timeout. Rather,
* the timeout value is simply used to determine whether or not to
* process another event. Pass PR_INTERVAL_NO_TIMEOUT to specify no
* timeout.
*/
NS_METHOD NS_ProcessPendingEvents(nsIThread *thread = nsnull,
PRIntervalTime timeout = PR_INTERVAL_NO_TIMEOUT);

=== nsCOMPtr helpers ===
The following nsCOMPtr helpers are defined to simplify things further:

already_AddRefed<nsIThread> do_GetCurrentThread();
 
already_AddRefed<nsIThread> do_GetMainThread();
 
already_AddRefed<nsIThread> do_GetThread(const nsACString &name);

=== nsRunnable ===
The class <code>nsRunnable</code> is also defined to simplify the
implementation of new event types. For example, to define a new
event all you need to do is write code like this:

class MyEvent : public nsRunnable {
public:
MyEvent(... params ...);
 
NS_IMETHOD Run() {
// do stuff
return NS_OK;
}
};

Dispatching <code>MyEvent</code> is then as simple as:

nsCOMPtr<nsIThread> thread = do_GetCurrentThread();
NS_ENSURE_STATE(thread);
 
nsCOMPtr<nsIRunnable> event = new MyEvent();
NS_ENSURE_STATE(event);
 
thread->Dispatch(event, NS_DISPATCH_NORMAL);

== From JS ==

=== Event Dispatch ===
Threads and Thread Manager implement <code>nsIClassInfo</code>:

function MyEvent() {
}
MyEvent.prototype = {
QueryInterface: function(iid) {
if (iid.equals(Components.interfaces.nsIRunnable) ||
iid.equals(Components.interfaces.nsISupports))
return this;
throw Components.results.NS_ERROR_NO_INTERFACE;
},
run: function() {
// do stuff
}
};
 
function DispatchMyEvent() {
var target =
Components.classes["@mozilla.org/thread-manager;1"].
getService().currentThread;
 
target.dispatch(new MyEvent(), target.DISPATCH_NORMAL);
}

== Remarks ==

* Thread priority for native threads can be exposed via <code>nsISupportsPriority</code>.
* Thread names must be unique.
* The Necko I/O thread pool will be replaced by a generic thread pool implementation provided by XPCOM. The thread pool will implement <code>nsIEventTarget</code>, allowing events to be dispatched to any thread in the thread pool. We may even wish to define a <code>nsIThreadPool</code> interface and have it implement that as well. That interface would define methods to adjust the limits on the number of threads in the thread pool and so on.
* We will need an alternative for <code>nsIEventQueue::RevokeEvents</code>. There are several possibilities: (1) make consumers hold references to their nsIRunnable's so they can "disconnect" them manually, or (2) expose an enumeration/visitor API that allows consumers to walk the list of pending tasks and remove arbitrary tasks. I'm not sure what is best yet. The first option or something similar based on weak references is probably best as it avoids the costly O(n) <code>RevokeEvents</code> call.
* The following interfaces/classes would go away or be modified heavily: <code>nsIEventQueue</code>, <code>nsIEventQueueService</code>, <code>nsIEventTarget</code>, <code>nsIThread</code>, <code>PLEvent</code>.
* Issue: Perhaps we should support calling <code>nsIThread::Shutdown</code> from the thread itself. That would probably have to be implemented by posting an event to the main thread, and having that thread call shutdown. However, <code>Shutdown</code> also has the property that it does not return until the thread is gone. That obvious can't happen if <code>Shutdown</code> is called on the thread itself.

=== What about "native" event queues? ===
The main thread where UI events are processed and the socket transport thread will use the observer interface defined by <code>nsIThreadInternal</code>. The main thread will interact with the "native" event system during calls to <code>ProcessNextEvent</code> and <code>Dispatch</code>. Likewise, the socket transport thread will similarly need to poll sockets and perform I/O operations. By observing calls to <code>ProcessNextEvent</code>, observers can wait on a native event queue (or poll on a set of file descriptors) instead of waiting on the thread's internal event queue monitor. When they observe a call to <code>Dispatch</code>, they can use whatever mechanism is appropriate to unblock the thread that is waiting on the native event queue.

=== How do synchronous events work? ===

When <code>Dispatch(event, DISPATCH_SYNC)</code> is called on a <code>nsIEventTarget</code>, it first checks to see if the current thread is the same as the thread where the event would be run. If it is, then it just runs the event directly without queuing it up. However, if not, then it must queue the event to be run when the dispatch target next processes its events. To avoid returning to the caller immediately, the method gets the current thread and calls its <code>ProcessNextEvent</code> method in a loop until it receives acknowledgement that the queued event has been run.

== Development ==

Development is occuring on the THREADS_20060307_BRANCH. See also {{bug|326273}}.

== Comments ==

=== biesi: ===
* What happens if shutdown is called while an event is being processed? I assume that this event will be processed to its end, no further events are accepted, and then the thread is shut down. right?
** What happens to events that were already dispatched to this thread, but not run?
* Is it a good idea to allow other events to run on the current thread while in dispatch?
* Who is expected to call ProcessNextEvent?

==== darin: ====
* When asked to shutdown, a thread would finish dispatching all queued events, and refuse to accept any new events. Once all queued events run to completion, the thread would terminate. This is consistent with how event queues work today.
* If you are sync dispatching, then it is necessary to pump events on the calling thread or else you could end up in a dead-lock situation. For example, if thread A sync dispatches an event to thread B, which cannot complete its job without dispatching an event back to thread A, then the system will dead-lock unless thread A continues to dispatch pending events.
* <code>ProcessNextEvent</code> may be called by anybody that wishes to implement the concept of a "modal event loop." For example, XMLHttpRequest (in sync configuration) would sit in a loop calling <code>ProcessNextEvent</code> while waiting for the underlying HTTP transaction to complete. The key difference between <code>ProcessNextEvent</code> and <code>nsIEventQueue::ProcessPendingEvents</code> is that <code>ProcessNextEvent</code>, when called on the UI thread, will process UI events as well. And, it will also wait (block the thread of execution) if there are no UI events or pending <code>nsIRunnable</code> events.

=== dbaron: ===
So mrbkap was telling me at lunch about what's essentially the third bullet point of your comment to biesi above -- that you're making the concept of "modal event loop" even more powerful. This actually scares me a good bit, because these modal event loops happen within another event -- an event that may have state on the stack (e.g., |this| parameters) that could be destroyed by the processing of further events, or may have posted events that rely on the event completing. I really don't like the mix of programming models here that makes it very hard to write robust code, and I wish we could avoid this whole concept altogether rather than making it even more powerful, and thus more dangerous. We already have crashes where frame trees get destroyed while processing an event that are related to the Windows API's way of doing the same thing, though (for, e.g., a DestroyWindow call or whatever it's called).

==== darin: ====
Yup, I'm aware of that issue. In fact, the problem already exists today. There are some places in the code where WaitPLEvent + HandleEvent are called in a loop waiting for an event to process. That bypasses PL_ProcessPendingEvents recursion restriction. PopThreadEventQueue does not behave as you would expect either. It can cause ProcessPendingEvents to run for all but the PLEventQueue that is the subject of the current call to PL_ProcessPendingEvents on the stack. That defeats the purpose of the nested event queue in the first place.

The problem you describe with layout events also occurs for nsIStreamListener implementations. It would be really wierd if OnDataAvailable were called recursively, or if OnDataAvailable were called while the consumer is calling nsIChannel::AsyncOpen. These specific problems are dealt with in nsBaseChannel.cpp by temporarily suspending the channel during callbacks. That suppresses recusive stream listener calls.

Do you have a suggestion that would allow us to prevent this problem? Is there a better way to make XMLHttpRequest.send, document.load, window.alert, etc. appear modal to the calling Javascript?

For C++ consumers, we'd have to basically eliminate modal dialogs altogether to avoid this problem. Today, we have bugs where downloads stall and get disconnected all because the browser popped up a modal dialog and the dialog was not closed promptly enough by the user. That's just unacceptable. And, nsIPromptService is frozen.

I think the answer is to be careful about making callbacks across XPCOM boundaries where event queues may be pumped. Maybe the layout code needs to unwind the stack more before allowing such callbacks to happen so that it can be sure that event processing won't be the end of the world.

dbaron: Also, with the new push/popEventQueue API defined on nsIThreadInternal, it is possible to suppress event dispatch for a particular scope. That is needed to implement synchronous XPCOM proxy calls. I'm assuming that any proper use of synchronous XPCOM proxy calls will be one that completes relatively quickly so as to negate the effects of locking up the browser. We should probably be very careful about calling PushEventQueue on the main thread, where it would potentially disrupt the browser UI. Native events would still be dispatched as always, but without application level events, the UI isn't very useful.

Browser Metrics:Data Collectors

2006-03-28T15:13:43Z

Darin: /* Load Event */

==Data Format==

===Overview===

Data will be collected as a stream of events, with the exception of a user profile that is collected once every browser session. Each event type is represented by a particular XML element in the <tt>http://www.mozilla.org/metrics</tt> namespace. We will define several event types that will have predefined schemas. We will be able to throttle data collection based on the event type, so that verbose events can be turned on and off when we want. The tentative event types and associated schemas are listed below. (Note: the list is still very much in flux and will likely change.)

All event types have a <tt>time</tt> attribute, which gives a timestamp for the event, recorded as seconds since the epoch.

===Profile===

The profile will be collected every browser session, to pick up changes periodically. The profile element is a grouping element which contains a set of profile values.

; Element <tt><profile></tt>
: ''Attributes:'' none

The following elements are optional children of <tt><profile></tt>:

; Element <tt><memory></tt>
: Describes the memory configuration of the client system.
: ''Attributes:''
:; <tt>mb = [integer]</tt>
:: Gives the number of megabytes of system memory.

; Element <tt><os></tt>
: Describes the operating system the client is running.
: ''Attributes:''
:; <tt>name = [string]</tt>
:: Gives the name of the operating system, e.g. "Windows" or "MacOSX".
:; <tt>version = [string]</tt>
:: Gives the version of the operating system, e.g. "XP" or "Tiger".

; Element <tt><install></tt>
: Describes the installation of Firefox the user is running.
: ''Attributes:''
:; <tt>buildid = [integer]</tt>
:: Gives the Build ID (e.g. 20060327).
:; <tt>installdate = [integer]</tt>
:: Gives the date the build was first run on this profile (seconds since the epoch).

; Element <tt><extensions></tt>
: A container element for 1 or more <tt>extension</tt> elements.
: ''Attributes:'' none

; Element <tt><extension></tt>
: Contains information about a single extension.
: ''Attributes:''
:; <tt>extensionid = [string]</tt>
:: Gives the extension's id.
:; <tt>version = [string]</tt>
:: Gives the extension's version number.

; Element <tt><plugins></tt>
: A container element for 1 or more <tt>plugin</tt> elements.
: ''Attributes:'' none

; Element <tt><plugin></tt>
: Contains information about a single plugin.
:; <tt>name = [string]</tt>
:: Gives the name of the plugin.
:; <tt>version = [string]</tt>
:: Gives the version of the plugin.

; Element <tt><display></tt>
: Describes the user's display.
: ''Attributes:''
:; <tt>xsize = [integer]</tt>
:: Gives the number of pixels horizontally on the display.
:; <tt>ysize = [integer]</tt>
:: Gives the number of pixels vertically on the display.

TBD: talkback GUID

===Window Event===

Window events log various actions pertaining to DOM Windows, which provide a context for load events.

; Element <tt><window></tt>
: ''Attributes:''
:; <tt>action = [string]</tt>
:: Indicates the action that happened for this window. Possible values are:
::* <tt>create</tt>: a new toplevel or child DOM Window was created
::* <tt>open</tt>: a toplevel DOM Window was opened
::* <tt>close</tt>: a toplevel DOM Window was closed
::* <tt>destroy</tt>: a toplevel or child DOM Window was destroyed
:; <tt>windowid = [integer]</tt>
:: The id of the affected window. Ids are assigned starting from 0 and are never reused during that session. The window id is not unique across sessions.
:; <tt>parent = [integer]</tt> (optional)
:: For create events, the id of the parent of the newly created window. Toplevel windows do not have a parent, so this attribute will not be set.
:; <tt>chrome = [boolean]</tt> (optional)
:: For create events, whether the new window has chrome privileges. Defaults to false.
:; <tt>opener = [integer window id]</tt> (optional)
:: For open events, the id of the opener DOM window. Windows opened from native code may not have an opener, and this attribute will not be set.

===Load Event===

Load events record a document being loaded into a DOM Window.

; Element <tt><load></tt>
: ''Attributes:''
:; <tt>window = [integer]</tt>
:: The id of the window where the document was loaded.
:; <tt>origin = [string]</tt> (optional)
:: The action which initiated the load. Possible values include:
::* <tt>typed</tt>: The document URI was typed (or pasted) by the user.
::* <tt>link</tt>: The user followed a link to the document URI.
::* <tt>session-history</tt>: The user used back/forward navigation to load the document.
::* <tt>reload</tt>: The user used the reload button or keyboard shortcut to reload the document.
::* <tt>global-history</tt>: The user loaded the page by selecting it from their global history.
::* <tt>bookmark</tt>: The user loaded the page by selecting it from the bookmarks menu, bookmarks toolbar, or bookmarks management UI.
::* <tt>script</tt>: A script executing on a page loaded the document.
::* <tt>refresh</tt>: A meta-refresh loaded the document.
::* <tt>external</tt>: The document URI was passed in from an external application.
:; <tt>loadtime = [integer]</tt>
:: The time from the initiation of the load until the document is complete (which includes all images, stylesheet, etc) in milliseconds.
:; <tt>bfCacheHit = [boolean]</tt> (optional)
:: Whether the document presentation was loaded from the session history cache. If not specified, assumed to be false.

Todo / possible todo items:
* cache size before/after load
* content viewer size estimate
* cache hit
* session history index
* last visit date
* tagged/bookmarked

===UI Event===

* action = [click, key, drag, drop...]
* target = [some kind of ID, possibly XUL name]

===Garbage Collection===

* number/size of objects reachable
* time spent doing garbage collection

===Startup/Shutdown===

* time taken

===Places UI Event===

We'll have to be sure not to duplicate data here between the UI Event and the Places UI Event. This could potentially be an extension of the regular UI Event.

* node types expanded/clicked
* periods of time searched

===Autocomplete===

We may try to fit this into the schema of another event type.

* how far down the list?
* match but typed anyway?

===Open Issues===

* We may want to consolidate some of these events into summary statistics, to compact the amount of data we are collecting. However, this may not be necessary since we will be able to throttle the data collection on a per event type.

* To allow extensions to collect data via this system, we will need to define a generic event type or a way to extend the list of predefined events. This is TBD.

* The event types listed above are still in flux and may be combined or removed.

Browser Metrics:Data Collectors

2006-03-28T15:11:51Z

Darin: /* Window Event */

==Data Format==

===Overview===

Data will be collected as a stream of events, with the exception of a user profile that is collected once every browser session. Each event type is represented by a particular XML element in the <tt>http://www.mozilla.org/metrics</tt> namespace. We will define several event types that will have predefined schemas. We will be able to throttle data collection based on the event type, so that verbose events can be turned on and off when we want. The tentative event types and associated schemas are listed below. (Note: the list is still very much in flux and will likely change.)

All event types have a <tt>time</tt> attribute, which gives a timestamp for the event, recorded as seconds since the epoch.

===Profile===

The profile will be collected every browser session, to pick up changes periodically. The profile element is a grouping element which contains a set of profile values.

; Element <tt><profile></tt>
: ''Attributes:'' none

The following elements are optional children of <tt><profile></tt>:

; Element <tt><memory></tt>
: Describes the memory configuration of the client system.
: ''Attributes:''
:; <tt>mb = [integer]</tt>
:: Gives the number of megabytes of system memory.

; Element <tt><os></tt>
: Describes the operating system the client is running.
: ''Attributes:''
:; <tt>name = [string]</tt>
:: Gives the name of the operating system, e.g. "Windows" or "MacOSX".
:; <tt>version = [string]</tt>
:: Gives the version of the operating system, e.g. "XP" or "Tiger".

; Element <tt><install></tt>
: Describes the installation of Firefox the user is running.
: ''Attributes:''
:; <tt>buildid = [integer]</tt>
:: Gives the Build ID (e.g. 20060327).
:; <tt>installdate = [integer]</tt>
:: Gives the date the build was first run on this profile (seconds since the epoch).

; Element <tt><extensions></tt>
: A container element for 1 or more <tt>extension</tt> elements.
: ''Attributes:'' none

; Element <tt><extension></tt>
: Contains information about a single extension.
: ''Attributes:''
:; <tt>extensionid = [string]</tt>
:: Gives the extension's id.
:; <tt>version = [string]</tt>
:: Gives the extension's version number.

; Element <tt><plugins></tt>
: A container element for 1 or more <tt>plugin</tt> elements.
: ''Attributes:'' none

; Element <tt><plugin></tt>
: Contains information about a single plugin.
:; <tt>name = [string]</tt>
:: Gives the name of the plugin.
:; <tt>version = [string]</tt>
:: Gives the version of the plugin.

; Element <tt><display></tt>
: Describes the user's display.
: ''Attributes:''
:; <tt>xsize = [integer]</tt>
:: Gives the number of pixels horizontally on the display.
:; <tt>ysize = [integer]</tt>
:: Gives the number of pixels vertically on the display.

TBD: talkback GUID

===Window Event===

Window events log various actions pertaining to DOM Windows, which provide a context for load events.

; Element <tt><window></tt>
: ''Attributes:''
:; <tt>action = [string]</tt>
:: Indicates the action that happened for this window. Possible values are:
::* <tt>create</tt>: a new toplevel or child DOM Window was created
::* <tt>open</tt>: a toplevel DOM Window was opened
::* <tt>close</tt>: a toplevel DOM Window was closed
::* <tt>destroy</tt>: a toplevel or child DOM Window was destroyed
:; <tt>windowid = [integer]</tt>
:: The id of the affected window. Ids are assigned starting from 0 and are never reused during that session. The window id is not unique across sessions.
:; <tt>parent = [integer]</tt> (optional)
:: For create events, the id of the parent of the newly created window. Toplevel windows do not have a parent, so this attribute will not be set.
:; <tt>chrome = [boolean]</tt> (optional)
:: For create events, whether the new window has chrome privileges. Defaults to false.
:; <tt>opener = [integer window id]</tt> (optional)
:: For open events, the id of the opener DOM window. Windows opened from native code may not have an opener, and this attribute will not be set.

===Load Event===

Load events record a document being loaded into a DOM Window.

Element name: <tt>load</tt>

Attributes:
<tt>window = [integer window id]</tt>

The id of the window where the document was loaded.

<tt>origin = [string]</tt> (optional)

The action which initiated the load. Possible values include:
* <tt>typed</tt>: The document URI was typed (or pasted) by the user.
* <tt>link</tt>: The user followed a link to the document URI.
* <tt>session-history</tt>: The user used back/forward navigation to load the document.
* <tt>reload</tt>: The user used the reload button or keyboard shortcut to reload the document.
* <tt>global-history</tt>: The user loaded the page by selecting it from their global history.
* <tt>bookmark</tt>: The user loaded the page by selecting it from the bookmarks menu, bookmarks toolbar, or bookmarks management UI.
* <tt>script</tt>: A script executing on a page loaded the document.
* <tt>refresh</tt>: A meta-refresh loaded the document.
* <tt>external</tt>: The document URI was passed in from an external application.

<tt>loadtime = [milliseconds]</tt>

The time from the initiation of the load until the document is complete (which includes all images, stylesheet, etc) in milliseconds.

<tt>bfCacheHit = [boolean]</tt> (optional)

Whether the document presentation was loaded from the session history cache. If not specified, assumed to be false.

Todo / possible todo items:
* cache size before/after load
* content viewer size estimate
* cache hit
* session history index
* last visit date
* tagged/bookmarked

===UI Event===

* action = [click, key, drag, drop...]
* target = [some kind of ID, possibly XUL name]

===Garbage Collection===

* number/size of objects reachable
* time spent doing garbage collection

===Startup/Shutdown===

* time taken

===Places UI Event===

We'll have to be sure not to duplicate data here between the UI Event and the Places UI Event. This could potentially be an extension of the regular UI Event.

* node types expanded/clicked
* periods of time searched

===Autocomplete===

We may try to fit this into the schema of another event type.

* how far down the list?
* match but typed anyway?

===Open Issues===

* We may want to consolidate some of these events into summary statistics, to compact the amount of data we are collecting. However, this may not be necessary since we will be able to throttle the data collection on a per event type.

* To allow extensions to collect data via this system, we will need to define a generic event type or a way to extend the list of predefined events. This is TBD.

* The event types listed above are still in flux and may be combined or removed.

Browser Metrics:Data Collectors

2006-03-28T15:08:08Z

Darin: /* Profile */

==Data Format==

===Overview===

Data will be collected as a stream of events, with the exception of a user profile that is collected once every browser session. Each event type is represented by a particular XML element in the <tt>http://www.mozilla.org/metrics</tt> namespace. We will define several event types that will have predefined schemas. We will be able to throttle data collection based on the event type, so that verbose events can be turned on and off when we want. The tentative event types and associated schemas are listed below. (Note: the list is still very much in flux and will likely change.)

All event types have a <tt>time</tt> attribute, which gives a timestamp for the event, recorded as seconds since the epoch.

===Profile===

The profile will be collected every browser session, to pick up changes periodically. The profile element is a grouping element which contains a set of profile values.

; Element <tt><profile></tt>
: ''Attributes:'' none

The following elements are optional children of <tt><profile></tt>:

; Element <tt><memory></tt>
: Describes the memory configuration of the client system.
: ''Attributes:''
:; <tt>mb = [integer]</tt>
:: Gives the number of megabytes of system memory.

; Element <tt><os></tt>
: Describes the operating system the client is running.
: ''Attributes:''
:; <tt>name = [string]</tt>
:: Gives the name of the operating system, e.g. "Windows" or "MacOSX".
:; <tt>version = [string]</tt>
:: Gives the version of the operating system, e.g. "XP" or "Tiger".

; Element <tt><install></tt>
: Describes the installation of Firefox the user is running.
: ''Attributes:''
:; <tt>buildid = [integer]</tt>
:: Gives the Build ID (e.g. 20060327).
:; <tt>installdate = [integer]</tt>
:: Gives the date the build was first run on this profile (seconds since the epoch).

; Element <tt><extensions></tt>
: A container element for 1 or more <tt>extension</tt> elements.
: ''Attributes:'' none

; Element <tt><extension></tt>
: Contains information about a single extension.
: ''Attributes:''
:; <tt>extensionid = [string]</tt>
:: Gives the extension's id.
:; <tt>version = [string]</tt>
:: Gives the extension's version number.

; Element <tt><plugins></tt>
: A container element for 1 or more <tt>plugin</tt> elements.
: ''Attributes:'' none

; Element <tt><plugin></tt>
: Contains information about a single plugin.
:; <tt>name = [string]</tt>
:: Gives the name of the plugin.
:; <tt>version = [string]</tt>
:: Gives the version of the plugin.

; Element <tt><display></tt>
: Describes the user's display.
: ''Attributes:''
:; <tt>xsize = [integer]</tt>
:: Gives the number of pixels horizontally on the display.
:; <tt>ysize = [integer]</tt>
:: Gives the number of pixels vertically on the display.

TBD: talkback GUID

===Window Event===

Window events log various actions pertaining to DOM Windows, which provide a context for load events.

Element name: <tt>window</tt>

Attributes:

<tt>action = [string]</tt>

Indicates the action that happened for this window. Possible values are:
<ul>
<li><tt>create</tt>: a new toplevel or child DOM Window was created</li>
<li><tt>open</tt>: a toplevel DOM Window was opened</li>
<li><tt>close</tt>: a toplevel DOM Window was closed</li>
<li><tt>destroy</tt>: a toplevel or child DOM Window was destroyed</li>
</ul>

<tt>windowid = [integer window id]</tt>

The id of the affected window. Ids are assigned starting from 0 and are never reused during that session. The window id is not unique across sessions.

<tt>parent = [integer window id]</tt> (optional)

For create events, the id of the parent of the newly created window. Toplevel windows do not have a parent, so this attribute will not be set.

<tt>chrome = [boolean]</tt> (optional)

For create events, whether the new window has chrome privileges. Defaults to false.

<tt>opener = [integer window id]</tt> (optional)

For open events, the id of the opener DOM window. Windows opened from native code may not have an opener, and this attribute will not be set.

===Load Event===

Load events record a document being loaded into a DOM Window.

Element name: <tt>load</tt>

Attributes:
<tt>window = [integer window id]</tt>

The id of the window where the document was loaded.

<tt>origin = [string]</tt> (optional)

The action which initiated the load. Possible values include:
* <tt>typed</tt>: The document URI was typed (or pasted) by the user.
* <tt>link</tt>: The user followed a link to the document URI.
* <tt>session-history</tt>: The user used back/forward navigation to load the document.
* <tt>reload</tt>: The user used the reload button or keyboard shortcut to reload the document.
* <tt>global-history</tt>: The user loaded the page by selecting it from their global history.
* <tt>bookmark</tt>: The user loaded the page by selecting it from the bookmarks menu, bookmarks toolbar, or bookmarks management UI.
* <tt>script</tt>: A script executing on a page loaded the document.
* <tt>refresh</tt>: A meta-refresh loaded the document.
* <tt>external</tt>: The document URI was passed in from an external application.

<tt>loadtime = [milliseconds]</tt>

The time from the initiation of the load until the document is complete (which includes all images, stylesheet, etc) in milliseconds.

<tt>bfCacheHit = [boolean]</tt> (optional)

Whether the document presentation was loaded from the session history cache. If not specified, assumed to be false.

Todo / possible todo items:
* cache size before/after load
* content viewer size estimate
* cache hit
* session history index
* last visit date
* tagged/bookmarked

===UI Event===

* action = [click, key, drag, drop...]
* target = [some kind of ID, possibly XUL name]

===Garbage Collection===

* number/size of objects reachable
* time spent doing garbage collection

===Startup/Shutdown===

* time taken

===Places UI Event===

We'll have to be sure not to duplicate data here between the UI Event and the Places UI Event. This could potentially be an extension of the regular UI Event.

* node types expanded/clicked
* periods of time searched

===Autocomplete===

We may try to fit this into the schema of another event type.

* how far down the list?
* match but typed anyway?

===Open Issues===

* We may want to consolidate some of these events into summary statistics, to compact the amount of data we are collecting. However, this may not be necessary since we will be able to throttle the data collection on a per event type.

* To allow extensions to collect data via this system, we will need to define a generic event type or a way to extend the list of predefined events. This is TBD.

* The event types listed above are still in flux and may be combined or removed.

Browser Metrics:Data Collectors

2006-03-28T05:18:37Z

Darin: /* Profile */

==Data Format==

===Overview===

Data will be collected as a stream of events, with the exception of a user profile that is collected once every browser session. Each event type is represented by a particular XML element in the <tt>http://www.mozilla.org/metrics</tt> namespace. We will define several event types that will have predefined schemas. We will be able to throttle data collection based on the event type, so that verbose events can be turned on and off when we want. The tentative event types and associated schemas are listed below. (Note: the list is still very much in flux and will likely change.)

All event types have a <tt>time</tt> attribute, which gives a timestamp for the event, recorded as seconds since the epoch.

===Profile===

The profile will be collected every browser session, to pick up changes periodically. The profile element is a grouping element which contains a set of profile values.

; Element <tt><profile></tt>
: ''Attributes:'' none

The following elements are optional children of <tt><profile></tt>:

; Element <tt><memory></tt>
: Describes the memory configuration of the client system.
: ''Attributes:''
:; <tt>mb = [integer]</tt>
:: Gives the number of megabytes of system memory.

; Element <tt><os></tt>
: Describes the operating system the client is running.
: ''Attributes:''
:; <tt>name = [string]</tt>
:: Gives the name of the operating system, e.g. "Windows" or "MacOSX".
:; <tt>version = [string]</tt>
:: Gives the version of the operating system, e.g. "XP" or "Tiger".

; Element <tt><install></tt>
: Describes the installation of Firefox the user is running.
: ''Attributes:''
:; <tt>buildid = [integer]</tt>
:: Gives the Build ID (e.g. 20060327).
:; <tt>installdate = [integer]</tt>
:: Gives the date the build was first run on this profile (seconds since the epoch).

; Element <tt><extensions></tt>
: A container element for 1 or more <tt>extension</tt> elements.
: ''Attributes:'' none

; Element <tt><extension></tt>
: Contains information about a single extension installed in the profile.
: ''Attributes:''
:; <tt>extensionid = [string]</tt>
:: Gives the extension's id.
:; <tt>version = [string]</tt>
:: Gives the extension's version number.

; Element <tt><plugins></tt>
: A container element for 1 or more <tt>plugin</tt> elements.
: ''Attributes:''
:; <tt>name = [string]</tt>
:: Gives the name of the plugin.
:; <tt>version = [string]</tt>
:: Gives the version of the plugin.

; Element <tt><display></tt>
: Describes the user's display.
: ''Attributes:''
:; <tt>xsize = [integer]</tt>
:: Gives the number of pixels horizontally on the display.
:; <tt>ysize = [integer]</tt>
:: Gives the number of pixels vertically on the display.

TBD: talkback GUID

===Window Event===

Window events log various actions pertaining to DOM Windows, which provide a context for load events.

Element name: <tt>window</tt>

Attributes:

<tt>action = [string]</tt>

Indicates the action that happened for this window. Possible values are:
<ul>
<li><tt>create</tt>: a new toplevel or child DOM Window was created</li>
<li><tt>open</tt>: a toplevel DOM Window was opened</li>
<li><tt>close</tt>: a toplevel DOM Window was closed</li>
<li><tt>destroy</tt>: a toplevel or child DOM Window was destroyed</li>
</ul>

<tt>windowid = [integer window id]</tt>

The id of the affected window. Ids are assigned starting from 0 and are never reused during that session. The window id is not unique across sessions.

<tt>parent = [integer window id]</tt> (optional)

For create events, the id of the parent of the newly created window. Toplevel windows do not have a parent, so this attribute will not be set.

<tt>chrome = [boolean]</tt> (optional)

For create events, whether the new window has chrome privileges. Defaults to false.

<tt>opener = [integer window id]</tt> (optional)

For open events, the id of the opener DOM window. Windows opened from native code may not have an opener, and this attribute will not be set.

===Load Event===

Load events record a document being loaded into a DOM Window.

Element name: <tt>load</tt>

Attributes:
<tt>window = [integer window id]</tt>

The id of the window where the document was loaded.

<tt>origin = [string]</tt> (optional)

The action which initiated the load. Possible values include:
* <tt>typed</tt>: The document URI was typed (or pasted) by the user.
* <tt>link</tt>: The user followed a link to the document URI.
* <tt>session-history</tt>: The user used back/forward navigation to load the document.
* <tt>reload</tt>: The user used the reload button or keyboard shortcut to reload the document.
* <tt>global-history</tt>: The user loaded the page by selecting it from their global history.
* <tt>bookmark</tt>: The user loaded the page by selecting it from the bookmarks menu, bookmarks toolbar, or bookmarks management UI.
* <tt>script</tt>: A script executing on a page loaded the document.
* <tt>refresh</tt>: A meta-refresh loaded the document.
* <tt>external</tt>: The document URI was passed in from an external application.

<tt>loadtime = [milliseconds]</tt>

The time from the initiation of the load until the document is complete (which includes all images, stylesheet, etc) in milliseconds.

<tt>bfCacheHit = [boolean]</tt> (optional)

Whether the document presentation was loaded from the session history cache. If not specified, assumed to be false.

Todo / possible todo items:
* cache size before/after load
* content viewer size estimate
* cache hit
* session history index
* last visit date
* tagged/bookmarked

===UI Event===

* action = [click, key, drag, drop...]
* target = [some kind of ID, possibly XUL name]

===Garbage Collection===

* number/size of objects reachable
* time spent doing garbage collection

===Startup/Shutdown===

* time taken

===Places UI Event===

We'll have to be sure not to duplicate data here between the UI Event and the Places UI Event. This could potentially be an extension of the regular UI Event.

* node types expanded/clicked
* periods of time searched

===Autocomplete===

We may try to fit this into the schema of another event type.

* how far down the list?
* match but typed anyway?

===Open Issues===

* We may want to consolidate some of these events into summary statistics, to compact the amount of data we are collecting. However, this may not be necessary since we will be able to throttle the data collection on a per event type.

* To allow extensions to collect data via this system, we will need to define a generic event type or a way to extend the list of predefined events. This is TBD.

* The event types listed above are still in flux and may be combined or removed.

User:Darin

2006-03-28T01:57:58Z

Darin:

== Darin Fisher ==

http://weblogs.mozillazine.org/darin/

[mailto:darin@meer.net]

Sheriff Schedule

2006-03-28T01:56:58Z

Darin: /* Schedule */

= Schedule =
{|
|Tuesday || 03/28/06 || available
|-
|Wednesday || 03/29/06 || biesi
|-
|Thursday || 03/30/06 || [[User:Darin|Darin Fisher]]
|-
|Friday || 03/31/06 || available
|-
|Saturday || 04/01/06 || #developers
|-
|Sunday || 04/02/06 || #developers
|-
|Monday || 04/03/06 || stuart
|-
|Tuesday || 04/04/06 || vlad
|-
|Wednesday || 04/05/06 || available
|-
|Thursday || 04/06/06 || bryner
|-
|Friday || 04/07/06 || available
|-
|Saturday || 04/08/06 || #developers
|-
|Sunday || 04/09/06 || #developers
|-
|Monday || 04/10/06 || rob_strong
|-
|Tuesday || 04/11/06 || [[User:Dbaron|David Baron]]
|-
|Wednesday || 04/12/06 || available
|-
|Thursday || 04/13/06 || available
|-
|Friday || 04/14/06 || available
|-
|Saturday || 04/15/06 || #developers
|-
|Sunday || 04/16/06 || #developers
|-
|Monday || 04/17/06 || available
|-
|Tuesday || 04/18/06 || brettw
|-
|Wednesday || 04/19/06 || available
|-
|Thursday || 04/20/06 || available
|-
|Friday || 04/21/06 || available
|-
|Saturday || 04/22/06 || #developers
|-
|Sunday || 04/23/06 || #developers
|-
|Monday || 04/24/06 || available
|}

WeeklyUpdates/2006-03-27

2006-03-27T21:20:44Z

Darin: /* In Attendance */

[[Staff/StatusMeetings/2006-03-19|<< previous week]] | [[Staff/StatusMeetings|index]] | [[Staff/StatusMeetings/2006-04-03|next week>>]]

'''Meeting Details'''
* 1:00pm PST (21:00 GMT)
* Mozilla HQ, 1st floor conference table
* 866-432-7917 (US)
* 334-309-0297 (INTL)
* join irc.mozilla.org #staffmeeting for attendance taking

= In Attendance =

bienvenu, blizzard, bsemdberg, darin, dmose, dveditz, hecker, justdave, justin, schrep, tim, preed, basil, rstrong, marcia, choffman, aravind, mscott, matt, karen, davel, mitchell, pav, asa, vlad, myk, dbaron, pkim, jlilly, cbeard

= Agenda =
# Development Updates
# IT Updates
# Marketing Updates
# Roundtable
# Other Business

= Development Updates =
== FF/TB 1.5.0.2/1.0.8 ==

* 1.0.8
** Build
*** Respins for FF CJK due to {{bug|331234}} are needed.
*** FF Mac l10n bits aren't available, due to a bug Preed is tracking down: {{bug|330959}}
*** These are behind 1.5.0.2 build tasks.
*** TB - Needed to be respun with the correct date problem. Also, the Linux bits never got produced, so a respin is required.
*** Will build/test L10n bugs on a "best effort" basis as localizers update from the en-UB build.
** QA
*** FF L10n testing after re-spins
*** TB testing has not yet commensed.

* 1.5.0.2
** Build
*** Completed the trial build for FF universal binary (UB), with the Talkback fix included. Tested well. Ready for final build.
*** Need to look into FF update channel issues.
*** Start l10n for FF 1.5.0.2, since we'll have all the platforms
*** TB: Final tag set, respins, UBs worked out (possibly)
*** We are debating whether to ship UB for TB. There are signifcant issues here. One is {{bug|331511}}.
** QA
*** FF testing to be done: Smoke test UB once final build is available. Start L10n testing. Update verification
*** TB testing to be done: UB testing - awaiting official binary. Need to continue with verifications (critical and security bugs). L10n testing

== FF/TB 1.5.0.3 ==

* Started triaging bugs. This is the earliest we have started for the 1.5.0.x releases!
* Starting with Blocker Nominations: ~22 triaged on Fri. 26 done today. 23 still in the queue.
* Hoping to start approving patches and open the 1.8.0 branch ~Wednesday.

== FF 2.0 ==
* All information updated [[Firefox2|here]]
* A1 Has Shipped
** Places backend
** Extension blacklisting
** Extension dependencies
** Search plugin format changeover
** RSS content detection
* Planning begun for A2
** Intended to be feature complete
** Scoping of work begun
* '''action:''' Review [[Firefox2|Planning Docs]] and give feedback in moz.dev.apps.firefox or moz.dev.planning

== TB 2.0 ==
* We are sending out Firefox developer shirts to some of the Thunderbird 1.5 contributors who didn't already receive Firefox shirts. We're almost done with the thank you letters. Many thanks to Marcia and Karen for helping to send out the thank you packages.
*Several of the Thunderbird 2 features are now available on the 1.8.1 branch for testing including folder views, new mail alert notifications, and folder summary tooltips.
* 1.5.0.2 getting close!

== Gecko 1.9 ==

= IT Updates =

* Colo Progress
** Network design drafts complete - will have breakout session on network design
* Wiki & Firefox Flicks migrated to the LVS cluster
* Firewall migration
** More capacity - 5 minute or less outage at Meer
** Planned for this weekend - more info to come
* Newsgroups
** Progressing slowly with Google - have several open tickets; posting through Google Groups and Giganews should be possible (according to Google)
* Service Requests
** Just a reminder to send all service requests through bugzilla - [https://bugzilla.mozilla.org/enter_bug.cgi?product=mozilla.org&format=itrequest bugzilla link]
* Addons2

= Marketing Updates =

* Firefox Flicks Ad Contest well underway
** ~70 submissions received so far
** Contest ends April 14, 2006
** This week, launching enhanced [http://www.FirefoxFlicks.com FirefoxFlicks.com] with capability to view and share Flicks ads.
** 4 Flicks ads to be screened at Vail Film Festival as part of Oscar Shorts Showcase on March 31.
* Planning for Firefox 2 marketing launch beginning this week.
* Updates to tools and infrastructure at [http://www.SpreadFirefox.com SpreadFirefox.com] coming this Spring, to enable SFx members easier ways to plan, initiate and share community marketing projects.
* Mozilla will be co-hosting the 2006 XTech Conference in Amsterdam from May 16th to 19th, for more information see http://www.xtech-conference.org
** We will be offering scholarships for Mozilla contributors to attend. cbeard is organizing.

= Roundtable =

= Other Business =

XPCOM:nsIThreadManager

2006-03-16T21:18:35Z

Darin: /* Development */

In a world without nested event queues, the concept of a thread and an event queue merge...

== Interfaces ==
=== nsIThreadManager ===
[scriptable, uuid(...)]
interface nsIThreadManager : nsISupports {
/**
* Create a new named thread (a global, user PRThread). If the name is
* non-empty, then the name of the thread must be unique. Specifying an
* empty name results in an anonymous thread that cannot be found later on
* using the getThread method.
*/
nsIThread newThread(in ACString name);
 
/**
* Find a named thread. If no thread exists by the given name, then null
* is returned.
*/
nsIThread getThread(in ACString name);
 
/**
* Get the nsIThread object (if any) corresponding to the given PRThread.
* This method returns null if there is no corresponding nsIThread.
*/
[noscript] nsIThread getThreadFromPRThread(in PRThread thread);
 
/**
* Get the main thread.
*/
readonly attribute nsIThread mainThread;
 
/**
* Get the current thread.
*/
readonly attribute nsIThread currentThread;
 
/**
* This attribute is true if the calling thread is the main thread of the
* application process.
*/
readonly attribute boolean isMainThread;
};

=== nsIEventTarget ===
[scriptable, uuid(...)]
interface nsIEventTarget : nsISupports {
/**
* Dispatch an event to the target. This function may be called from any
* thread. If flags specifies DISPATCH_SYNC, then the dispatch method
* will not return until the event has been processed. NOTE: Calling
* dispatch with DISPATCH_SYNC, may have the side-effect of running other
* events on the current thread while waiting for the given event to run
* to completion. This function is thread-safe and re-entrant.
*/
void dispatch(in nsIRunnable event, in unsigned long flags);
const unsigned long DISPATCH_NORMAL = 0;
const unsigned long DISPATCH_SYNC = 1;
 
/**
* Returns true if events dispatched to this target will run on the
* current thread (i.e., the thread calling this method).
*/
boolean isOnCurrentThread();
};
 
%{C++
// convenient aliases:
#define NS_DISPATCH_NORMAL nsIEventTarget::DISPATCH_NORMAL
#define NS_DISPATCH_SYNC nsIEventTarget::DISPATCH_SYNC
%}

=== nsIThread ===
[scriptable, uuid(...)]
interface nsIThread : nsIEventTarget {
/**
* Returns the name of the thread, which may be empty if this thread is
* anonymous.
*/
readonly attribute ACString name;
 
/**
* Returns the PRThread object corresponding to this nsIThread.
*/
[noscript] PRThread getPRThread();
 
/**
* Shutdown the thread. This method may not be executed from the thread
* itself. Instead, it is meant to be executed from another thread (usually
* the thread that created this thread). When this function returns, the
* thread will be shutdown, and it will no longer be possible to dispatch
* events to the thread.
*/
void shutdown();
 
/**
* Returns true if this thread has one or more pending events.
*/
boolean hasPendingEvents();
 
/**
* Process the next event. If there are no pending events, then this
* method will wait until an event is dispatched to this thread. This
* method is re-entrant but may only be called if this thread is the
* current thread.
*/
void processNextEvent();
};
=== nsIThreadInternal ===
[scriptable, uuid(...)]
interface nsIThreadInternal : nsIThread {
/**
* Get/set an observer for this thread (may be null). This attribute may
* be read from any thread, but must only be set on the thread corresponding
* to this thread object.
*/
attribute nsIThreadObserver observer;
 
/**
* This method causes any events currently enqueued on the thread to be
* suppressed until PopEventQueue is called. Additionally, any new events
* dispatched to the thread will only be processed if they are accepted by
* the given filter. If the filter is null, then new events are accepted.
* Calls to PushEventQueue may be nested and must each be paired with a call
* to PopEventQueue in order to restore the original state of the thread.
*/
void pushEventQueue(in nsIThreadEventFilter filter);
 
/**
* Revert a call to PushEventQueue. When an event queue is popped, any
* events remaining in the queue are appended to the elder queue.
*/
void popEventQueue();
};

=== nsIThreadObserver ===
[scriptable, uuid(...)]
interface nsIThreadObserver : nsISupports {
/**
* This method is called after an event has been dispatched to the thread.
* This method may be called from any thread.
*/
void onDispatchedEvent(in nsIThreadInternal thread);
 
/**
* This method is called (from nsIThread::ProcessNextEvent) before an event
* is processed. This method is only called on the target thread.
*
* @param thread
* The thread being asked to process another event.
* @param mayWait
* Indicates whether or not the method is allowed to block the calling
* thread. For example, this parameter is false during thread shutdown.
* @param recursionDepth
* Indicates the number of calls to ProcessNextEvent on the call stack
* in addition to the current call.
*/
void onProcessNextEvent(in nsIThreadInternal thread, in boolean mayWait,
in unsigned long recursionDepth);
};

=== nsIThreadEventFilter ===
[scriptable, uuid(...)]
interface nsIThreadEventFilter : nsISupports {
/**
* This method is called to determine whether or not an event may be accepted
* by a "nested" event queue (see nsIThreadInternal::PushEventQueue).
*
* WARNING: This method must not make any calls on the thread object.
*/
[notxpcom] boolean AcceptEvent(in nsIRunnable event);
};

=== nsIThreadPool ===
[scriptable, uuid(...)]
interface nsIThreadPool : nsIEventTarget
{
/**
* Shutdown the thread pool. This method may not be executed from any
* thread in the thread pool. Instead, it is meant to be executed from
* another thread (usually the thread that created this thread pool).
* When this function returns, the thread pool and all of its threads will
* be shutdown, and it will no longer be possible to dispatch tasks to the
* thread pool.
*/
void shutdown()
 
/**
* Get/set the maximum number of threads allowed at one time in this pool.
*/
attribute unsigned long threadLimit;
 
/**
* Get/set the maximum number of idle threads kept alive.
*/
attribute unsigned long idleThreadLimit;
 
/**
* Get/set the amount of time in milliseconds before an idle thread is
* destroyed.
*/
attribute unsigned long idleThreadTimeout;
};

== C++ Utilities ==

=== Functions ===
nsThreadUtils.h defines the following helper functions:

/**
* Create a new thread.
*
* @param name
* The name of the thread (must be unique) or the empty string to
* create an anonymous thread.
* @param event
* The initial event to run on this thread. This can be null.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_NewThread(const nsACString &name, nsIRunnable *event,
nsIThread **result);
 
/**
* Get a reference to the current thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetCurrentThread(nsIThread **result);
 
/**
* Get a reference to the main thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetMainThread(nsIThread **result);
 
/**
* Get a reference to the thread with the given name.
*
* @param name
* The name of the requested thread. Must be non-empty.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetThread(const nsACString &name, nsIThread **result);
 
/**
* Test to see if the current thread is the main thread.
*
* @returns PR_TRUE if the current thread is the main thread, and PR_FALSE
* otherwise.
*/
PRBool NS_IsMainThread();
 
/**
* Dispatch the given event to the current thread.
*
* @param event
* The event to dispatch.
*/
NS_METHOD NS_DispatchToCurrentThread(nsIRunnable *event);
 
/**
* Dispatch the given event to the main thread.
*
* @param event
* The event to dispatch.
* @param dispatchFlags
* The flags to pass to the main thread's dispatch method.
*/
NS_METHOD NS_DispatchToMainThread(nsIRunnable *event,
PRUint32 dispatchFlags = NS_DISPATCH_NORMAL);
 
/**
* Process all pending events for the given thread before returning. This
* method simply calls ProcessNextEvent on the thread while HasPendingEvents
* continues to return true and the time spent in NS_ProcessPendingEvents
* does not exceed the given timeout value.
*
* @param thread
* The thread object for which to process pending events. If null,
* then events will be processed for the current thread.
* @param timeout
* The maximum number of milliseconds to spend processing pending
* events. Events are not pre-empted to honor this timeout. Rather,
* the timeout value is simply used to determine whether or not to
* process another event. Pass PR_INTERVAL_NO_TIMEOUT to specify no
* timeout.
*/
NS_METHOD NS_ProcessPendingEvents(nsIThread *thread = nsnull,
PRIntervalTime timeout = PR_INTERVAL_NO_TIMEOUT);

=== nsCOMPtr helpers ===
The following nsCOMPtr helpers are defined to simplify things further:

already_AddRefed<nsIThread> do_GetCurrentThread();
 
already_AddRefed<nsIThread> do_GetMainThread();
 
already_AddRefed<nsIThread> do_GetThread(const nsACString &name);

=== nsRunnable ===
The class <code>nsRunnable</code> is also defined to simplify the
implementation of new event types. For example, to define a new
event all you need to do is write code like this:

class MyEvent : public nsRunnable {
public:
MyEvent(... params ...);
 
NS_IMETHOD Run() {
// do stuff
return NS_OK;
}
};

Dispatching <code>MyEvent</code> is then as simple as:

nsCOMPtr<nsIThread> thread = do_GetCurrentThread();
NS_ENSURE_STATE(thread);
 
nsCOMPtr<nsIRunnable> event = new MyEvent();
NS_ENSURE_STATE(event);
 
thread->Dispatch(event, NS_DISPATCH_NORMAL);

== From JS ==

=== Event Dispatch ===
Threads and Thread Manager implement <code>nsIClassInfo</code>:

function MyEvent() {
}
MyEvent.prototype = {
QueryInterface: function(iid) {
if (iid.equals(Components.interfaces.nsIRunnable) ||
iid.equals(Components.interfaces.nsISupports))
return this;
throw Components.results.NS_ERROR_NO_INTERFACE;
},
run: function() {
// do stuff
}
};
 
function DispatchMyEvent() {
var target =
Components.classes["@mozilla.org/thread-manager;1"].
getService().currentThread;
 
target.dispatch(new MyEvent(), target.DISPATCH_NORMAL);
}

== Remarks ==

* Thread priority for native threads can be exposed via <code>nsISupportsPriority</code>.
* Thread names must be unique.
* The Necko I/O thread pool will be replaced by a generic thread pool implementation provided by XPCOM. The thread pool will implement <code>nsIEventTarget</code>, allowing events to be dispatched to any thread in the thread pool. We may even wish to define a <code>nsIThreadPool</code> interface and have it implement that as well. That interface would define methods to adjust the limits on the number of threads in the thread pool and so on.
* We will need an alternative for <code>nsIEventQueue::RevokeEvents</code>. There are several possibilities: (1) make consumers hold references to their nsIRunnable's so they can "disconnect" them manually, or (2) expose an enumeration/visitor API that allows consumers to walk the list of pending tasks and remove arbitrary tasks. I'm not sure what is best yet. The first option or something similar based on weak references is probably best as it avoids the costly O(n) <code>RevokeEvents</code> call.
* The following interfaces/classes would go away or be modified heavily: <code>nsIEventQueue</code>, <code>nsIEventQueueService</code>, <code>nsIEventTarget</code>, <code>nsIThread</code>, <code>PLEvent</code>.
* Issue: Perhaps we should support calling <code>nsIThread::Shutdown</code> from the thread itself. That would probably have to be implemented by posting an event to the main thread, and having that thread call shutdown. However, <code>Shutdown</code> also has the property that it does not return until the thread is gone. That obvious can't happen if <code>Shutdown</code> is called on the thread itself.

=== What about "native" event queues? ===
The main thread where UI events are processed and the socket transport thread will use the observer interface defined by <code>nsIThreadInternal</code>. The main thread will interact with the "native" event system during calls to <code>ProcessNextEvent</code> and <code>Dispatch</code>. Likewise, the socket transport thread will similarly need to poll sockets and perform I/O operations. By observing calls to <code>ProcessNextEvent</code>, observers can wait on a native event queue (or poll on a set of file descriptors) instead of waiting on the thread's internal event queue monitor. When they observe a call to <code>Dispatch</code>, they can use whatever mechanism is appropriate to unblock the thread that is waiting on the native event queue.

=== How do synchronous events work? ===

When <code>Dispatch(event, DISPATCH_SYNC)</code> is called on a <code>nsIEventTarget</code>, it first checks to see if the current thread is the same as the thread where the event would be run. If it is, then it just runs the event directly without queuing it up. However, if not, then it must queue the event to be run when the dispatch target next processes its events. To avoid returning to the caller immediately, the method gets the current thread and calls its <code>ProcessNextEvent</code> method in a loop until it receives acknowledgement that the queued event has been run.

== Development ==

Development is occuring on the THREADS_20060307_BRANCH. See also {{bug|326273}}.

== Comments ==

=== biesi: ===
* What happens if shutdown is called while an event is being processed? I assume that this event will be processed to its end, no further events are accepted, and then the thread is shut down. right?
** What happens to events that were already dispatched to this thread, but not run?
* Is it a good idea to allow other events to run on the current thread while in dispatch?
* Who is expected to call ProcessNextEvent?

==== darin: ====
* When asked to shutdown, a thread would finish dispatching all queued events, and refuse to accept any new events. Once all queued events run to completion, the thread would terminate. This is consistent with how event queues work today.
* If you are sync dispatching, then it is necessary to pump events on the calling thread or else you could end up in a dead-lock situation. For example, if thread A sync dispatches an event to thread B, which cannot complete its job without dispatching an event back to thread A, then the system will dead-lock unless thread A continues to dispatch pending events.
* <code>ProcessNextEvent</code> may be called by anybody that wishes to implement the concept of a "modal event loop." For example, XMLHttpRequest (in sync configuration) would sit in a loop calling <code>ProcessNextEvent</code> while waiting for the underlying HTTP transaction to complete. The key difference between <code>ProcessNextEvent</code> and <code>nsIEventQueue::ProcessPendingEvents</code> is that <code>ProcessNextEvent</code>, when called on the UI thread, will process UI events as well. And, it will also wait (block the thread of execution) if there are no UI events or pending <code>nsIRunnable</code> events.

=== dbaron: ===
So mrbkap was telling me at lunch about what's essentially the third bullet point of your comment to biesi above -- that you're making the concept of "modal event loop" even more powerful. This actually scares me a good bit, because these modal event loops happen within another event -- an event that may have state on the stack (e.g., |this| parameters) that could be destroyed by the processing of further events, or may have posted events that rely on the event completing. I really don't like the mix of programming models here that makes it very hard to write robust code, and I wish we could avoid this whole concept altogether rather than making it even more powerful, and thus more dangerous. We already have crashes where frame trees get destroyed while processing an event that are related to the Windows API's way of doing the same thing, though (for, e.g., a DestroyWindow call or whatever it's called).

==== darin: ====
Yup, I'm aware of that issue. In fact, the problem already exists today. There are some places in the code where WaitPLEvent + HandleEvent are called in a loop waiting for an event to process. That bypasses PL_ProcessPendingEvents recursion restriction. PopThreadEventQueue does not behave as you would expect either. It can cause ProcessPendingEvents to run for all but the PLEventQueue that is the subject of the current call to PL_ProcessPendingEvents on the stack. That defeats the purpose of the nested event queue in the first place.

The problem you describe with layout events also occurs for nsIStreamListener implementations. It would be really wierd if OnDataAvailable were called recursively, or if OnDataAvailable were called while the consumer is calling nsIChannel::AsyncOpen. These specific problems are dealt with in nsBaseChannel.cpp by temporarily suspending the channel during callbacks. That suppresses recusive stream listener calls.

Do you have a suggestion that would allow us to prevent this problem? Is there a better way to make XMLHttpRequest.send, document.load, window.alert, etc. appear modal to the calling Javascript?

For C++ consumers, we'd have to basically eliminate modal dialogs altogether to avoid this problem. Today, we have bugs where downloads stall and get disconnected all because the browser popped up a modal dialog and the dialog was not closed promptly enough by the user. That's just unacceptable. And, nsIPromptService is frozen.

I think the answer is to be careful about making callbacks across XPCOM boundaries where event queues may be pumped. Maybe the layout code needs to unwind the stack more before allowing such callbacks to happen so that it can be sure that event processing won't be the end of the world.

dbaron: Also, with the new push/popEventQueue API defined on nsIThreadInternal, it is possible to suppress event dispatch for a particular scope. That is needed to implement synchronous XPCOM proxy calls. I'm assuming that any proper use of synchronous XPCOM proxy calls will be one that completes relatively quickly so as to negate the effects of locking up the browser. We should probably be very careful about calling PushEventQueue on the main thread, where it would potentially disrupt the browser UI. Native events would still be dispatched as always, but without application level events, the UI isn't very useful.

XPCOM:nsIThreadManager

2006-03-16T21:02:40Z

Darin: /* nsIThreadObserver */

In a world without nested event queues, the concept of a thread and an event queue merge...

== Interfaces ==
=== nsIThreadManager ===
[scriptable, uuid(...)]
interface nsIThreadManager : nsISupports {
/**
* Create a new named thread (a global, user PRThread). If the name is
* non-empty, then the name of the thread must be unique. Specifying an
* empty name results in an anonymous thread that cannot be found later on
* using the getThread method.
*/
nsIThread newThread(in ACString name);
 
/**
* Find a named thread. If no thread exists by the given name, then null
* is returned.
*/
nsIThread getThread(in ACString name);
 
/**
* Get the nsIThread object (if any) corresponding to the given PRThread.
* This method returns null if there is no corresponding nsIThread.
*/
[noscript] nsIThread getThreadFromPRThread(in PRThread thread);
 
/**
* Get the main thread.
*/
readonly attribute nsIThread mainThread;
 
/**
* Get the current thread.
*/
readonly attribute nsIThread currentThread;
 
/**
* This attribute is true if the calling thread is the main thread of the
* application process.
*/
readonly attribute boolean isMainThread;
};

=== nsIEventTarget ===
[scriptable, uuid(...)]
interface nsIEventTarget : nsISupports {
/**
* Dispatch an event to the target. This function may be called from any
* thread. If flags specifies DISPATCH_SYNC, then the dispatch method
* will not return until the event has been processed. NOTE: Calling
* dispatch with DISPATCH_SYNC, may have the side-effect of running other
* events on the current thread while waiting for the given event to run
* to completion. This function is thread-safe and re-entrant.
*/
void dispatch(in nsIRunnable event, in unsigned long flags);
const unsigned long DISPATCH_NORMAL = 0;
const unsigned long DISPATCH_SYNC = 1;
 
/**
* Returns true if events dispatched to this target will run on the
* current thread (i.e., the thread calling this method).
*/
boolean isOnCurrentThread();
};
 
%{C++
// convenient aliases:
#define NS_DISPATCH_NORMAL nsIEventTarget::DISPATCH_NORMAL
#define NS_DISPATCH_SYNC nsIEventTarget::DISPATCH_SYNC
%}

=== nsIThread ===
[scriptable, uuid(...)]
interface nsIThread : nsIEventTarget {
/**
* Returns the name of the thread, which may be empty if this thread is
* anonymous.
*/
readonly attribute ACString name;
 
/**
* Returns the PRThread object corresponding to this nsIThread.
*/
[noscript] PRThread getPRThread();
 
/**
* Shutdown the thread. This method may not be executed from the thread
* itself. Instead, it is meant to be executed from another thread (usually
* the thread that created this thread). When this function returns, the
* thread will be shutdown, and it will no longer be possible to dispatch
* events to the thread.
*/
void shutdown();
 
/**
* Returns true if this thread has one or more pending events.
*/
boolean hasPendingEvents();
 
/**
* Process the next event. If there are no pending events, then this
* method will wait until an event is dispatched to this thread. This
* method is re-entrant but may only be called if this thread is the
* current thread.
*/
void processNextEvent();
};
=== nsIThreadInternal ===
[scriptable, uuid(...)]
interface nsIThreadInternal : nsIThread {
/**
* Get/set an observer for this thread (may be null). This attribute may
* be read from any thread, but must only be set on the thread corresponding
* to this thread object.
*/
attribute nsIThreadObserver observer;
 
/**
* This method causes any events currently enqueued on the thread to be
* suppressed until PopEventQueue is called. Additionally, any new events
* dispatched to the thread will only be processed if they are accepted by
* the given filter. If the filter is null, then new events are accepted.
* Calls to PushEventQueue may be nested and must each be paired with a call
* to PopEventQueue in order to restore the original state of the thread.
*/
void pushEventQueue(in nsIThreadEventFilter filter);
 
/**
* Revert a call to PushEventQueue. When an event queue is popped, any
* events remaining in the queue are appended to the elder queue.
*/
void popEventQueue();
};

=== nsIThreadObserver ===
[scriptable, uuid(...)]
interface nsIThreadObserver : nsISupports {
/**
* This method is called after an event has been dispatched to the thread.
* This method may be called from any thread.
*/
void onDispatchedEvent(in nsIThreadInternal thread);
 
/**
* This method is called (from nsIThread::ProcessNextEvent) before an event
* is processed. This method is only called on the target thread.
*
* @param thread
* The thread being asked to process another event.
* @param mayWait
* Indicates whether or not the method is allowed to block the calling
* thread. For example, this parameter is false during thread shutdown.
* @param recursionDepth
* Indicates the number of calls to ProcessNextEvent on the call stack
* in addition to the current call.
*/
void onProcessNextEvent(in nsIThreadInternal thread, in boolean mayWait,
in unsigned long recursionDepth);
};

=== nsIThreadEventFilter ===
[scriptable, uuid(...)]
interface nsIThreadEventFilter : nsISupports {
/**
* This method is called to determine whether or not an event may be accepted
* by a "nested" event queue (see nsIThreadInternal::PushEventQueue).
*
* WARNING: This method must not make any calls on the thread object.
*/
[notxpcom] boolean AcceptEvent(in nsIRunnable event);
};

=== nsIThreadPool ===
[scriptable, uuid(...)]
interface nsIThreadPool : nsIEventTarget
{
/**
* Shutdown the thread pool. This method may not be executed from any
* thread in the thread pool. Instead, it is meant to be executed from
* another thread (usually the thread that created this thread pool).
* When this function returns, the thread pool and all of its threads will
* be shutdown, and it will no longer be possible to dispatch tasks to the
* thread pool.
*/
void shutdown()
 
/**
* Get/set the maximum number of threads allowed at one time in this pool.
*/
attribute unsigned long threadLimit;
 
/**
* Get/set the maximum number of idle threads kept alive.
*/
attribute unsigned long idleThreadLimit;
 
/**
* Get/set the amount of time in milliseconds before an idle thread is
* destroyed.
*/
attribute unsigned long idleThreadTimeout;
};

== C++ Utilities ==

=== Functions ===
nsThreadUtils.h defines the following helper functions:

/**
* Create a new thread.
*
* @param name
* The name of the thread (must be unique) or the empty string to
* create an anonymous thread.
* @param event
* The initial event to run on this thread. This can be null.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_NewThread(const nsACString &name, nsIRunnable *event,
nsIThread **result);
 
/**
* Get a reference to the current thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetCurrentThread(nsIThread **result);
 
/**
* Get a reference to the main thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetMainThread(nsIThread **result);
 
/**
* Get a reference to the thread with the given name.
*
* @param name
* The name of the requested thread. Must be non-empty.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetThread(const nsACString &name, nsIThread **result);
 
/**
* Test to see if the current thread is the main thread.
*
* @returns PR_TRUE if the current thread is the main thread, and PR_FALSE
* otherwise.
*/
PRBool NS_IsMainThread();
 
/**
* Dispatch the given event to the current thread.
*
* @param event
* The event to dispatch.
*/
NS_METHOD NS_DispatchToCurrentThread(nsIRunnable *event);
 
/**
* Dispatch the given event to the main thread.
*
* @param event
* The event to dispatch.
* @param dispatchFlags
* The flags to pass to the main thread's dispatch method.
*/
NS_METHOD NS_DispatchToMainThread(nsIRunnable *event,
PRUint32 dispatchFlags = NS_DISPATCH_NORMAL);
 
/**
* Process all pending events for the given thread before returning. This
* method simply calls ProcessNextEvent on the thread while HasPendingEvents
* continues to return true and the time spent in NS_ProcessPendingEvents
* does not exceed the given timeout value.
*
* @param thread
* The thread object for which to process pending events. If null,
* then events will be processed for the current thread.
* @param timeout
* The maximum number of milliseconds to spend processing pending
* events. Events are not pre-empted to honor this timeout. Rather,
* the timeout value is simply used to determine whether or not to
* process another event. Pass PR_INTERVAL_NO_TIMEOUT to specify no
* timeout.
*/
NS_METHOD NS_ProcessPendingEvents(nsIThread *thread = nsnull,
PRIntervalTime timeout = PR_INTERVAL_NO_TIMEOUT);

=== nsCOMPtr helpers ===
The following nsCOMPtr helpers are defined to simplify things further:

already_AddRefed<nsIThread> do_GetCurrentThread();
 
already_AddRefed<nsIThread> do_GetMainThread();
 
already_AddRefed<nsIThread> do_GetThread(const nsACString &name);

=== nsRunnable ===
The class <code>nsRunnable</code> is also defined to simplify the
implementation of new event types. For example, to define a new
event all you need to do is write code like this:

class MyEvent : public nsRunnable {
public:
MyEvent(... params ...);
 
NS_IMETHOD Run() {
// do stuff
return NS_OK;
}
};

Dispatching <code>MyEvent</code> is then as simple as:

nsCOMPtr<nsIThread> thread = do_GetCurrentThread();
NS_ENSURE_STATE(thread);
 
nsCOMPtr<nsIRunnable> event = new MyEvent();
NS_ENSURE_STATE(event);
 
thread->Dispatch(event, NS_DISPATCH_NORMAL);

== From JS ==

=== Event Dispatch ===
Threads and Thread Manager implement <code>nsIClassInfo</code>:

function MyEvent() {
}
MyEvent.prototype = {
QueryInterface: function(iid) {
if (iid.equals(Components.interfaces.nsIRunnable) ||
iid.equals(Components.interfaces.nsISupports))
return this;
throw Components.results.NS_ERROR_NO_INTERFACE;
},
run: function() {
// do stuff
}
};
 
function DispatchMyEvent() {
var target =
Components.classes["@mozilla.org/thread-manager;1"].
getService().currentThread;
 
target.dispatch(new MyEvent(), target.DISPATCH_NORMAL);
}

== Remarks ==

* Thread priority for native threads can be exposed via <code>nsISupportsPriority</code>.
* Thread names must be unique.
* The Necko I/O thread pool will be replaced by a generic thread pool implementation provided by XPCOM. The thread pool will implement <code>nsIEventTarget</code>, allowing events to be dispatched to any thread in the thread pool. We may even wish to define a <code>nsIThreadPool</code> interface and have it implement that as well. That interface would define methods to adjust the limits on the number of threads in the thread pool and so on.
* We will need an alternative for <code>nsIEventQueue::RevokeEvents</code>. There are several possibilities: (1) make consumers hold references to their nsIRunnable's so they can "disconnect" them manually, or (2) expose an enumeration/visitor API that allows consumers to walk the list of pending tasks and remove arbitrary tasks. I'm not sure what is best yet. The first option or something similar based on weak references is probably best as it avoids the costly O(n) <code>RevokeEvents</code> call.
* The following interfaces/classes would go away or be modified heavily: <code>nsIEventQueue</code>, <code>nsIEventQueueService</code>, <code>nsIEventTarget</code>, <code>nsIThread</code>, <code>PLEvent</code>.
* Issue: Perhaps we should support calling <code>nsIThread::Shutdown</code> from the thread itself. That would probably have to be implemented by posting an event to the main thread, and having that thread call shutdown. However, <code>Shutdown</code> also has the property that it does not return until the thread is gone. That obvious can't happen if <code>Shutdown</code> is called on the thread itself.

=== What about "native" event queues? ===
The main thread where UI events are processed and the socket transport thread will use the observer interface defined by <code>nsIThreadInternal</code>. The main thread will interact with the "native" event system during calls to <code>ProcessNextEvent</code> and <code>Dispatch</code>. Likewise, the socket transport thread will similarly need to poll sockets and perform I/O operations. By observing calls to <code>ProcessNextEvent</code>, observers can wait on a native event queue (or poll on a set of file descriptors) instead of waiting on the thread's internal event queue monitor. When they observe a call to <code>Dispatch</code>, they can use whatever mechanism is appropriate to unblock the thread that is waiting on the native event queue.

=== How do synchronous events work? ===

When <code>Dispatch(event, DISPATCH_SYNC)</code> is called on a <code>nsIEventTarget</code>, it first checks to see if the current thread is the same as the thread where the event would be run. If it is, then it just runs the event directly without queuing it up. However, if not, then it must queue the event to be run when the dispatch target next processes its events. To avoid returning to the caller immediately, the method gets the current thread and calls its <code>ProcessNextEvent</code> method in a loop until it receives acknowledgement that the queued event has been run.

== Development ==

Development is occuring on the THREADS_20060213_BRANCH. See also {{bug|326273}}.

== Comments ==

=== biesi: ===
* What happens if shutdown is called while an event is being processed? I assume that this event will be processed to its end, no further events are accepted, and then the thread is shut down. right?
** What happens to events that were already dispatched to this thread, but not run?
* Is it a good idea to allow other events to run on the current thread while in dispatch?
* Who is expected to call ProcessNextEvent?

==== darin: ====
* When asked to shutdown, a thread would finish dispatching all queued events, and refuse to accept any new events. Once all queued events run to completion, the thread would terminate. This is consistent with how event queues work today.
* If you are sync dispatching, then it is necessary to pump events on the calling thread or else you could end up in a dead-lock situation. For example, if thread A sync dispatches an event to thread B, which cannot complete its job without dispatching an event back to thread A, then the system will dead-lock unless thread A continues to dispatch pending events.
* <code>ProcessNextEvent</code> may be called by anybody that wishes to implement the concept of a "modal event loop." For example, XMLHttpRequest (in sync configuration) would sit in a loop calling <code>ProcessNextEvent</code> while waiting for the underlying HTTP transaction to complete. The key difference between <code>ProcessNextEvent</code> and <code>nsIEventQueue::ProcessPendingEvents</code> is that <code>ProcessNextEvent</code>, when called on the UI thread, will process UI events as well. And, it will also wait (block the thread of execution) if there are no UI events or pending <code>nsIRunnable</code> events.

=== dbaron: ===
So mrbkap was telling me at lunch about what's essentially the third bullet point of your comment to biesi above -- that you're making the concept of "modal event loop" even more powerful. This actually scares me a good bit, because these modal event loops happen within another event -- an event that may have state on the stack (e.g., |this| parameters) that could be destroyed by the processing of further events, or may have posted events that rely on the event completing. I really don't like the mix of programming models here that makes it very hard to write robust code, and I wish we could avoid this whole concept altogether rather than making it even more powerful, and thus more dangerous. We already have crashes where frame trees get destroyed while processing an event that are related to the Windows API's way of doing the same thing, though (for, e.g., a DestroyWindow call or whatever it's called).

==== darin: ====
Yup, I'm aware of that issue. In fact, the problem already exists today. There are some places in the code where WaitPLEvent + HandleEvent are called in a loop waiting for an event to process. That bypasses PL_ProcessPendingEvents recursion restriction. PopThreadEventQueue does not behave as you would expect either. It can cause ProcessPendingEvents to run for all but the PLEventQueue that is the subject of the current call to PL_ProcessPendingEvents on the stack. That defeats the purpose of the nested event queue in the first place.

The problem you describe with layout events also occurs for nsIStreamListener implementations. It would be really wierd if OnDataAvailable were called recursively, or if OnDataAvailable were called while the consumer is calling nsIChannel::AsyncOpen. These specific problems are dealt with in nsBaseChannel.cpp by temporarily suspending the channel during callbacks. That suppresses recusive stream listener calls.

Do you have a suggestion that would allow us to prevent this problem? Is there a better way to make XMLHttpRequest.send, document.load, window.alert, etc. appear modal to the calling Javascript?

For C++ consumers, we'd have to basically eliminate modal dialogs altogether to avoid this problem. Today, we have bugs where downloads stall and get disconnected all because the browser popped up a modal dialog and the dialog was not closed promptly enough by the user. That's just unacceptable. And, nsIPromptService is frozen.

I think the answer is to be careful about making callbacks across XPCOM boundaries where event queues may be pumped. Maybe the layout code needs to unwind the stack more before allowing such callbacks to happen so that it can be sure that event processing won't be the end of the world.

dbaron: Also, with the new push/popEventQueue API defined on nsIThreadInternal, it is possible to suppress event dispatch for a particular scope. That is needed to implement synchronous XPCOM proxy calls. I'm assuming that any proper use of synchronous XPCOM proxy calls will be one that completes relatively quickly so as to negate the effects of locking up the browser. We should probably be very careful about calling PushEventQueue on the main thread, where it would potentially disrupt the browser UI. Native events would still be dispatched as always, but without application level events, the UI isn't very useful.

Better Offline Mode

2006-03-14T15:13:49Z

Darin: /* Nice to have */

== Overview ==

Historically, Firefox and other Mozilla-based products have not handled disconnected operation, flaky network conditions, or network configuration changes well. Several extensions help to ease some of these problems, but it would be nice to have something built into Mozilla to better deal with these sorts of conditions.

=== Low-hanging fruit ===

* Do not discard cached content when we have a network connection failure. (<del>{{bug|189570}}</del> and <del>{{bug|278007}}</del>)
* Automatically reload PAC file when changing networks, or at least reload the PAC file when we encounter a network connection failure. ({{bug|243277}} and {{bug|125875}})

=== Nice to have ===

* Detect offline/online state changes from OS, and put browser in offline/online mode. ({{bug|76111}} and {{bug|312793}})

Better Offline Mode

2006-03-14T15:13:11Z

Darin: /* Low-hanging fruit */

XPCOM:nsIThreadManager

2006-03-08T01:44:05Z

Darin: /* darin: */

In a world without nested event queues, the concept of a thread and an event queue merge...

== Interfaces ==
=== nsIThreadManager ===
[scriptable, uuid(...)]
interface nsIThreadManager : nsISupports {
/**
* Create a new named thread (a global, user PRThread). If the name is
* non-empty, then the name of the thread must be unique. Specifying an
* empty name results in an anonymous thread that cannot be found later on
* using the getThread method.
*/
nsIThread newThread(in ACString name);
 
/**
* Find a named thread. If no thread exists by the given name, then null
* is returned.
*/
nsIThread getThread(in ACString name);
 
/**
* Get the nsIThread object (if any) corresponding to the given PRThread.
* This method returns null if there is no corresponding nsIThread.
*/
[noscript] nsIThread getThreadFromPRThread(in PRThread thread);
 
/**
* Get the main thread.
*/
readonly attribute nsIThread mainThread;
 
/**
* Get the current thread.
*/
readonly attribute nsIThread currentThread;
 
/**
* This attribute is true if the calling thread is the main thread of the
* application process.
*/
readonly attribute boolean isMainThread;
};

=== nsIEventTarget ===
[scriptable, uuid(...)]
interface nsIEventTarget : nsISupports {
/**
* Dispatch an event to the target. This function may be called from any
* thread. If flags specifies DISPATCH_SYNC, then the dispatch method
* will not return until the event has been processed. NOTE: Calling
* dispatch with DISPATCH_SYNC, may have the side-effect of running other
* events on the current thread while waiting for the given event to run
* to completion. This function is thread-safe and re-entrant.
*/
void dispatch(in nsIRunnable event, in unsigned long flags);
const unsigned long DISPATCH_NORMAL = 0;
const unsigned long DISPATCH_SYNC = 1;
 
/**
* Returns true if events dispatched to this target will run on the
* current thread (i.e., the thread calling this method).
*/
boolean isOnCurrentThread();
};
 
%{C++
// convenient aliases:
#define NS_DISPATCH_NORMAL nsIEventTarget::DISPATCH_NORMAL
#define NS_DISPATCH_SYNC nsIEventTarget::DISPATCH_SYNC
%}

=== nsIThread ===
[scriptable, uuid(...)]
interface nsIThread : nsIEventTarget {
/**
* Returns the name of the thread, which may be empty if this thread is
* anonymous.
*/
readonly attribute ACString name;
 
/**
* Returns the PRThread object corresponding to this nsIThread.
*/
[noscript] PRThread getPRThread();
 
/**
* Shutdown the thread. This method may not be executed from the thread
* itself. Instead, it is meant to be executed from another thread (usually
* the thread that created this thread). When this function returns, the
* thread will be shutdown, and it will no longer be possible to dispatch
* events to the thread.
*/
void shutdown();
 
/**
* Returns true if this thread has one or more pending events.
*/
boolean hasPendingEvents();
 
/**
* Process the next event. If there are no pending events, then this
* method will wait until an event is dispatched to this thread. This
* method is re-entrant but may only be called if this thread is the
* current thread.
*/
void processNextEvent();
};
=== nsIThreadInternal ===
[scriptable, uuid(...)]
interface nsIThreadInternal : nsIThread {
/**
* Get/set an observer for this thread (may be null). This attribute may
* be read from any thread, but must only be set on the thread corresponding
* to this thread object.
*/
attribute nsIThreadObserver observer;
 
/**
* This method causes any events currently enqueued on the thread to be
* suppressed until PopEventQueue is called. Additionally, any new events
* dispatched to the thread will only be processed if they are accepted by
* the given filter. If the filter is null, then new events are accepted.
* Calls to PushEventQueue may be nested and must each be paired with a call
* to PopEventQueue in order to restore the original state of the thread.
*/
void pushEventQueue(in nsIThreadEventFilter filter);
 
/**
* Revert a call to PushEventQueue. When an event queue is popped, any
* events remaining in the queue are appended to the elder queue.
*/
void popEventQueue();
};

=== nsIThreadObserver ===
[scriptable, uuid(...)]
interface nsIThreadObserver : nsISupports {
/**
* This method is called after an event has been dispatched to the thread.
* This method may be called from any thread.
*/
void onDispatchedEvent(in nsIThreadInternal thread);
 
/**
* This method is called (from nsIThread::ProcessNextEvent) before an event
* is processed. This method is only called on the target thread.
*
* @param thread
* The thread being asked to process another event.
* @param mayWait
* Indicates whether or not the method is allowed to block the calling
* thread. For example, this parameter is false during thread shutdown.
*/
void onProcessNextEvent(in nsIThreadInternal thread,
in boolean mayWait);
};

=== nsIThreadEventFilter ===
[scriptable, uuid(...)]
interface nsIThreadEventFilter : nsISupports {
/**
* This method is called to determine whether or not an event may be accepted
* by a "nested" event queue (see nsIThreadInternal::PushEventQueue).
*
* WARNING: This method must not make any calls on the thread object.
*/
[notxpcom] boolean AcceptEvent(in nsIRunnable event);
};

=== nsIThreadPool ===
[scriptable, uuid(...)]
interface nsIThreadPool : nsIEventTarget
{
/**
* Shutdown the thread pool. This method may not be executed from any
* thread in the thread pool. Instead, it is meant to be executed from
* another thread (usually the thread that created this thread pool).
* When this function returns, the thread pool and all of its threads will
* be shutdown, and it will no longer be possible to dispatch tasks to the
* thread pool.
*/
void shutdown()
 
/**
* Get/set the maximum number of threads allowed at one time in this pool.
*/
attribute unsigned long threadLimit;
 
/**
* Get/set the maximum number of idle threads kept alive.
*/
attribute unsigned long idleThreadLimit;
 
/**
* Get/set the amount of time in milliseconds before an idle thread is
* destroyed.
*/
attribute unsigned long idleThreadTimeout;
};

== C++ Utilities ==

=== Functions ===
nsThreadUtils.h defines the following helper functions:

/**
* Create a new thread.
*
* @param name
* The name of the thread (must be unique) or the empty string to
* create an anonymous thread.
* @param event
* The initial event to run on this thread. This can be null.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_NewThread(const nsACString &name, nsIRunnable *event,
nsIThread **result);
 
/**
* Get a reference to the current thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetCurrentThread(nsIThread **result);
 
/**
* Get a reference to the main thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetMainThread(nsIThread **result);
 
/**
* Get a reference to the thread with the given name.
*
* @param name
* The name of the requested thread. Must be non-empty.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetThread(const nsACString &name, nsIThread **result);
 
/**
* Test to see if the current thread is the main thread.
*
* @returns PR_TRUE if the current thread is the main thread, and PR_FALSE
* otherwise.
*/
PRBool NS_IsMainThread();
 
/**
* Dispatch the given event to the current thread.
*
* @param event
* The event to dispatch.
*/
NS_METHOD NS_DispatchToCurrentThread(nsIRunnable *event);
 
/**
* Dispatch the given event to the main thread.
*
* @param event
* The event to dispatch.
* @param dispatchFlags
* The flags to pass to the main thread's dispatch method.
*/
NS_METHOD NS_DispatchToMainThread(nsIRunnable *event,
PRUint32 dispatchFlags = NS_DISPATCH_NORMAL);
 
/**
* Process all pending events for the given thread before returning. This
* method simply calls ProcessNextEvent on the thread while HasPendingEvents
* continues to return true and the time spent in NS_ProcessPendingEvents
* does not exceed the given timeout value.
*
* @param thread
* The thread object for which to process pending events. If null,
* then events will be processed for the current thread.
* @param timeout
* The maximum number of milliseconds to spend processing pending
* events. Events are not pre-empted to honor this timeout. Rather,
* the timeout value is simply used to determine whether or not to
* process another event. Pass PR_INTERVAL_NO_TIMEOUT to specify no
* timeout.
*/
NS_METHOD NS_ProcessPendingEvents(nsIThread *thread = nsnull,
PRIntervalTime timeout = PR_INTERVAL_NO_TIMEOUT);

=== nsCOMPtr helpers ===
The following nsCOMPtr helpers are defined to simplify things further:

already_AddRefed<nsIThread> do_GetCurrentThread();
 
already_AddRefed<nsIThread> do_GetMainThread();
 
already_AddRefed<nsIThread> do_GetThread(const nsACString &name);

=== nsRunnable ===
The class <code>nsRunnable</code> is also defined to simplify the
implementation of new event types. For example, to define a new
event all you need to do is write code like this:

class MyEvent : public nsRunnable {
public:
MyEvent(... params ...);
 
NS_IMETHOD Run() {
// do stuff
return NS_OK;
}
};

Dispatching <code>MyEvent</code> is then as simple as:

nsCOMPtr<nsIThread> thread = do_GetCurrentThread();
NS_ENSURE_STATE(thread);
 
nsCOMPtr<nsIRunnable> event = new MyEvent();
NS_ENSURE_STATE(event);
 
thread->Dispatch(event, NS_DISPATCH_NORMAL);

== From JS ==

=== Event Dispatch ===
Threads and Thread Manager implement <code>nsIClassInfo</code>:

function MyEvent() {
}
MyEvent.prototype = {
QueryInterface: function(iid) {
if (iid.equals(Components.interfaces.nsIRunnable) ||
iid.equals(Components.interfaces.nsISupports))
return this;
throw Components.results.NS_ERROR_NO_INTERFACE;
},
run: function() {
// do stuff
}
};
 
function DispatchMyEvent() {
var target =
Components.classes["@mozilla.org/thread-manager;1"].
getService().currentThread;
 
target.dispatch(new MyEvent(), target.DISPATCH_NORMAL);
}

== Remarks ==

* Thread priority for native threads can be exposed via <code>nsISupportsPriority</code>.
* Thread names must be unique.
* The Necko I/O thread pool will be replaced by a generic thread pool implementation provided by XPCOM. The thread pool will implement <code>nsIEventTarget</code>, allowing events to be dispatched to any thread in the thread pool. We may even wish to define a <code>nsIThreadPool</code> interface and have it implement that as well. That interface would define methods to adjust the limits on the number of threads in the thread pool and so on.
* We will need an alternative for <code>nsIEventQueue::RevokeEvents</code>. There are several possibilities: (1) make consumers hold references to their nsIRunnable's so they can "disconnect" them manually, or (2) expose an enumeration/visitor API that allows consumers to walk the list of pending tasks and remove arbitrary tasks. I'm not sure what is best yet. The first option or something similar based on weak references is probably best as it avoids the costly O(n) <code>RevokeEvents</code> call.
* The following interfaces/classes would go away or be modified heavily: <code>nsIEventQueue</code>, <code>nsIEventQueueService</code>, <code>nsIEventTarget</code>, <code>nsIThread</code>, <code>PLEvent</code>.
* Issue: Perhaps we should support calling <code>nsIThread::Shutdown</code> from the thread itself. That would probably have to be implemented by posting an event to the main thread, and having that thread call shutdown. However, <code>Shutdown</code> also has the property that it does not return until the thread is gone. That obvious can't happen if <code>Shutdown</code> is called on the thread itself.

=== What about "native" event queues? ===
The main thread where UI events are processed and the socket transport thread will use the observer interface defined by <code>nsIThreadInternal</code>. The main thread will interact with the "native" event system during calls to <code>ProcessNextEvent</code> and <code>Dispatch</code>. Likewise, the socket transport thread will similarly need to poll sockets and perform I/O operations. By observing calls to <code>ProcessNextEvent</code>, observers can wait on a native event queue (or poll on a set of file descriptors) instead of waiting on the thread's internal event queue monitor. When they observe a call to <code>Dispatch</code>, they can use whatever mechanism is appropriate to unblock the thread that is waiting on the native event queue.

=== How do synchronous events work? ===

When <code>Dispatch(event, DISPATCH_SYNC)</code> is called on a <code>nsIEventTarget</code>, it first checks to see if the current thread is the same as the thread where the event would be run. If it is, then it just runs the event directly without queuing it up. However, if not, then it must queue the event to be run when the dispatch target next processes its events. To avoid returning to the caller immediately, the method gets the current thread and calls its <code>ProcessNextEvent</code> method in a loop until it receives acknowledgement that the queued event has been run.

== Development ==

Development is occuring on the THREADS_20060213_BRANCH. See also {{bug|326273}}.

== Comments ==

=== biesi: ===
* What happens if shutdown is called while an event is being processed? I assume that this event will be processed to its end, no further events are accepted, and then the thread is shut down. right?
** What happens to events that were already dispatched to this thread, but not run?
* Is it a good idea to allow other events to run on the current thread while in dispatch?
* Who is expected to call ProcessNextEvent?

==== darin: ====
* When asked to shutdown, a thread would finish dispatching all queued events, and refuse to accept any new events. Once all queued events run to completion, the thread would terminate. This is consistent with how event queues work today.
* If you are sync dispatching, then it is necessary to pump events on the calling thread or else you could end up in a dead-lock situation. For example, if thread A sync dispatches an event to thread B, which cannot complete its job without dispatching an event back to thread A, then the system will dead-lock unless thread A continues to dispatch pending events.
* <code>ProcessNextEvent</code> may be called by anybody that wishes to implement the concept of a "modal event loop." For example, XMLHttpRequest (in sync configuration) would sit in a loop calling <code>ProcessNextEvent</code> while waiting for the underlying HTTP transaction to complete. The key difference between <code>ProcessNextEvent</code> and <code>nsIEventQueue::ProcessPendingEvents</code> is that <code>ProcessNextEvent</code>, when called on the UI thread, will process UI events as well. And, it will also wait (block the thread of execution) if there are no UI events or pending <code>nsIRunnable</code> events.

=== dbaron: ===
So mrbkap was telling me at lunch about what's essentially the third bullet point of your comment to biesi above -- that you're making the concept of "modal event loop" even more powerful. This actually scares me a good bit, because these modal event loops happen within another event -- an event that may have state on the stack (e.g., |this| parameters) that could be destroyed by the processing of further events, or may have posted events that rely on the event completing. I really don't like the mix of programming models here that makes it very hard to write robust code, and I wish we could avoid this whole concept altogether rather than making it even more powerful, and thus more dangerous. We already have crashes where frame trees get destroyed while processing an event that are related to the Windows API's way of doing the same thing, though (for, e.g., a DestroyWindow call or whatever it's called).

==== darin: ====
Yup, I'm aware of that issue. In fact, the problem already exists today. There are some places in the code where WaitPLEvent + HandleEvent are called in a loop waiting for an event to process. That bypasses PL_ProcessPendingEvents recursion restriction. PopThreadEventQueue does not behave as you would expect either. It can cause ProcessPendingEvents to run for all but the PLEventQueue that is the subject of the current call to PL_ProcessPendingEvents on the stack. That defeats the purpose of the nested event queue in the first place.

The problem you describe with layout events also occurs for nsIStreamListener implementations. It would be really wierd if OnDataAvailable were called recursively, or if OnDataAvailable were called while the consumer is calling nsIChannel::AsyncOpen. These specific problems are dealt with in nsBaseChannel.cpp by temporarily suspending the channel during callbacks. That suppresses recusive stream listener calls.

Do you have a suggestion that would allow us to prevent this problem? Is there a better way to make XMLHttpRequest.send, document.load, window.alert, etc. appear modal to the calling Javascript?

For C++ consumers, we'd have to basically eliminate modal dialogs altogether to avoid this problem. Today, we have bugs where downloads stall and get disconnected all because the browser popped up a modal dialog and the dialog was not closed promptly enough by the user. That's just unacceptable. And, nsIPromptService is frozen.

I think the answer is to be careful about making callbacks across XPCOM boundaries where event queues may be pumped. Maybe the layout code needs to unwind the stack more before allowing such callbacks to happen so that it can be sure that event processing won't be the end of the world.

dbaron: Also, with the new push/popEventQueue API defined on nsIThreadInternal, it is possible to suppress event dispatch for a particular scope. That is needed to implement synchronous XPCOM proxy calls. I'm assuming that any proper use of synchronous XPCOM proxy calls will be one that completes relatively quickly so as to negate the effects of locking up the browser. We should probably be very careful about calling PushEventQueue on the main thread, where it would potentially disrupt the browser UI. Native events would still be dispatched as always, but without application level events, the UI isn't very useful.

XPCOM:nsIThreadManager

2006-03-08T01:30:49Z

Darin: /* darin: */

In a world without nested event queues, the concept of a thread and an event queue merge...

== Interfaces ==
=== nsIThreadManager ===
[scriptable, uuid(...)]
interface nsIThreadManager : nsISupports {
/**
* Create a new named thread (a global, user PRThread). If the name is
* non-empty, then the name of the thread must be unique. Specifying an
* empty name results in an anonymous thread that cannot be found later on
* using the getThread method.
*/
nsIThread newThread(in ACString name);
 
/**
* Find a named thread. If no thread exists by the given name, then null
* is returned.
*/
nsIThread getThread(in ACString name);
 
/**
* Get the nsIThread object (if any) corresponding to the given PRThread.
* This method returns null if there is no corresponding nsIThread.
*/
[noscript] nsIThread getThreadFromPRThread(in PRThread thread);
 
/**
* Get the main thread.
*/
readonly attribute nsIThread mainThread;
 
/**
* Get the current thread.
*/
readonly attribute nsIThread currentThread;
 
/**
* This attribute is true if the calling thread is the main thread of the
* application process.
*/
readonly attribute boolean isMainThread;
};

=== nsIEventTarget ===
[scriptable, uuid(...)]
interface nsIEventTarget : nsISupports {
/**
* Dispatch an event to the target. This function may be called from any
* thread. If flags specifies DISPATCH_SYNC, then the dispatch method
* will not return until the event has been processed. NOTE: Calling
* dispatch with DISPATCH_SYNC, may have the side-effect of running other
* events on the current thread while waiting for the given event to run
* to completion. This function is thread-safe and re-entrant.
*/
void dispatch(in nsIRunnable event, in unsigned long flags);
const unsigned long DISPATCH_NORMAL = 0;
const unsigned long DISPATCH_SYNC = 1;
 
/**
* Returns true if events dispatched to this target will run on the
* current thread (i.e., the thread calling this method).
*/
boolean isOnCurrentThread();
};
 
%{C++
// convenient aliases:
#define NS_DISPATCH_NORMAL nsIEventTarget::DISPATCH_NORMAL
#define NS_DISPATCH_SYNC nsIEventTarget::DISPATCH_SYNC
%}

=== nsIThread ===
[scriptable, uuid(...)]
interface nsIThread : nsIEventTarget {
/**
* Returns the name of the thread, which may be empty if this thread is
* anonymous.
*/
readonly attribute ACString name;
 
/**
* Returns the PRThread object corresponding to this nsIThread.
*/
[noscript] PRThread getPRThread();
 
/**
* Shutdown the thread. This method may not be executed from the thread
* itself. Instead, it is meant to be executed from another thread (usually
* the thread that created this thread). When this function returns, the
* thread will be shutdown, and it will no longer be possible to dispatch
* events to the thread.
*/
void shutdown();
 
/**
* Returns true if this thread has one or more pending events.
*/
boolean hasPendingEvents();
 
/**
* Process the next event. If there are no pending events, then this
* method will wait until an event is dispatched to this thread. This
* method is re-entrant but may only be called if this thread is the
* current thread.
*/
void processNextEvent();
};
=== nsIThreadInternal ===
[scriptable, uuid(...)]
interface nsIThreadInternal : nsIThread {
/**
* Get/set an observer for this thread (may be null). This attribute may
* be read from any thread, but must only be set on the thread corresponding
* to this thread object.
*/
attribute nsIThreadObserver observer;
 
/**
* This method causes any events currently enqueued on the thread to be
* suppressed until PopEventQueue is called. Additionally, any new events
* dispatched to the thread will only be processed if they are accepted by
* the given filter. If the filter is null, then new events are accepted.
* Calls to PushEventQueue may be nested and must each be paired with a call
* to PopEventQueue in order to restore the original state of the thread.
*/
void pushEventQueue(in nsIThreadEventFilter filter);
 
/**
* Revert a call to PushEventQueue. When an event queue is popped, any
* events remaining in the queue are appended to the elder queue.
*/
void popEventQueue();
};

=== nsIThreadObserver ===
[scriptable, uuid(...)]
interface nsIThreadObserver : nsISupports {
/**
* This method is called after an event has been dispatched to the thread.
* This method may be called from any thread.
*/
void onDispatchedEvent(in nsIThreadInternal thread);
 
/**
* This method is called (from nsIThread::ProcessNextEvent) before an event
* is processed. This method is only called on the target thread.
*
* @param thread
* The thread being asked to process another event.
* @param mayWait
* Indicates whether or not the method is allowed to block the calling
* thread. For example, this parameter is false during thread shutdown.
*/
void onProcessNextEvent(in nsIThreadInternal thread,
in boolean mayWait);
};

=== nsIThreadEventFilter ===
[scriptable, uuid(...)]
interface nsIThreadEventFilter : nsISupports {
/**
* This method is called to determine whether or not an event may be accepted
* by a "nested" event queue (see nsIThreadInternal::PushEventQueue).
*
* WARNING: This method must not make any calls on the thread object.
*/
[notxpcom] boolean AcceptEvent(in nsIRunnable event);
};

=== nsIThreadPool ===
[scriptable, uuid(...)]
interface nsIThreadPool : nsIEventTarget
{
/**
* Shutdown the thread pool. This method may not be executed from any
* thread in the thread pool. Instead, it is meant to be executed from
* another thread (usually the thread that created this thread pool).
* When this function returns, the thread pool and all of its threads will
* be shutdown, and it will no longer be possible to dispatch tasks to the
* thread pool.
*/
void shutdown()
 
/**
* Get/set the maximum number of threads allowed at one time in this pool.
*/
attribute unsigned long threadLimit;
 
/**
* Get/set the maximum number of idle threads kept alive.
*/
attribute unsigned long idleThreadLimit;
 
/**
* Get/set the amount of time in milliseconds before an idle thread is
* destroyed.
*/
attribute unsigned long idleThreadTimeout;
};

== C++ Utilities ==

=== Functions ===
nsThreadUtils.h defines the following helper functions:

/**
* Create a new thread.
*
* @param name
* The name of the thread (must be unique) or the empty string to
* create an anonymous thread.
* @param event
* The initial event to run on this thread. This can be null.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_NewThread(const nsACString &name, nsIRunnable *event,
nsIThread **result);
 
/**
* Get a reference to the current thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetCurrentThread(nsIThread **result);
 
/**
* Get a reference to the main thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetMainThread(nsIThread **result);
 
/**
* Get a reference to the thread with the given name.
*
* @param name
* The name of the requested thread. Must be non-empty.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetThread(const nsACString &name, nsIThread **result);
 
/**
* Test to see if the current thread is the main thread.
*
* @returns PR_TRUE if the current thread is the main thread, and PR_FALSE
* otherwise.
*/
PRBool NS_IsMainThread();
 
/**
* Dispatch the given event to the current thread.
*
* @param event
* The event to dispatch.
*/
NS_METHOD NS_DispatchToCurrentThread(nsIRunnable *event);
 
/**
* Dispatch the given event to the main thread.
*
* @param event
* The event to dispatch.
* @param dispatchFlags
* The flags to pass to the main thread's dispatch method.
*/
NS_METHOD NS_DispatchToMainThread(nsIRunnable *event,
PRUint32 dispatchFlags = NS_DISPATCH_NORMAL);
 
/**
* Process all pending events for the given thread before returning. This
* method simply calls ProcessNextEvent on the thread while HasPendingEvents
* continues to return true and the time spent in NS_ProcessPendingEvents
* does not exceed the given timeout value.
*
* @param thread
* The thread object for which to process pending events. If null,
* then events will be processed for the current thread.
* @param timeout
* The maximum number of milliseconds to spend processing pending
* events. Events are not pre-empted to honor this timeout. Rather,
* the timeout value is simply used to determine whether or not to
* process another event. Pass PR_INTERVAL_NO_TIMEOUT to specify no
* timeout.
*/
NS_METHOD NS_ProcessPendingEvents(nsIThread *thread = nsnull,
PRIntervalTime timeout = PR_INTERVAL_NO_TIMEOUT);

=== nsCOMPtr helpers ===
The following nsCOMPtr helpers are defined to simplify things further:

already_AddRefed<nsIThread> do_GetCurrentThread();
 
already_AddRefed<nsIThread> do_GetMainThread();
 
already_AddRefed<nsIThread> do_GetThread(const nsACString &name);

=== nsRunnable ===
The class <code>nsRunnable</code> is also defined to simplify the
implementation of new event types. For example, to define a new
event all you need to do is write code like this:

class MyEvent : public nsRunnable {
public:
MyEvent(... params ...);
 
NS_IMETHOD Run() {
// do stuff
return NS_OK;
}
};

Dispatching <code>MyEvent</code> is then as simple as:

nsCOMPtr<nsIThread> thread = do_GetCurrentThread();
NS_ENSURE_STATE(thread);
 
nsCOMPtr<nsIRunnable> event = new MyEvent();
NS_ENSURE_STATE(event);
 
thread->Dispatch(event, NS_DISPATCH_NORMAL);

== From JS ==

=== Event Dispatch ===
Threads and Thread Manager implement <code>nsIClassInfo</code>:

function MyEvent() {
}
MyEvent.prototype = {
QueryInterface: function(iid) {
if (iid.equals(Components.interfaces.nsIRunnable) ||
iid.equals(Components.interfaces.nsISupports))
return this;
throw Components.results.NS_ERROR_NO_INTERFACE;
},
run: function() {
// do stuff
}
};
 
function DispatchMyEvent() {
var target =
Components.classes["@mozilla.org/thread-manager;1"].
getService().currentThread;
 
target.dispatch(new MyEvent(), target.DISPATCH_NORMAL);
}

== Remarks ==

* Thread priority for native threads can be exposed via <code>nsISupportsPriority</code>.
* Thread names must be unique.
* The Necko I/O thread pool will be replaced by a generic thread pool implementation provided by XPCOM. The thread pool will implement <code>nsIEventTarget</code>, allowing events to be dispatched to any thread in the thread pool. We may even wish to define a <code>nsIThreadPool</code> interface and have it implement that as well. That interface would define methods to adjust the limits on the number of threads in the thread pool and so on.
* We will need an alternative for <code>nsIEventQueue::RevokeEvents</code>. There are several possibilities: (1) make consumers hold references to their nsIRunnable's so they can "disconnect" them manually, or (2) expose an enumeration/visitor API that allows consumers to walk the list of pending tasks and remove arbitrary tasks. I'm not sure what is best yet. The first option or something similar based on weak references is probably best as it avoids the costly O(n) <code>RevokeEvents</code> call.
* The following interfaces/classes would go away or be modified heavily: <code>nsIEventQueue</code>, <code>nsIEventQueueService</code>, <code>nsIEventTarget</code>, <code>nsIThread</code>, <code>PLEvent</code>.
* Issue: Perhaps we should support calling <code>nsIThread::Shutdown</code> from the thread itself. That would probably have to be implemented by posting an event to the main thread, and having that thread call shutdown. However, <code>Shutdown</code> also has the property that it does not return until the thread is gone. That obvious can't happen if <code>Shutdown</code> is called on the thread itself.

=== What about "native" event queues? ===
The main thread where UI events are processed and the socket transport thread will use the observer interface defined by <code>nsIThreadInternal</code>. The main thread will interact with the "native" event system during calls to <code>ProcessNextEvent</code> and <code>Dispatch</code>. Likewise, the socket transport thread will similarly need to poll sockets and perform I/O operations. By observing calls to <code>ProcessNextEvent</code>, observers can wait on a native event queue (or poll on a set of file descriptors) instead of waiting on the thread's internal event queue monitor. When they observe a call to <code>Dispatch</code>, they can use whatever mechanism is appropriate to unblock the thread that is waiting on the native event queue.

=== How do synchronous events work? ===

When <code>Dispatch(event, DISPATCH_SYNC)</code> is called on a <code>nsIEventTarget</code>, it first checks to see if the current thread is the same as the thread where the event would be run. If it is, then it just runs the event directly without queuing it up. However, if not, then it must queue the event to be run when the dispatch target next processes its events. To avoid returning to the caller immediately, the method gets the current thread and calls its <code>ProcessNextEvent</code> method in a loop until it receives acknowledgement that the queued event has been run.

== Development ==

Development is occuring on the THREADS_20060213_BRANCH. See also {{bug|326273}}.

== Comments ==

=== biesi: ===
* What happens if shutdown is called while an event is being processed? I assume that this event will be processed to its end, no further events are accepted, and then the thread is shut down. right?
** What happens to events that were already dispatched to this thread, but not run?
* Is it a good idea to allow other events to run on the current thread while in dispatch?
* Who is expected to call ProcessNextEvent?

==== darin: ====
* When asked to shutdown, a thread would finish dispatching all queued events, and refuse to accept any new events. Once all queued events run to completion, the thread would terminate. This is consistent with how event queues work today.
* If you are sync dispatching, then it is necessary to pump events on the calling thread or else you could end up in a dead-lock situation. For example, if thread A sync dispatches an event to thread B, which cannot complete its job without dispatching an event back to thread A, then the system will dead-lock unless thread A continues to dispatch pending events.
* <code>ProcessNextEvent</code> may be called by anybody that wishes to implement the concept of a "modal event loop." For example, XMLHttpRequest (in sync configuration) would sit in a loop calling <code>ProcessNextEvent</code> while waiting for the underlying HTTP transaction to complete. The key difference between <code>ProcessNextEvent</code> and <code>nsIEventQueue::ProcessPendingEvents</code> is that <code>ProcessNextEvent</code>, when called on the UI thread, will process UI events as well. And, it will also wait (block the thread of execution) if there are no UI events or pending <code>nsIRunnable</code> events.

=== dbaron: ===
So mrbkap was telling me at lunch about what's essentially the third bullet point of your comment to biesi above -- that you're making the concept of "modal event loop" even more powerful. This actually scares me a good bit, because these modal event loops happen within another event -- an event that may have state on the stack (e.g., |this| parameters) that could be destroyed by the processing of further events, or may have posted events that rely on the event completing. I really don't like the mix of programming models here that makes it very hard to write robust code, and I wish we could avoid this whole concept altogether rather than making it even more powerful, and thus more dangerous. We already have crashes where frame trees get destroyed while processing an event that are related to the Windows API's way of doing the same thing, though (for, e.g., a DestroyWindow call or whatever it's called).

==== darin: ====
Yup, I'm aware of that issue. In fact, the problem already exists today. There are some places in the code where WaitPLEvent + HandleEvent are called in a loop waiting for an event to process. That bypasses PL_ProcessPendingEvents recursion restriction. PopThreadEventQueue does not behave as you would expect either. It can cause ProcessPendingEvents to run for all but the PLEventQueue that is the subject of the current call to PL_ProcessPendingEvents on the stack. That defeats the purpose of the nested event queue in the first place.

The problem you describe with layout events also occurs for nsIStreamListener implementations. It would be really wierd if OnDataAvailable were called recursively, or if OnDataAvailable were called while the consumer is calling nsIChannel::AsyncOpen. These specific problems are dealt with in nsBaseChannel.cpp by temporarily suspending the channel during callbacks. That suppresses recusive stream listener calls.

Do you have a suggestion that would allow us to prevent this problem? Is there a better way to make XMLHttpRequest.send, document.load, window.alert, etc. appear modal to the calling Javascript?

For C++ consumers, we'd have to basically eliminate modal dialogs altogether to avoid this problem. Today, we have bugs where downloads stall and get disconnected all because the browser popped up a modal dialog and the dialog was not closed promptly enough by the user. That's just unacceptable. And, nsIPromptService is frozen.

I think the answer is to be careful about making callbacks across XPCOM boundaries where event queues may be pumped. Maybe the layout code needs to unwind the stack more before allowing such callbacks to happen so that it can be sure that event processing won't be the end of the world.

XPCOM:nsIThreadManager

2006-03-08T01:28:28Z

Darin: /* Comments */

In a world without nested event queues, the concept of a thread and an event queue merge...

== Interfaces ==
=== nsIThreadManager ===
[scriptable, uuid(...)]
interface nsIThreadManager : nsISupports {
/**
* Create a new named thread (a global, user PRThread). If the name is
* non-empty, then the name of the thread must be unique. Specifying an
* empty name results in an anonymous thread that cannot be found later on
* using the getThread method.
*/
nsIThread newThread(in ACString name);
 
/**
* Find a named thread. If no thread exists by the given name, then null
* is returned.
*/
nsIThread getThread(in ACString name);
 
/**
* Get the nsIThread object (if any) corresponding to the given PRThread.
* This method returns null if there is no corresponding nsIThread.
*/
[noscript] nsIThread getThreadFromPRThread(in PRThread thread);
 
/**
* Get the main thread.
*/
readonly attribute nsIThread mainThread;
 
/**
* Get the current thread.
*/
readonly attribute nsIThread currentThread;
 
/**
* This attribute is true if the calling thread is the main thread of the
* application process.
*/
readonly attribute boolean isMainThread;
};

=== nsIEventTarget ===
[scriptable, uuid(...)]
interface nsIEventTarget : nsISupports {
/**
* Dispatch an event to the target. This function may be called from any
* thread. If flags specifies DISPATCH_SYNC, then the dispatch method
* will not return until the event has been processed. NOTE: Calling
* dispatch with DISPATCH_SYNC, may have the side-effect of running other
* events on the current thread while waiting for the given event to run
* to completion. This function is thread-safe and re-entrant.
*/
void dispatch(in nsIRunnable event, in unsigned long flags);
const unsigned long DISPATCH_NORMAL = 0;
const unsigned long DISPATCH_SYNC = 1;
 
/**
* Returns true if events dispatched to this target will run on the
* current thread (i.e., the thread calling this method).
*/
boolean isOnCurrentThread();
};
 
%{C++
// convenient aliases:
#define NS_DISPATCH_NORMAL nsIEventTarget::DISPATCH_NORMAL
#define NS_DISPATCH_SYNC nsIEventTarget::DISPATCH_SYNC
%}

=== nsIThread ===
[scriptable, uuid(...)]
interface nsIThread : nsIEventTarget {
/**
* Returns the name of the thread, which may be empty if this thread is
* anonymous.
*/
readonly attribute ACString name;
 
/**
* Returns the PRThread object corresponding to this nsIThread.
*/
[noscript] PRThread getPRThread();
 
/**
* Shutdown the thread. This method may not be executed from the thread
* itself. Instead, it is meant to be executed from another thread (usually
* the thread that created this thread). When this function returns, the
* thread will be shutdown, and it will no longer be possible to dispatch
* events to the thread.
*/
void shutdown();
 
/**
* Returns true if this thread has one or more pending events.
*/
boolean hasPendingEvents();
 
/**
* Process the next event. If there are no pending events, then this
* method will wait until an event is dispatched to this thread. This
* method is re-entrant but may only be called if this thread is the
* current thread.
*/
void processNextEvent();
};
=== nsIThreadInternal ===
[scriptable, uuid(...)]
interface nsIThreadInternal : nsIThread {
/**
* Get/set an observer for this thread (may be null). This attribute may
* be read from any thread, but must only be set on the thread corresponding
* to this thread object.
*/
attribute nsIThreadObserver observer;
 
/**
* This method causes any events currently enqueued on the thread to be
* suppressed until PopEventQueue is called. Additionally, any new events
* dispatched to the thread will only be processed if they are accepted by
* the given filter. If the filter is null, then new events are accepted.
* Calls to PushEventQueue may be nested and must each be paired with a call
* to PopEventQueue in order to restore the original state of the thread.
*/
void pushEventQueue(in nsIThreadEventFilter filter);
 
/**
* Revert a call to PushEventQueue. When an event queue is popped, any
* events remaining in the queue are appended to the elder queue.
*/
void popEventQueue();
};

=== nsIThreadObserver ===
[scriptable, uuid(...)]
interface nsIThreadObserver : nsISupports {
/**
* This method is called after an event has been dispatched to the thread.
* This method may be called from any thread.
*/
void onDispatchedEvent(in nsIThreadInternal thread);
 
/**
* This method is called (from nsIThread::ProcessNextEvent) before an event
* is processed. This method is only called on the target thread.
*
* @param thread
* The thread being asked to process another event.
* @param mayWait
* Indicates whether or not the method is allowed to block the calling
* thread. For example, this parameter is false during thread shutdown.
*/
void onProcessNextEvent(in nsIThreadInternal thread,
in boolean mayWait);
};

=== nsIThreadEventFilter ===
[scriptable, uuid(...)]
interface nsIThreadEventFilter : nsISupports {
/**
* This method is called to determine whether or not an event may be accepted
* by a "nested" event queue (see nsIThreadInternal::PushEventQueue).
*
* WARNING: This method must not make any calls on the thread object.
*/
[notxpcom] boolean AcceptEvent(in nsIRunnable event);
};

=== nsIThreadPool ===
[scriptable, uuid(...)]
interface nsIThreadPool : nsIEventTarget
{
/**
* Shutdown the thread pool. This method may not be executed from any
* thread in the thread pool. Instead, it is meant to be executed from
* another thread (usually the thread that created this thread pool).
* When this function returns, the thread pool and all of its threads will
* be shutdown, and it will no longer be possible to dispatch tasks to the
* thread pool.
*/
void shutdown()
 
/**
* Get/set the maximum number of threads allowed at one time in this pool.
*/
attribute unsigned long threadLimit;
 
/**
* Get/set the maximum number of idle threads kept alive.
*/
attribute unsigned long idleThreadLimit;
 
/**
* Get/set the amount of time in milliseconds before an idle thread is
* destroyed.
*/
attribute unsigned long idleThreadTimeout;
};

== C++ Utilities ==

=== Functions ===
nsThreadUtils.h defines the following helper functions:

/**
* Create a new thread.
*
* @param name
* The name of the thread (must be unique) or the empty string to
* create an anonymous thread.
* @param event
* The initial event to run on this thread. This can be null.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_NewThread(const nsACString &name, nsIRunnable *event,
nsIThread **result);
 
/**
* Get a reference to the current thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetCurrentThread(nsIThread **result);
 
/**
* Get a reference to the main thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetMainThread(nsIThread **result);
 
/**
* Get a reference to the thread with the given name.
*
* @param name
* The name of the requested thread. Must be non-empty.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetThread(const nsACString &name, nsIThread **result);
 
/**
* Test to see if the current thread is the main thread.
*
* @returns PR_TRUE if the current thread is the main thread, and PR_FALSE
* otherwise.
*/
PRBool NS_IsMainThread();
 
/**
* Dispatch the given event to the current thread.
*
* @param event
* The event to dispatch.
*/
NS_METHOD NS_DispatchToCurrentThread(nsIRunnable *event);
 
/**
* Dispatch the given event to the main thread.
*
* @param event
* The event to dispatch.
* @param dispatchFlags
* The flags to pass to the main thread's dispatch method.
*/
NS_METHOD NS_DispatchToMainThread(nsIRunnable *event,
PRUint32 dispatchFlags = NS_DISPATCH_NORMAL);
 
/**
* Process all pending events for the given thread before returning. This
* method simply calls ProcessNextEvent on the thread while HasPendingEvents
* continues to return true and the time spent in NS_ProcessPendingEvents
* does not exceed the given timeout value.
*
* @param thread
* The thread object for which to process pending events. If null,
* then events will be processed for the current thread.
* @param timeout
* The maximum number of milliseconds to spend processing pending
* events. Events are not pre-empted to honor this timeout. Rather,
* the timeout value is simply used to determine whether or not to
* process another event. Pass PR_INTERVAL_NO_TIMEOUT to specify no
* timeout.
*/
NS_METHOD NS_ProcessPendingEvents(nsIThread *thread = nsnull,
PRIntervalTime timeout = PR_INTERVAL_NO_TIMEOUT);

=== nsCOMPtr helpers ===
The following nsCOMPtr helpers are defined to simplify things further:

already_AddRefed<nsIThread> do_GetCurrentThread();
 
already_AddRefed<nsIThread> do_GetMainThread();
 
already_AddRefed<nsIThread> do_GetThread(const nsACString &name);

=== nsRunnable ===
The class <code>nsRunnable</code> is also defined to simplify the
implementation of new event types. For example, to define a new
event all you need to do is write code like this:

class MyEvent : public nsRunnable {
public:
MyEvent(... params ...);
 
NS_IMETHOD Run() {
// do stuff
return NS_OK;
}
};

Dispatching <code>MyEvent</code> is then as simple as:

nsCOMPtr<nsIThread> thread = do_GetCurrentThread();
NS_ENSURE_STATE(thread);
 
nsCOMPtr<nsIRunnable> event = new MyEvent();
NS_ENSURE_STATE(event);
 
thread->Dispatch(event, NS_DISPATCH_NORMAL);

== From JS ==

=== Event Dispatch ===
Threads and Thread Manager implement <code>nsIClassInfo</code>:

function MyEvent() {
}
MyEvent.prototype = {
QueryInterface: function(iid) {
if (iid.equals(Components.interfaces.nsIRunnable) ||
iid.equals(Components.interfaces.nsISupports))
return this;
throw Components.results.NS_ERROR_NO_INTERFACE;
},
run: function() {
// do stuff
}
};
 
function DispatchMyEvent() {
var target =
Components.classes["@mozilla.org/thread-manager;1"].
getService().currentThread;
 
target.dispatch(new MyEvent(), target.DISPATCH_NORMAL);
}

== Remarks ==

* Thread priority for native threads can be exposed via <code>nsISupportsPriority</code>.
* Thread names must be unique.
* The Necko I/O thread pool will be replaced by a generic thread pool implementation provided by XPCOM. The thread pool will implement <code>nsIEventTarget</code>, allowing events to be dispatched to any thread in the thread pool. We may even wish to define a <code>nsIThreadPool</code> interface and have it implement that as well. That interface would define methods to adjust the limits on the number of threads in the thread pool and so on.
* We will need an alternative for <code>nsIEventQueue::RevokeEvents</code>. There are several possibilities: (1) make consumers hold references to their nsIRunnable's so they can "disconnect" them manually, or (2) expose an enumeration/visitor API that allows consumers to walk the list of pending tasks and remove arbitrary tasks. I'm not sure what is best yet. The first option or something similar based on weak references is probably best as it avoids the costly O(n) <code>RevokeEvents</code> call.
* The following interfaces/classes would go away or be modified heavily: <code>nsIEventQueue</code>, <code>nsIEventQueueService</code>, <code>nsIEventTarget</code>, <code>nsIThread</code>, <code>PLEvent</code>.
* Issue: Perhaps we should support calling <code>nsIThread::Shutdown</code> from the thread itself. That would probably have to be implemented by posting an event to the main thread, and having that thread call shutdown. However, <code>Shutdown</code> also has the property that it does not return until the thread is gone. That obvious can't happen if <code>Shutdown</code> is called on the thread itself.

=== What about "native" event queues? ===
The main thread where UI events are processed and the socket transport thread will use the observer interface defined by <code>nsIThreadInternal</code>. The main thread will interact with the "native" event system during calls to <code>ProcessNextEvent</code> and <code>Dispatch</code>. Likewise, the socket transport thread will similarly need to poll sockets and perform I/O operations. By observing calls to <code>ProcessNextEvent</code>, observers can wait on a native event queue (or poll on a set of file descriptors) instead of waiting on the thread's internal event queue monitor. When they observe a call to <code>Dispatch</code>, they can use whatever mechanism is appropriate to unblock the thread that is waiting on the native event queue.

=== How do synchronous events work? ===

When <code>Dispatch(event, DISPATCH_SYNC)</code> is called on a <code>nsIEventTarget</code>, it first checks to see if the current thread is the same as the thread where the event would be run. If it is, then it just runs the event directly without queuing it up. However, if not, then it must queue the event to be run when the dispatch target next processes its events. To avoid returning to the caller immediately, the method gets the current thread and calls its <code>ProcessNextEvent</code> method in a loop until it receives acknowledgement that the queued event has been run.

== Development ==

Development is occuring on the THREADS_20060213_BRANCH. See also {{bug|326273}}.

== Comments ==

=== biesi: ===
* What happens if shutdown is called while an event is being processed? I assume that this event will be processed to its end, no further events are accepted, and then the thread is shut down. right?
** What happens to events that were already dispatched to this thread, but not run?
* Is it a good idea to allow other events to run on the current thread while in dispatch?
* Who is expected to call ProcessNextEvent?

==== darin: ====
* When asked to shutdown, a thread would finish dispatching all queued events, and refuse to accept any new events. Once all queued events run to completion, the thread would terminate. This is consistent with how event queues work today.
* If you are sync dispatching, then it is necessary to pump events on the calling thread or else you could end up in a dead-lock situation. For example, if thread A sync dispatches an event to thread B, which cannot complete its job without dispatching an event back to thread A, then the system will dead-lock unless thread A continues to dispatch pending events.
* <code>ProcessNextEvent</code> may be called by anybody that wishes to implement the concept of a "modal event loop." For example, XMLHttpRequest (in sync configuration) would sit in a loop calling <code>ProcessNextEvent</code> while waiting for the underlying HTTP transaction to complete. The key difference between <code>ProcessNextEvent</code> and <code>nsIEventQueue::ProcessPendingEvents</code> is that <code>ProcessNextEvent</code>, when called on the UI thread, will process UI events as well. And, it will also wait (block the thread of execution) if there are no UI events or pending <code>nsIRunnable</code> events.

=== dbaron: ===
So mrbkap was telling me at lunch about what's essentially the third bullet point of your comment to biesi above -- that you're making the concept of "modal event loop" even more powerful. This actually scares me a good bit, because these modal event loops happen within another event -- an event that may have state on the stack (e.g., |this| parameters) that could be destroyed by the processing of further events, or may have posted events that rely on the event completing. I really don't like the mix of programming models here that makes it very hard to write robust code, and I wish we could avoid this whole concept altogether rather than making it even more powerful, and thus more dangerous. We already have crashes where frame trees get destroyed while processing an event that are related to the Windows API's way of doing the same thing, though (for, e.g., a DestroyWindow call or whatever it's called).

==== darin: ====
Yup, I'm aware of that issue. In fact, the problem already exists today. There are some places in the code where WaitPLEvent + HandleEvent are called in a loop waiting for an event to process. That bypasses PL_ProcessPendingEvents recursion restriction. PopThreadEventQueue does not behave as you would expect either. It can cause ProcessPendingEvents to run for all but the PLEventQueue that is the subject of the current call to PL_ProcessPendingEvents on the stack. That defeats the purpose of the nested event queue in the first place.

The problem you describe with layout events also occurs for nsIStreamListener implementations. It would be really wierd if OnDataAvailable were called recursively, or if OnDataAvailable were called while the consumer is calling nsIChannel::AsyncOpen. These specific problems are dealt with in nsBaseChannel.cpp by temporarily suspending the channel during callbacks. That suppresses recusive stream listener calls.

Do you have a suggestion that would allow us to prevent this problem? Is there a better way to make XMLHttpRequest.send, document.load, window.alert, etc. appear modal to the calling Javascript?

For C++ consumers, we'd have to basically eliminate modal dialogs altogether to avoid this problem. Today, we have bugs where downloads stale and get disconnected all because the browser popped up a modal dialog and the dialog was not closed promptly enough by the user. That's just unacceptable. And, nsIPromptService is frozen.

I think the answer is to be careful about making callbacks across XPCOM boundaries where event queues may be pumped. Maybe the layout code needs to unwind the stack more before allowing such callbacks to happen so that it can be sure that event processing won't be the end of the world.

Firefox2/StatusMeetings/2006-03-07

2006-03-07T18:35:36Z

Darin: /* Instrumentation / Exit Surveys */

[[Firefox2/StatusMeetings/2006-02-28|<< previous week]] | [[Firefox2/StatusMeetings|index]] | [[Firefox2/StatusMeetings/2006-03-14|next week>>]]

= In Attendance =
jhughes

= Agenda =
# Alpha 1 Status
# Firefox 2 Feature Status Roundtable
# Any other business

= Alpha 1 Status =
== Features ==
* '''Places infrastructure (performance, stability, toolbar drag & drop)'''
** ''now on trunk, ready for branch?''
** ''estimated time remaining for A1 readiness''

* '''Undo Close Tab'''
** '' pushed to A2?''

* '''Tab Overflow'''
** ''pushed to A2?''

* '''Extension Blacklisting'''
** ''patch reviewed and landed?''

* '''Extension Dependencies'''
** landed, no regressions

* '''Search Plugin Format Changeover (with sherlock import)'''
** ''patch reviewed?''

* '''Spell-As-You-Type (english only)'''
** we are clear to ship en-US with the product
** all other dictionaries must be downloaded explicitly as XPIs, mscott maintains a [http://www.mozilla.com/thunderbird/dictionaries.html list of these extensions]; these are the same dictionaries/problems that OpenOffice has. (cbeard: we can do better! ;-) perhaps we can license or buy dictionaries and release under a compatible license? rebron is going to dive into this. we should continue on the current path regardless.)
** ''enable this on branch by default? where do we package the dictionary file?''

* '''Instrumentation Infrastructure'''
** ''landed on trunk?''

* '''RSS parser'''
** SAX parser [https://bugzilla.mozilla.org/show_bug.cgi?id=315826 bug 315826] and dependencies finally got reviewed. Documented and almost ready to land. [https://bugzilla.mozilla.org/show_bug.cgi?id=325080 bug 325080] contains working RSS2/RSS1 parser w/ some Atom support. Need to cover more pathological cases and finish Atom. [-RS]

* '''RSS content detection (?)'''
** ''has this landed for branch?''

== Release Issues & Timing ==
* version number for A1 will be 2.0a1, trunk will be 3.0a1 (see [http://forums.mozillazine.org/viewtopic.php?t=388559 MZ forums post by mscott])
* still have to make the patch to rename trunk/branch
** trunk will become browser/3.0a1, 1.8_BRANCH will become Bon Echo/2.0a1
* plan is to promote this as developer only release, low-key announce
* ''any updates from QA/Software Update questions raised last week?''

= Status Updates =
== Places ==

* Brett: have seen no new data loss bugs since re-turning on. Startup and PLT are reasonable.
* ''any other updates?''

== Tabbed Browsing ==
* ''any other updates?''

== Extension Manager Enhancements ==
* ''any other updates?''

== Installer ==
* ''any other updates?''

== Search Engine UI ==
* ''any other updates?''

== Visual/UI Refresh ==
* started [http://groups.google.com/group/mozilla.dev.themes/browse_frm/thread/32c6e0c4fbc03fa5/1574dfb465b7fe8a#1574dfb465b7fe8a discussion in moz.dev.themes] about new theme for Firefox2; surprisingly low response!
* the Chrome changes UI thread in dev.apps.firefox seems to have wound down, will consolidate feedback and review later today and post back on that thread

== Platform Uplift ==
* ''anything new from last week?''

== Inline Spell Check ==
* we are clear to ship en-US with the product
** all other dictionaries must be downloaded explicitly as XPIs, mscott maintains a [http://www.mozilla.com/thunderbird/dictionaries.html list of these extensions]; these are the same dictionaries/problems that OpenOffice has.
** rebron will explore the possibilities, cbeard has suggested that we could look to either license or buy dictionaries for inclusion or release under compatible licenses.

== Instrumentation / Exit Surveys ==
* working on getting machines for server
* lots of progress on server side code
* working on finishing client side tasks
* exit survey web app {{bug|322884}} is still not live. need to poke morgamic.

== Session Saver ==

* Patch almost ready, testing now.
* No other news.

== Branding & Update Systems ==
* Still a todo item for Darin. We don't need to do anything special for FF 2.0a1, but it would be nice to get the nightly update channel working again. Preed says it is "midway on the list."

== RSS ==
* biesi's generic content sniffing patch landed on the MOZILLA_1_8_BRANCH.

== Offline mode / better use of cache ==
* Fixed a regression
* Roc has a patch to observe OS network state on linux. A similar patch exists in bugzilla for windows. Might be worth it to get some of this into FF2.
* Other work remaining: refresh PAC automatically

== Anti-Phishing ==
* [https://bugzilla.mozilla.org/show_bug.cgi?id=329292 bug 329292] filed to track the landing of Google's "Safe Browsing" code on branch
** to-dos include: opening up to other data providers, anonymizing data stream, creating generic API for other Mozilla products to use, renaming to "anti-phishing" (see [https://bugzilla.mozilla.org/show_bug.cgi?id=329292#c26 comment 26] and [https://bugzilla.mozilla.org/show_bug.cgi?id=329292#c28 comment 28])
* Sherman Dickman to take over this bit from cbeard, and investigate heuristic mechanisms as well as integration of this code from Google

== EULA ==
* nothing new here

== Performance ==
* ''any updates?''

= Other Business =
* ''any other business?''

Firefox2/StatusMeetings/2006-03-07

2006-03-07T18:32:09Z

Darin: /* RSS */

[[Firefox2/StatusMeetings/2006-02-28|<< previous week]] | [[Firefox2/StatusMeetings|index]] | [[Firefox2/StatusMeetings/2006-03-14|next week>>]]

= In Attendance =
jhughes

= Agenda =
# Alpha 1 Status
# Firefox 2 Feature Status Roundtable
# Any other business

= Alpha 1 Status =
== Features ==
* '''Places infrastructure (performance, stability, toolbar drag & drop)'''
** ''now on trunk, ready for branch?''
** ''estimated time remaining for A1 readiness''

* '''Undo Close Tab'''
** '' pushed to A2?''

* '''Tab Overflow'''
** ''pushed to A2?''

* '''Extension Blacklisting'''
** ''patch reviewed and landed?''

* '''Extension Dependencies'''
** landed, no regressions

* '''Search Plugin Format Changeover (with sherlock import)'''
** ''patch reviewed?''

* '''Spell-As-You-Type (english only)'''
** we are clear to ship en-US with the product
** all other dictionaries must be downloaded explicitly as XPIs, mscott maintains a [http://www.mozilla.com/thunderbird/dictionaries.html list of these extensions]; these are the same dictionaries/problems that OpenOffice has. (cbeard: we can do better! ;-) perhaps we can license or buy dictionaries and release under a compatible license? rebron is going to dive into this. we should continue on the current path regardless.)
** ''enable this on branch by default? where do we package the dictionary file?''

* '''Instrumentation Infrastructure'''
** ''landed on trunk?''

* '''RSS parser'''
** SAX parser [https://bugzilla.mozilla.org/show_bug.cgi?id=315826 bug 315826] and dependencies finally got reviewed. Documented and almost ready to land. [https://bugzilla.mozilla.org/show_bug.cgi?id=325080 bug 325080] contains working RSS2/RSS1 parser w/ some Atom support. Need to cover more pathological cases and finish Atom. [-RS]

* '''RSS content detection (?)'''
** ''has this landed for branch?''

== Release Issues & Timing ==
* version number for A1 will be 2.0a1, trunk will be 3.0a1 (see [http://forums.mozillazine.org/viewtopic.php?t=388559 MZ forums post by mscott])
* still have to make the patch to rename trunk/branch
** trunk will become browser/3.0a1, 1.8_BRANCH will become Bon Echo/2.0a1
* plan is to promote this as developer only release, low-key announce
* ''any updates from QA/Software Update questions raised last week?''

= Status Updates =
== Places ==

* Brett: have seen no new data loss bugs since re-turning on. Startup and PLT are reasonable.
* ''any other updates?''

== Tabbed Browsing ==
* ''any other updates?''

== Extension Manager Enhancements ==
* ''any other updates?''

== Installer ==
* ''any other updates?''

== Search Engine UI ==
* ''any other updates?''

== Visual/UI Refresh ==
* started [http://groups.google.com/group/mozilla.dev.themes/browse_frm/thread/32c6e0c4fbc03fa5/1574dfb465b7fe8a#1574dfb465b7fe8a discussion in moz.dev.themes] about new theme for Firefox2; surprisingly low response!
* the Chrome changes UI thread in dev.apps.firefox seems to have wound down, will consolidate feedback and review later today and post back on that thread

== Platform Uplift ==
* ''anything new from last week?''

== Inline Spell Check ==
* we are clear to ship en-US with the product
** all other dictionaries must be downloaded explicitly as XPIs, mscott maintains a [http://www.mozilla.com/thunderbird/dictionaries.html list of these extensions]; these are the same dictionaries/problems that OpenOffice has.
** need to come up with a strategy for handling this issue

== Instrumentation / Exit Surveys ==
* working on getting machines for server
* lots of progress on server side code
* working on finishing client side tasks

== Session Saver ==

* Patch almost ready, testing now.
* No other news.

== Branding & Update Systems ==
* Still a todo item for Darin. We don't need to do anything special for FF 2.0a1, but it would be nice to get the nightly update channel working again. Preed says it is "midway on the list."

== RSS ==
* biesi's generic content sniffing patch landed on the MOZILLA_1_8_BRANCH.

== Offline mode / better use of cache ==
* Fixed a regression
* Roc has a patch to observe OS network state on linux. A similar patch exists in bugzilla for windows. Might be worth it to get some of this into FF2.
* Other work remaining: refresh PAC automatically

== Anti-Phishing ==
* [https://bugzilla.mozilla.org/show_bug.cgi?id=329292 bug 329292] filed to track the landing of Google's "Safe Browsing" code on branch
** to-dos include: opening up to other data providers, anonymizing data stream, creating generic API for other Mozilla products to use, renaming to "anti-phishing" (see [https://bugzilla.mozilla.org/show_bug.cgi?id=329292#c26 comment 26] and [https://bugzilla.mozilla.org/show_bug.cgi?id=329292#c28 comment 28])
* Sherman Dickman to take over this bit from cbeard, and investigate heuristic mechanisms as well as integration of this code from Google

== EULA ==
* nothing new here

== Performance ==
* ''any updates?''

= Other Business =
* ''any other business?''

Firefox2/StatusMeetings/2006-03-07

2006-03-07T18:30:37Z

Darin: /* Branding & Update Systems */

[[Firefox2/StatusMeetings/2006-02-28|<< previous week]] | [[Firefox2/StatusMeetings|index]] | [[Firefox2/StatusMeetings/2006-03-14|next week>>]]

= In Attendance =
jhughes

= Agenda =
# Alpha 1 Status
# Firefox 2 Feature Status Roundtable
# Any other business

= Alpha 1 Status =
== Features ==
* '''Places infrastructure (performance, stability, toolbar drag & drop)'''
** ''now on trunk, ready for branch?''
** ''estimated time remaining for A1 readiness''

* '''Undo Close Tab'''
** '' pushed to A2?''

* '''Tab Overflow'''
** ''pushed to A2?''

* '''Extension Blacklisting'''
** ''patch reviewed and landed?''

* '''Extension Dependencies'''
** landed, no regressions

* '''Search Plugin Format Changeover (with sherlock import)'''
** ''patch reviewed?''

* '''Spell-As-You-Type (english only)'''
** we are clear to ship en-US with the product
** all other dictionaries must be downloaded explicitly as XPIs, mscott maintains a [http://www.mozilla.com/thunderbird/dictionaries.html list of these extensions]; these are the same dictionaries/problems that OpenOffice has.
** ''enable this on branch by default? where do we package the dictionary file?''
** (cbeard: we can do better, perhaps we can license or buy dictionaries and release under a compatible license? rebron is going to dive into this. we should continue on the current path regardless.)

* '''Instrumentation Infrastructure'''
** ''landed on trunk?''

* '''RSS parser'''
** SAX parser [https://bugzilla.mozilla.org/show_bug.cgi?id=315826 bug 315826] and dependencies finally got reviewed. Documented and almost ready to land. [https://bugzilla.mozilla.org/show_bug.cgi?id=325080 bug 325080] contains working RSS2/RSS1 parser w/ some Atom support. Need to cover more pathological cases and finish Atom. [-RS]

* '''RSS content detection (?)'''
** ''has this landed for branch?''

== Release Issues & Timing ==
* version number for A1 will be 2.0a1, trunk will be 3.0a1 (see [http://forums.mozillazine.org/viewtopic.php?t=388559 MZ forums post by mscott])
* still have to make the patch to rename trunk/branch
** trunk will become browser/3.0a1, 1.8_BRANCH will become Bon Echo/2.0a1
* plan is to promote this as developer only release, low-key announce
* ''any updates from QA/Software Update questions raised last week?''

= Status Updates =
== Places ==

* Brett: have seen no new data loss bugs since re-turning on. Startup and PLT are reasonable.
* ''any other updates?''

== Tabbed Browsing ==
* ''any other updates?''

== Extension Manager Enhancements ==
* ''any other updates?''

== Installer ==
* ''any other updates?''

== Search Engine UI ==
* ''any other updates?''

== Visual/UI Refresh ==
* started [http://groups.google.com/group/mozilla.dev.themes/browse_frm/thread/32c6e0c4fbc03fa5/1574dfb465b7fe8a#1574dfb465b7fe8a discussion in moz.dev.themes] about new theme for Firefox2; surprisingly low response!
* the Chrome changes UI thread in dev.apps.firefox seems to have wound down, will consolidate feedback and review later today and post back on that thread

== Platform Uplift ==
* ''anything new from last week?''

== Inline Spell Check ==
* we are clear to ship en-US with the product
** all other dictionaries must be downloaded explicitly as XPIs, mscott maintains a [http://www.mozilla.com/thunderbird/dictionaries.html list of these extensions]; these are the same dictionaries/problems that OpenOffice has.
** need to come up with a strategy for handling this issue

== Instrumentation / Exit Surveys ==
* working on getting machines for server
* lots of progress on server side code
* working on finishing client side tasks

== Session Saver ==

* Patch almost ready, testing now.
* No other news.

== Branding & Update Systems ==
* Still a todo item for Darin. We don't need to do anything special for FF 2.0a1, but it would be nice to get the nightly update channel working again. Preed says it is "midway on the list."

== RSS ==
* ''any other updates?''

== Offline mode / better use of cache ==
* Fixed a regression
* Roc has a patch to observe OS network state on linux. A similar patch exists in bugzilla for windows. Might be worth it to get some of this into FF2.
* Other work remaining: refresh PAC automatically

== Anti-Phishing ==
* [https://bugzilla.mozilla.org/show_bug.cgi?id=329292 bug 329292] filed to track the landing of Google's "Safe Browsing" code on branch
** to-dos include: opening up to other data providers, anonymizing data stream, creating generic API for other Mozilla products to use, renaming to "anti-phishing" (see [https://bugzilla.mozilla.org/show_bug.cgi?id=329292#c26 comment 26] and [https://bugzilla.mozilla.org/show_bug.cgi?id=329292#c28 comment 28])
* Sherman Dickman to take over this bit from cbeard, and investigate heuristic mechanisms as well as integration of this code from Google

== EULA ==
* nothing new here

== Performance ==
* ''any updates?''

= Other Business =
* ''any other business?''

Firefox2/StatusMeetings/2006-03-07

2006-03-07T18:27:14Z

Darin: /* Offline mode / better use of cache */

[[Firefox2/StatusMeetings/2006-02-28|<< previous week]] | [[Firefox2/StatusMeetings|index]] | [[Firefox2/StatusMeetings/2006-03-14|next week>>]]

= In Attendance =
jhughes

= Agenda =
# Alpha 1 Status
# Firefox 2 Feature Status Roundtable
# Any other business

= Alpha 1 Status =
== Features ==
* '''Places infrastructure (performance, stability, toolbar drag & drop)'''
** ''now on trunk, ready for branch?''
** ''estimated time remaining for A1 readiness''

* '''Undo Close Tab'''
** '' pushed to A2?''

* '''Tab Overflow'''
** ''pushed to A2?''

* '''Extension Blacklisting'''
** ''patch reviewed and landed?''

* '''Extension Dependencies'''
** landed, no regressions

* '''Search Plugin Format Changeover (with sherlock import)'''
** ''patch reviewed?''

* '''Spell-As-You-Type (english only)'''
** we are clear to ship en-US with the product
** all other dictionaries must be downloaded explicitly as XPIs, mscott maintains a [http://www.mozilla.com/thunderbird/dictionaries.html list of these extensions]; these are the same dictionaries/problems that OpenOffice has.
** ''enable this on branch by default? where do we package the dictionary file?''
** (cbeard: we can do better, perhaps we can license or buy dictionaries and release under a compatible license? rebron is going to dive into this. we should continue on the current path regardless.)

* '''Instrumentation Infrastructure'''
** ''landed on trunk?''

* '''RSS parser'''
** SAX parser [https://bugzilla.mozilla.org/show_bug.cgi?id=315826 bug 315826] and dependencies finally got reviewed. Documented and almost ready to land. [https://bugzilla.mozilla.org/show_bug.cgi?id=325080 bug 325080] contains working RSS2/RSS1 parser w/ some Atom support. Need to cover more pathological cases and finish Atom. [-RS]

* '''RSS content detection (?)'''
** ''has this landed for branch?''

== Release Issues & Timing ==
* version number for A1 will be 2.0a1, trunk will be 3.0a1 (see [http://forums.mozillazine.org/viewtopic.php?t=388559 MZ forums post by mscott])
* still have to make the patch to rename trunk/branch
** trunk will become browser/3.0a1, 1.8_BRANCH will become Bon Echo/2.0a1
* plan is to promote this as developer only release, low-key announce
* ''any updates from QA/Software Update questions raised last week?''

= Status Updates =
== Places ==

* Brett: have seen no new data loss bugs since re-turning on. Startup and PLT are reasonable.
* ''any other updates?''

== Tabbed Browsing ==
* ''any other updates?''

== Extension Manager Enhancements ==
* ''any other updates?''

== Installer ==
* ''any other updates?''

== Search Engine UI ==
* ''any other updates?''

== Visual/UI Refresh ==
* started [http://groups.google.com/group/mozilla.dev.themes/browse_frm/thread/32c6e0c4fbc03fa5/1574dfb465b7fe8a#1574dfb465b7fe8a discussion in moz.dev.themes] about new theme for Firefox2; surprisingly low response!
* the Chrome changes UI thread in dev.apps.firefox seems to have wound down, will consolidate feedback and review later today and post back on that thread

== Platform Uplift ==
* ''anything new from last week?''

== Inline Spell Check ==
* we are clear to ship en-US with the product
** all other dictionaries must be downloaded explicitly as XPIs, mscott maintains a [http://www.mozilla.com/thunderbird/dictionaries.html list of these extensions]; these are the same dictionaries/problems that OpenOffice has.
** need to come up with a strategy for handling this issue

== Instrumentation / Exit Surveys ==
* working on getting machines for server
* lots of progress on server side code
* working on finishing client side tasks

== Session Saver ==

* Patch almost ready, testing now.
* No other news.

== Branding & Update Systems ==
* ''any other updates?''

== RSS ==
* ''any other updates?''

== Offline mode / better use of cache ==
* Fixed a regression
* Roc has a patch to observe OS network state on linux. A similar patch exists in bugzilla for windows. Might be worth it to get some of this into FF2.
* Other work remaining: refresh PAC automatically

== Anti-Phishing ==
* [https://bugzilla.mozilla.org/show_bug.cgi?id=329292 bug 329292] filed to track the landing of Google's "Safe Browsing" code on branch
** to-dos include: opening up to other data providers, anonymizing data stream, creating generic API for other Mozilla products to use, renaming to "anti-phishing" (see [https://bugzilla.mozilla.org/show_bug.cgi?id=329292#c26 comment 26] and [https://bugzilla.mozilla.org/show_bug.cgi?id=329292#c28 comment 28])
* Sherman Dickman to take over this bit from cbeard, and investigate heuristic mechanisms as well as integration of this code from Google

== EULA ==
* nothing new here

== Performance ==
* ''any updates?''

= Other Business =
* ''any other business?''

Firefox2/StatusMeetings/2006-03-07

2006-03-07T18:25:30Z

Darin: /* Instrumentation / Exit Surveys */

[[Firefox2/StatusMeetings/2006-02-28|<< previous week]] | [[Firefox2/StatusMeetings|index]] | [[Firefox2/StatusMeetings/2006-03-14|next week>>]]

= In Attendance =
jhughes

= Agenda =
# Alpha 1 Status
# Firefox 2 Feature Status Roundtable
# Any other business

= Alpha 1 Status =
== Features ==
* '''Places infrastructure (performance, stability, toolbar drag & drop)'''
** ''now on trunk, ready for branch?''
** ''estimated time remaining for A1 readiness''

* '''Undo Close Tab'''
** '' pushed to A2?''

* '''Tab Overflow'''
** ''pushed to A2?''

* '''Extension Blacklisting'''
** ''patch reviewed and landed?''

* '''Extension Dependencies'''
** landed, no regressions

* '''Search Plugin Format Changeover (with sherlock import)'''
** ''patch reviewed?''

* '''Spell-As-You-Type (english only)'''
** we are clear to ship en-US with the product
** all other dictionaries must be downloaded explicitly as XPIs, mscott maintains a [http://www.mozilla.com/thunderbird/dictionaries.html list of these extensions]; these are the same dictionaries/problems that OpenOffice has.
** ''enable this on branch by default? where do we package the dictionary file?''
** (cbeard: we can do better, perhaps we can license or buy dictionaries and release under a compatible license? rebron is going to dive into this. we should continue on the current path regardless.)

* '''Instrumentation Infrastructure'''
** ''landed on trunk?''

* '''RSS parser'''
** SAX parser [https://bugzilla.mozilla.org/show_bug.cgi?id=315826 bug 315826] and dependencies finally got reviewed. Documented and almost ready to land. [https://bugzilla.mozilla.org/show_bug.cgi?id=325080 bug 325080] contains working RSS2/RSS1 parser w/ some Atom support. Need to cover more pathological cases and finish Atom. [-RS]

* '''RSS content detection (?)'''
** ''has this landed for branch?''

== Release Issues & Timing ==
* version number for A1 will be 2.0a1, trunk will be 3.0a1 (see [http://forums.mozillazine.org/viewtopic.php?t=388559 MZ forums post by mscott])
* still have to make the patch to rename trunk/branch
** trunk will become browser/3.0a1, 1.8_BRANCH will become Bon Echo/2.0a1
* plan is to promote this as developer only release, low-key announce
* ''any updates from QA/Software Update questions raised last week?''

= Status Updates =
== Places ==

* Brett: have seen no new data loss bugs since re-turning on. Startup and PLT are reasonable.
* ''any other updates?''

== Tabbed Browsing ==
* ''any other updates?''

== Extension Manager Enhancements ==
* ''any other updates?''

== Installer ==
* ''any other updates?''

== Search Engine UI ==
* ''any other updates?''

== Visual/UI Refresh ==
* started [http://groups.google.com/group/mozilla.dev.themes/browse_frm/thread/32c6e0c4fbc03fa5/1574dfb465b7fe8a#1574dfb465b7fe8a discussion in moz.dev.themes] about new theme for Firefox2; surprisingly low response!
* the Chrome changes UI thread in dev.apps.firefox seems to have wound down, will consolidate feedback and review later today and post back on that thread

== Platform Uplift ==
* ''anything new from last week?''

== Inline Spell Check ==
* we are clear to ship en-US with the product
** all other dictionaries must be downloaded explicitly as XPIs, mscott maintains a [http://www.mozilla.com/thunderbird/dictionaries.html list of these extensions]; these are the same dictionaries/problems that OpenOffice has.
** need to come up with a strategy for handling this issue

== Instrumentation / Exit Surveys ==
* working on getting machines for server
* lots of progress on server side code
* working on finishing client side tasks

== Session Saver ==

* Patch almost ready, testing now.
* No other news.

== Branding & Update Systems ==
* ''any other updates?''

== RSS ==
* ''any other updates?''

== Offline mode / better use of cache ==
* ''any other updates?''

== Anti-Phishing ==
* [https://bugzilla.mozilla.org/show_bug.cgi?id=329292 bug 329292] filed to track the landing of Google's "Safe Browsing" code on branch
** to-dos include: opening up to other data providers, anonymizing data stream, creating generic API for other Mozilla products to use, renaming to "anti-phishing" (see [https://bugzilla.mozilla.org/show_bug.cgi?id=329292#c26 comment 26] and [https://bugzilla.mozilla.org/show_bug.cgi?id=329292#c28 comment 28])
* Sherman Dickman to take over this bit from cbeard, and investigate heuristic mechanisms as well as integration of this code from Google

== EULA ==
* nothing new here

== Performance ==
* ''any updates?''

= Other Business =
* ''any other business?''

XPCOM:nsIThreadManager

2006-03-04T00:49:55Z

Darin: /* Remarks */

In a world without nested event queues, the concept of a thread and an event queue merge...

== Interfaces ==
=== nsIThreadManager ===
[scriptable, uuid(...)]
interface nsIThreadManager : nsISupports {
/**
* Create a new named thread (a global, user PRThread). If the name is
* non-empty, then the name of the thread must be unique. Specifying an
* empty name results in an anonymous thread that cannot be found later on
* using the getThread method.
*/
nsIThread newThread(in ACString name);
 
/**
* Find a named thread. If no thread exists by the given name, then null
* is returned.
*/
nsIThread getThread(in ACString name);
 
/**
* Get the nsIThread object (if any) corresponding to the given PRThread.
* This method returns null if there is no corresponding nsIThread.
*/
[noscript] nsIThread getThreadFromPRThread(in PRThread thread);
 
/**
* Get the main thread.
*/
readonly attribute nsIThread mainThread;
 
/**
* Get the current thread.
*/
readonly attribute nsIThread currentThread;
 
/**
* This attribute is true if the calling thread is the main thread of the
* application process.
*/
readonly attribute boolean isMainThread;
};

=== nsIEventTarget ===
[scriptable, uuid(...)]
interface nsIEventTarget : nsISupports {
/**
* Dispatch an event to the target. This function may be called from any
* thread. If flags specifies DISPATCH_SYNC, then the dispatch method
* will not return until the event has been processed. NOTE: Calling
* dispatch with DISPATCH_SYNC, may have the side-effect of running other
* events on the current thread while waiting for the given event to run
* to completion. This function is thread-safe and re-entrant.
*/
void dispatch(in nsIRunnable event, in unsigned long flags);
const unsigned long DISPATCH_NORMAL = 0;
const unsigned long DISPATCH_SYNC = 1;
 
/**
* Returns true if events dispatched to this target will run on the
* current thread (i.e., the thread calling this method).
*/
boolean isOnCurrentThread();
};
 
%{C++
// convenient aliases:
#define NS_DISPATCH_NORMAL nsIEventTarget::DISPATCH_NORMAL
#define NS_DISPATCH_SYNC nsIEventTarget::DISPATCH_SYNC
%}

=== nsIThread ===
[scriptable, uuid(...)]
interface nsIThread : nsIEventTarget {
/**
* Returns the name of the thread, which may be empty if this thread is
* anonymous.
*/
readonly attribute ACString name;
 
/**
* Returns the PRThread object corresponding to this nsIThread.
*/
[noscript] PRThread getPRThread();
 
/**
* Shutdown the thread. This method may not be executed from the thread
* itself. Instead, it is meant to be executed from another thread (usually
* the thread that created this thread). When this function returns, the
* thread will be shutdown, and it will no longer be possible to dispatch
* events to the thread.
*/
void shutdown();
 
/**
* Returns true if this thread has one or more pending events.
*/
boolean hasPendingEvents();
 
/**
* Process the next event. If there are no pending events, then this
* method will wait until an event is dispatched to this thread. This
* method is re-entrant but may only be called if this thread is the
* current thread.
*/
void processNextEvent();
};
=== nsIThreadInternal ===
[scriptable, uuid(...)]
interface nsIThreadInternal : nsIThread {
/**
* Get/set an observer for this thread (may be null). This attribute may
* be read from any thread, but must only be set on the thread corresponding
* to this thread object.
*/
attribute nsIThreadObserver observer;
 
/**
* This method causes any events currently enqueued on the thread to be
* suppressed until PopEventQueue is called. Additionally, any new events
* dispatched to the thread will only be processed if they are accepted by
* the given filter. If the filter is null, then new events are accepted.
* Calls to PushEventQueue may be nested and must each be paired with a call
* to PopEventQueue in order to restore the original state of the thread.
*/
void pushEventQueue(in nsIThreadEventFilter filter);
 
/**
* Revert a call to PushEventQueue. When an event queue is popped, any
* events remaining in the queue are appended to the elder queue.
*/
void popEventQueue();
};

=== nsIThreadObserver ===
[scriptable, uuid(...)]
interface nsIThreadObserver : nsISupports {
/**
* This method is called after an event has been dispatched to the thread.
* This method may be called from any thread.
*/
void onDispatchedEvent(in nsIThreadInternal thread);
 
/**
* This method is called (from nsIThread::ProcessNextEvent) before an event
* is processed. This method is only called on the target thread.
*
* @param thread
* The thread being asked to process another event.
* @param mayWait
* Indicates whether or not the method is allowed to block the calling
* thread. For example, this parameter is false during thread shutdown.
*/
void onProcessNextEvent(in nsIThreadInternal thread,
in boolean mayWait);
};

=== nsIThreadEventFilter ===
[scriptable, uuid(...)]
interface nsIThreadEventFilter : nsISupports {
/**
* This method is called to determine whether or not an event may be accepted
* by a "nested" event queue (see nsIThreadInternal::PushEventQueue).
*
* WARNING: This method must not make any calls on the thread object.
*/
[notxpcom] boolean AcceptEvent(in nsIRunnable event);
};

=== nsIThreadPool ===
[scriptable, uuid(...)]
interface nsIThreadPool : nsIEventTarget
{
/**
* Shutdown the thread pool. This method may not be executed from any
* thread in the thread pool. Instead, it is meant to be executed from
* another thread (usually the thread that created this thread pool).
* When this function returns, the thread pool and all of its threads will
* be shutdown, and it will no longer be possible to dispatch tasks to the
* thread pool.
*/
void shutdown()
 
/**
* Get/set the maximum number of threads allowed at one time in this pool.
*/
attribute unsigned long threadLimit;
 
/**
* Get/set the maximum number of idle threads kept alive.
*/
attribute unsigned long idleThreadLimit;
 
/**
* Get/set the amount of time in milliseconds before an idle thread is
* destroyed.
*/
attribute unsigned long idleThreadTimeout;
};

== C++ Utilities ==

=== Functions ===
nsThreadUtils.h defines the following helper functions:

/**
* Create a new thread.
*
* @param name
* The name of the thread (must be unique) or the empty string to
* create an anonymous thread.
* @param event
* The initial event to run on this thread. This can be null.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_NewThread(const nsACString &name, nsIRunnable *event,
nsIThread **result);
 
/**
* Get a reference to the current thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetCurrentThread(nsIThread **result);
 
/**
* Get a reference to the main thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetMainThread(nsIThread **result);
 
/**
* Get a reference to the thread with the given name.
*
* @param name
* The name of the requested thread. Must be non-empty.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetThread(const nsACString &name, nsIThread **result);
 
/**
* Test to see if the current thread is the main thread.
*
* @returns PR_TRUE if the current thread is the main thread, and PR_FALSE
* otherwise.
*/
PRBool NS_IsMainThread();
 
/**
* Dispatch the given event to the current thread.
*
* @param event
* The event to dispatch.
*/
NS_METHOD NS_DispatchToCurrentThread(nsIRunnable *event);
 
/**
* Dispatch the given event to the main thread.
*
* @param event
* The event to dispatch.
* @param dispatchFlags
* The flags to pass to the main thread's dispatch method.
*/
NS_METHOD NS_DispatchToMainThread(nsIRunnable *event,
PRUint32 dispatchFlags = NS_DISPATCH_NORMAL);
 
/**
* Process all pending events for the given thread before returning. This
* method simply calls ProcessNextEvent on the thread while HasPendingEvents
* continues to return true and the time spent in NS_ProcessPendingEvents
* does not exceed the given timeout value.
*
* @param thread
* The thread object for which to process pending events. If null,
* then events will be processed for the current thread.
* @param timeout
* The maximum number of milliseconds to spend processing pending
* events. Events are not pre-empted to honor this timeout. Rather,
* the timeout value is simply used to determine whether or not to
* process another event. Pass PR_INTERVAL_NO_TIMEOUT to specify no
* timeout.
*/
NS_METHOD NS_ProcessPendingEvents(nsIThread *thread = nsnull,
PRIntervalTime timeout = PR_INTERVAL_NO_TIMEOUT);

=== nsCOMPtr helpers ===
The following nsCOMPtr helpers are defined to simplify things further:

already_AddRefed<nsIThread> do_GetCurrentThread();
 
already_AddRefed<nsIThread> do_GetMainThread();
 
already_AddRefed<nsIThread> do_GetThread(const nsACString &name);

=== nsRunnable ===
The class <code>nsRunnable</code> is also defined to simplify the
implementation of new event types. For example, to define a new
event all you need to do is write code like this:

class MyEvent : public nsRunnable {
public:
MyEvent(... params ...);
 
NS_IMETHOD Run() {
// do stuff
return NS_OK;
}
};

Dispatching <code>MyEvent</code> is then as simple as:

nsCOMPtr<nsIThread> thread = do_GetCurrentThread();
NS_ENSURE_STATE(thread);
 
nsCOMPtr<nsIRunnable> event = new MyEvent();
NS_ENSURE_STATE(event);
 
thread->Dispatch(event, NS_DISPATCH_NORMAL);

== From JS ==

=== Event Dispatch ===
Threads and Thread Manager implement <code>nsIClassInfo</code>:

function MyEvent() {
}
MyEvent.prototype = {
QueryInterface: function(iid) {
if (iid.equals(Components.interfaces.nsIRunnable) ||
iid.equals(Components.interfaces.nsISupports))
return this;
throw Components.results.NS_ERROR_NO_INTERFACE;
},
run: function() {
// do stuff
}
};
 
function DispatchMyEvent() {
var target =
Components.classes["@mozilla.org/thread-manager;1"].
getService().currentThread;
 
target.dispatch(new MyEvent(), target.DISPATCH_NORMAL);
}

== Remarks ==

* Thread priority for native threads can be exposed via <code>nsISupportsPriority</code>.
* Thread names must be unique.
* The Necko I/O thread pool will be replaced by a generic thread pool implementation provided by XPCOM. The thread pool will implement <code>nsIEventTarget</code>, allowing events to be dispatched to any thread in the thread pool. We may even wish to define a <code>nsIThreadPool</code> interface and have it implement that as well. That interface would define methods to adjust the limits on the number of threads in the thread pool and so on.
* We will need an alternative for <code>nsIEventQueue::RevokeEvents</code>. There are several possibilities: (1) make consumers hold references to their nsIRunnable's so they can "disconnect" them manually, or (2) expose an enumeration/visitor API that allows consumers to walk the list of pending tasks and remove arbitrary tasks. I'm not sure what is best yet. The first option or something similar based on weak references is probably best as it avoids the costly O(n) <code>RevokeEvents</code> call.
* The following interfaces/classes would go away or be modified heavily: <code>nsIEventQueue</code>, <code>nsIEventQueueService</code>, <code>nsIEventTarget</code>, <code>nsIThread</code>, <code>PLEvent</code>.
* Issue: Perhaps we should support calling <code>nsIThread::Shutdown</code> from the thread itself. That would probably have to be implemented by posting an event to the main thread, and having that thread call shutdown. However, <code>Shutdown</code> also has the property that it does not return until the thread is gone. That obvious can't happen if <code>Shutdown</code> is called on the thread itself.

=== What about "native" event queues? ===
The main thread where UI events are processed and the socket transport thread will use the observer interface defined by <code>nsIThreadInternal</code>. The main thread will interact with the "native" event system during calls to <code>ProcessNextEvent</code> and <code>Dispatch</code>. Likewise, the socket transport thread will similarly need to poll sockets and perform I/O operations. By observing calls to <code>ProcessNextEvent</code>, observers can wait on a native event queue (or poll on a set of file descriptors) instead of waiting on the thread's internal event queue monitor. When they observe a call to <code>Dispatch</code>, they can use whatever mechanism is appropriate to unblock the thread that is waiting on the native event queue.

=== How do synchronous events work? ===

When <code>Dispatch(event, DISPATCH_SYNC)</code> is called on a <code>nsIEventTarget</code>, it first checks to see if the current thread is the same as the thread where the event would be run. If it is, then it just runs the event directly without queuing it up. However, if not, then it must queue the event to be run when the dispatch target next processes its events. To avoid returning to the caller immediately, the method gets the current thread and calls its <code>ProcessNextEvent</code> method in a loop until it receives acknowledgement that the queued event has been run.

== Development ==

Development is occuring on the THREADS_20060213_BRANCH. See also {{bug|326273}}.

== Comments ==

=== biesi: ===
* What happens if shutdown is called while an event is being processed? I assume that this event will be processed to its end, no further events are accepted, and then the thread is shut down. right?
** What happens to events that were already dispatched to this thread, but not run?
* Is it a good idea to allow other events to run on the current thread while in dispatch?
* Who is expected to call ProcessNextEvent?

==== darin: ====
* When asked to shutdown, a thread would finish dispatching all queued events, and refuse to accept any new events. Once all queued events run to completion, the thread would terminate. This is consistent with how event queues work today.
* If you are sync dispatching, then it is necessary to pump events on the calling thread or else you could end up in a dead-lock situation. For example, if thread A sync dispatches an event to thread B, which cannot complete its job without dispatching an event back to thread A, then the system will dead-lock unless thread A continues to dispatch pending events.
* <code>ProcessNextEvent</code> may be called by anybody that wishes to implement the concept of a "modal event loop." For example, XMLHttpRequest (in sync configuration) would sit in a loop calling <code>ProcessNextEvent</code> while waiting for the underlying HTTP transaction to complete. The key difference between <code>ProcessNextEvent</code> and <code>nsIEventQueue::ProcessPendingEvents</code> is that <code>ProcessNextEvent</code>, when called on the UI thread, will process UI events as well. And, it will also wait (block the thread of execution) if there are no UI events or pending <code>nsIRunnable</code> events.

XPCOM:nsIThreadManager

2006-03-04T00:47:44Z

Darin: /* nsIThreadObserver */

In a world without nested event queues, the concept of a thread and an event queue merge...

== Interfaces ==
=== nsIThreadManager ===
[scriptable, uuid(...)]
interface nsIThreadManager : nsISupports {
/**
* Create a new named thread (a global, user PRThread). If the name is
* non-empty, then the name of the thread must be unique. Specifying an
* empty name results in an anonymous thread that cannot be found later on
* using the getThread method.
*/
nsIThread newThread(in ACString name);
 
/**
* Find a named thread. If no thread exists by the given name, then null
* is returned.
*/
nsIThread getThread(in ACString name);
 
/**
* Get the nsIThread object (if any) corresponding to the given PRThread.
* This method returns null if there is no corresponding nsIThread.
*/
[noscript] nsIThread getThreadFromPRThread(in PRThread thread);
 
/**
* Get the main thread.
*/
readonly attribute nsIThread mainThread;
 
/**
* Get the current thread.
*/
readonly attribute nsIThread currentThread;
 
/**
* This attribute is true if the calling thread is the main thread of the
* application process.
*/
readonly attribute boolean isMainThread;
};

=== nsIEventTarget ===
[scriptable, uuid(...)]
interface nsIEventTarget : nsISupports {
/**
* Dispatch an event to the target. This function may be called from any
* thread. If flags specifies DISPATCH_SYNC, then the dispatch method
* will not return until the event has been processed. NOTE: Calling
* dispatch with DISPATCH_SYNC, may have the side-effect of running other
* events on the current thread while waiting for the given event to run
* to completion. This function is thread-safe and re-entrant.
*/
void dispatch(in nsIRunnable event, in unsigned long flags);
const unsigned long DISPATCH_NORMAL = 0;
const unsigned long DISPATCH_SYNC = 1;
 
/**
* Returns true if events dispatched to this target will run on the
* current thread (i.e., the thread calling this method).
*/
boolean isOnCurrentThread();
};
 
%{C++
// convenient aliases:
#define NS_DISPATCH_NORMAL nsIEventTarget::DISPATCH_NORMAL
#define NS_DISPATCH_SYNC nsIEventTarget::DISPATCH_SYNC
%}

=== nsIThread ===
[scriptable, uuid(...)]
interface nsIThread : nsIEventTarget {
/**
* Returns the name of the thread, which may be empty if this thread is
* anonymous.
*/
readonly attribute ACString name;
 
/**
* Returns the PRThread object corresponding to this nsIThread.
*/
[noscript] PRThread getPRThread();
 
/**
* Shutdown the thread. This method may not be executed from the thread
* itself. Instead, it is meant to be executed from another thread (usually
* the thread that created this thread). When this function returns, the
* thread will be shutdown, and it will no longer be possible to dispatch
* events to the thread.
*/
void shutdown();
 
/**
* Returns true if this thread has one or more pending events.
*/
boolean hasPendingEvents();
 
/**
* Process the next event. If there are no pending events, then this
* method will wait until an event is dispatched to this thread. This
* method is re-entrant but may only be called if this thread is the
* current thread.
*/
void processNextEvent();
};
=== nsIThreadInternal ===
[scriptable, uuid(...)]
interface nsIThreadInternal : nsIThread {
/**
* Get/set an observer for this thread (may be null). This attribute may
* be read from any thread, but must only be set on the thread corresponding
* to this thread object.
*/
attribute nsIThreadObserver observer;
 
/**
* This method causes any events currently enqueued on the thread to be
* suppressed until PopEventQueue is called. Additionally, any new events
* dispatched to the thread will only be processed if they are accepted by
* the given filter. If the filter is null, then new events are accepted.
* Calls to PushEventQueue may be nested and must each be paired with a call
* to PopEventQueue in order to restore the original state of the thread.
*/
void pushEventQueue(in nsIThreadEventFilter filter);
 
/**
* Revert a call to PushEventQueue. When an event queue is popped, any
* events remaining in the queue are appended to the elder queue.
*/
void popEventQueue();
};

=== nsIThreadObserver ===
[scriptable, uuid(...)]
interface nsIThreadObserver : nsISupports {
/**
* This method is called after an event has been dispatched to the thread.
* This method may be called from any thread.
*/
void onDispatchedEvent(in nsIThreadInternal thread);
 
/**
* This method is called (from nsIThread::ProcessNextEvent) before an event
* is processed. This method is only called on the target thread.
*
* @param thread
* The thread being asked to process another event.
* @param mayWait
* Indicates whether or not the method is allowed to block the calling
* thread. For example, this parameter is false during thread shutdown.
*/
void onProcessNextEvent(in nsIThreadInternal thread,
in boolean mayWait);
};

=== nsIThreadEventFilter ===
[scriptable, uuid(...)]
interface nsIThreadEventFilter : nsISupports {
/**
* This method is called to determine whether or not an event may be accepted
* by a "nested" event queue (see nsIThreadInternal::PushEventQueue).
*
* WARNING: This method must not make any calls on the thread object.
*/
[notxpcom] boolean AcceptEvent(in nsIRunnable event);
};

=== nsIThreadPool ===
[scriptable, uuid(...)]
interface nsIThreadPool : nsIEventTarget
{
/**
* Shutdown the thread pool. This method may not be executed from any
* thread in the thread pool. Instead, it is meant to be executed from
* another thread (usually the thread that created this thread pool).
* When this function returns, the thread pool and all of its threads will
* be shutdown, and it will no longer be possible to dispatch tasks to the
* thread pool.
*/
void shutdown()
 
/**
* Get/set the maximum number of threads allowed at one time in this pool.
*/
attribute unsigned long threadLimit;
 
/**
* Get/set the maximum number of idle threads kept alive.
*/
attribute unsigned long idleThreadLimit;
 
/**
* Get/set the amount of time in milliseconds before an idle thread is
* destroyed.
*/
attribute unsigned long idleThreadTimeout;
};

== C++ Utilities ==

=== Functions ===
nsThreadUtils.h defines the following helper functions:

/**
* Create a new thread.
*
* @param name
* The name of the thread (must be unique) or the empty string to
* create an anonymous thread.
* @param event
* The initial event to run on this thread. This can be null.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_NewThread(const nsACString &name, nsIRunnable *event,
nsIThread **result);
 
/**
* Get a reference to the current thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetCurrentThread(nsIThread **result);
 
/**
* Get a reference to the main thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetMainThread(nsIThread **result);
 
/**
* Get a reference to the thread with the given name.
*
* @param name
* The name of the requested thread. Must be non-empty.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetThread(const nsACString &name, nsIThread **result);
 
/**
* Test to see if the current thread is the main thread.
*
* @returns PR_TRUE if the current thread is the main thread, and PR_FALSE
* otherwise.
*/
PRBool NS_IsMainThread();
 
/**
* Dispatch the given event to the current thread.
*
* @param event
* The event to dispatch.
*/
NS_METHOD NS_DispatchToCurrentThread(nsIRunnable *event);
 
/**
* Dispatch the given event to the main thread.
*
* @param event
* The event to dispatch.
* @param dispatchFlags
* The flags to pass to the main thread's dispatch method.
*/
NS_METHOD NS_DispatchToMainThread(nsIRunnable *event,
PRUint32 dispatchFlags = NS_DISPATCH_NORMAL);
 
/**
* Process all pending events for the given thread before returning. This
* method simply calls ProcessNextEvent on the thread while HasPendingEvents
* continues to return true and the time spent in NS_ProcessPendingEvents
* does not exceed the given timeout value.
*
* @param thread
* The thread object for which to process pending events. If null,
* then events will be processed for the current thread.
* @param timeout
* The maximum number of milliseconds to spend processing pending
* events. Events are not pre-empted to honor this timeout. Rather,
* the timeout value is simply used to determine whether or not to
* process another event. Pass PR_INTERVAL_NO_TIMEOUT to specify no
* timeout.
*/
NS_METHOD NS_ProcessPendingEvents(nsIThread *thread = nsnull,
PRIntervalTime timeout = PR_INTERVAL_NO_TIMEOUT);

=== nsCOMPtr helpers ===
The following nsCOMPtr helpers are defined to simplify things further:

already_AddRefed<nsIThread> do_GetCurrentThread();
 
already_AddRefed<nsIThread> do_GetMainThread();
 
already_AddRefed<nsIThread> do_GetThread(const nsACString &name);

=== nsRunnable ===
The class <code>nsRunnable</code> is also defined to simplify the
implementation of new event types. For example, to define a new
event all you need to do is write code like this:

class MyEvent : public nsRunnable {
public:
MyEvent(... params ...);
 
NS_IMETHOD Run() {
// do stuff
return NS_OK;
}
};

Dispatching <code>MyEvent</code> is then as simple as:

nsCOMPtr<nsIThread> thread = do_GetCurrentThread();
NS_ENSURE_STATE(thread);
 
nsCOMPtr<nsIRunnable> event = new MyEvent();
NS_ENSURE_STATE(event);
 
thread->Dispatch(event, NS_DISPATCH_NORMAL);

== From JS ==

=== Event Dispatch ===
Threads and Thread Manager implement <code>nsIClassInfo</code>:

function MyEvent() {
}
MyEvent.prototype = {
QueryInterface: function(iid) {
if (iid.equals(Components.interfaces.nsIRunnable) ||
iid.equals(Components.interfaces.nsISupports))
return this;
throw Components.results.NS_ERROR_NO_INTERFACE;
},
run: function() {
// do stuff
}
};
 
function DispatchMyEvent() {
var target =
Components.classes["@mozilla.org/thread-manager;1"].
getService().currentThread;
 
target.dispatch(new MyEvent(), target.DISPATCH_NORMAL);
}

== Remarks ==

* Thread priority for native threads can be exposed via <code>nsISupportsPriority</code>.
* Thread names must be unique.
* The Necko I/O thread pool will be replaced by a generic thread pool implementation provided by XPCOM. The thread pool will implement <code>nsIEventTarget</code>, allowing events to be dispatched to any thread in the thread pool. We may even wish to define a <code>nsIThreadPool</code> interface and have it implement that as well. That interface would define methods to adjust the limits on the number of threads in the thread pool and so on.
* We will need an alternative for <code>nsIEventQueue::RevokeEvents</code>. There are several possibilities: (1) make consumers hold references to their nsIRunnable's so they can "disconnect" them manually, or (2) expose an enumeration/visitor API that allows consumers to walk the list of pending tasks and remove arbitrary tasks. I'm not sure what is best yet. The first option or something similar based on weak references is probably best as it avoids the costly O(n) <code>RevokeEvents</code> call.
* The following interfaces/classes would go away or be modified heavily: nsIEventQueue, nsIEventQueueService, nsIEventTarget, nsIThread, PLEvent.
* Issue: Perhaps we should support calling <code>nsIThread::Shutdown</code> from the thread itself. That would probably have to be implemented by posting an event to the main thread, and having that thread call shutdown. However, <code>Shutdown</code> also has the property that it does not return until the thread is gone. That obvious can't happen if <code>Shutdown</code> is called on the thread itself.

=== What about "native" event queues? ===
The main thread where UI events are processed and the socket transport thread will use the observer interface defined by <code>nsIThreadInternal</code>. The main thread will interact with the "native" event system during calls to <code>ProcessNextEvent</code> and <code>Dispatch</code>. Likewise, the socket transport thread will similarly need to poll sockets and perform I/O operations. By observing calls to <code>ProcessNextEvent</code>, observers can wait on a native event queue (or poll on a set of file descriptors) instead of waiting on the thread's internal event queue monitor. When they observe a call to <code>Dispatch</code>, they can use whatever mechanism is appropriate to unblock the thread that is waiting on the native event queue.

=== How do synchronous events work? ===

When <code>Dispatch(event, DISPATCH_SYNC)</code> is called on a <code>nsIEventTarget</code>, it first checks to see if the current thread is the same as the thread where the event would be run. If it is, then it just runs the event directly without queuing it up. However, if not, then it must queue the event to be run when the dispatch target next processes its events. To avoid returning to the caller immediately, the method gets the current thread and calls its <code>ProcessNextEvent</code> method in a loop until it receives acknowledgement that the queued event has been run.

== Development ==

Development is occuring on the THREADS_20060213_BRANCH. See also {{bug|326273}}.

== Comments ==

=== biesi: ===
* What happens if shutdown is called while an event is being processed? I assume that this event will be processed to its end, no further events are accepted, and then the thread is shut down. right?
** What happens to events that were already dispatched to this thread, but not run?
* Is it a good idea to allow other events to run on the current thread while in dispatch?
* Who is expected to call ProcessNextEvent?

==== darin: ====
* When asked to shutdown, a thread would finish dispatching all queued events, and refuse to accept any new events. Once all queued events run to completion, the thread would terminate. This is consistent with how event queues work today.
* If you are sync dispatching, then it is necessary to pump events on the calling thread or else you could end up in a dead-lock situation. For example, if thread A sync dispatches an event to thread B, which cannot complete its job without dispatching an event back to thread A, then the system will dead-lock unless thread A continues to dispatch pending events.
* <code>ProcessNextEvent</code> may be called by anybody that wishes to implement the concept of a "modal event loop." For example, XMLHttpRequest (in sync configuration) would sit in a loop calling <code>ProcessNextEvent</code> while waiting for the underlying HTTP transaction to complete. The key difference between <code>ProcessNextEvent</code> and <code>nsIEventQueue::ProcessPendingEvents</code> is that <code>ProcessNextEvent</code>, when called on the UI thread, will process UI events as well. And, it will also wait (block the thread of execution) if there are no UI events or pending <code>nsIRunnable</code> events.

XPCOM:nsIThreadManager

2006-03-04T00:46:58Z

Darin: /* nsIThreadObserver */

In a world without nested event queues, the concept of a thread and an event queue merge...

== Interfaces ==
=== nsIThreadManager ===
[scriptable, uuid(...)]
interface nsIThreadManager : nsISupports {
/**
* Create a new named thread (a global, user PRThread). If the name is
* non-empty, then the name of the thread must be unique. Specifying an
* empty name results in an anonymous thread that cannot be found later on
* using the getThread method.
*/
nsIThread newThread(in ACString name);
 
/**
* Find a named thread. If no thread exists by the given name, then null
* is returned.
*/
nsIThread getThread(in ACString name);
 
/**
* Get the nsIThread object (if any) corresponding to the given PRThread.
* This method returns null if there is no corresponding nsIThread.
*/
[noscript] nsIThread getThreadFromPRThread(in PRThread thread);
 
/**
* Get the main thread.
*/
readonly attribute nsIThread mainThread;
 
/**
* Get the current thread.
*/
readonly attribute nsIThread currentThread;
 
/**
* This attribute is true if the calling thread is the main thread of the
* application process.
*/
readonly attribute boolean isMainThread;
};

=== nsIEventTarget ===
[scriptable, uuid(...)]
interface nsIEventTarget : nsISupports {
/**
* Dispatch an event to the target. This function may be called from any
* thread. If flags specifies DISPATCH_SYNC, then the dispatch method
* will not return until the event has been processed. NOTE: Calling
* dispatch with DISPATCH_SYNC, may have the side-effect of running other
* events on the current thread while waiting for the given event to run
* to completion. This function is thread-safe and re-entrant.
*/
void dispatch(in nsIRunnable event, in unsigned long flags);
const unsigned long DISPATCH_NORMAL = 0;
const unsigned long DISPATCH_SYNC = 1;
 
/**
* Returns true if events dispatched to this target will run on the
* current thread (i.e., the thread calling this method).
*/
boolean isOnCurrentThread();
};
 
%{C++
// convenient aliases:
#define NS_DISPATCH_NORMAL nsIEventTarget::DISPATCH_NORMAL
#define NS_DISPATCH_SYNC nsIEventTarget::DISPATCH_SYNC
%}

=== nsIThread ===
[scriptable, uuid(...)]
interface nsIThread : nsIEventTarget {
/**
* Returns the name of the thread, which may be empty if this thread is
* anonymous.
*/
readonly attribute ACString name;
 
/**
* Returns the PRThread object corresponding to this nsIThread.
*/
[noscript] PRThread getPRThread();
 
/**
* Shutdown the thread. This method may not be executed from the thread
* itself. Instead, it is meant to be executed from another thread (usually
* the thread that created this thread). When this function returns, the
* thread will be shutdown, and it will no longer be possible to dispatch
* events to the thread.
*/
void shutdown();
 
/**
* Returns true if this thread has one or more pending events.
*/
boolean hasPendingEvents();
 
/**
* Process the next event. If there are no pending events, then this
* method will wait until an event is dispatched to this thread. This
* method is re-entrant but may only be called if this thread is the
* current thread.
*/
void processNextEvent();
};
=== nsIThreadInternal ===
[scriptable, uuid(...)]
interface nsIThreadInternal : nsIThread {
/**
* Get/set an observer for this thread (may be null). This attribute may
* be read from any thread, but must only be set on the thread corresponding
* to this thread object.
*/
attribute nsIThreadObserver observer;
 
/**
* This method causes any events currently enqueued on the thread to be
* suppressed until PopEventQueue is called. Additionally, any new events
* dispatched to the thread will only be processed if they are accepted by
* the given filter. If the filter is null, then new events are accepted.
* Calls to PushEventQueue may be nested and must each be paired with a call
* to PopEventQueue in order to restore the original state of the thread.
*/
void pushEventQueue(in nsIThreadEventFilter filter);
 
/**
* Revert a call to PushEventQueue. When an event queue is popped, any
* events remaining in the queue are appended to the elder queue.
*/
void popEventQueue();
};

=== nsIThreadObserver ===
[scriptable, uuid(...)]
interface nsIThreadObserver : nsISupports {
/**
* This method is called after an event has been dispatched to the thread.
* This method may be called from any thread.
*/
void onDispatchedEvent(in nsIThreadInternal thread);
 
/**
* This method is called (from nsIThread::ProcessNextEvent) before an event
* is processed. This method is only called on the target thread.
*
* @param thread
* The thread being asked to process another event.
* @param mayWait
* Indicates whether or not the method is allowed to block the calling
* thread. For example, this parameter is false during thread shutdown.
*/
void onProcessNextEvent(in nsIThreadInternal thread,
in boolean mayWait);
};

=== nsIThreadPool ===
[scriptable, uuid(...)]
interface nsIThreadPool : nsIEventTarget
{
/**
* Shutdown the thread pool. This method may not be executed from any
* thread in the thread pool. Instead, it is meant to be executed from
* another thread (usually the thread that created this thread pool).
* When this function returns, the thread pool and all of its threads will
* be shutdown, and it will no longer be possible to dispatch tasks to the
* thread pool.
*/
void shutdown()
 
/**
* Get/set the maximum number of threads allowed at one time in this pool.
*/
attribute unsigned long threadLimit;
 
/**
* Get/set the maximum number of idle threads kept alive.
*/
attribute unsigned long idleThreadLimit;
 
/**
* Get/set the amount of time in milliseconds before an idle thread is
* destroyed.
*/
attribute unsigned long idleThreadTimeout;
};

== C++ Utilities ==

=== Functions ===
nsThreadUtils.h defines the following helper functions:

/**
* Create a new thread.
*
* @param name
* The name of the thread (must be unique) or the empty string to
* create an anonymous thread.
* @param event
* The initial event to run on this thread. This can be null.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_NewThread(const nsACString &name, nsIRunnable *event,
nsIThread **result);
 
/**
* Get a reference to the current thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetCurrentThread(nsIThread **result);
 
/**
* Get a reference to the main thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetMainThread(nsIThread **result);
 
/**
* Get a reference to the thread with the given name.
*
* @param name
* The name of the requested thread. Must be non-empty.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetThread(const nsACString &name, nsIThread **result);
 
/**
* Test to see if the current thread is the main thread.
*
* @returns PR_TRUE if the current thread is the main thread, and PR_FALSE
* otherwise.
*/
PRBool NS_IsMainThread();
 
/**
* Dispatch the given event to the current thread.
*
* @param event
* The event to dispatch.
*/
NS_METHOD NS_DispatchToCurrentThread(nsIRunnable *event);
 
/**
* Dispatch the given event to the main thread.
*
* @param event
* The event to dispatch.
* @param dispatchFlags
* The flags to pass to the main thread's dispatch method.
*/
NS_METHOD NS_DispatchToMainThread(nsIRunnable *event,
PRUint32 dispatchFlags = NS_DISPATCH_NORMAL);
 
/**
* Process all pending events for the given thread before returning. This
* method simply calls ProcessNextEvent on the thread while HasPendingEvents
* continues to return true and the time spent in NS_ProcessPendingEvents
* does not exceed the given timeout value.
*
* @param thread
* The thread object for which to process pending events. If null,
* then events will be processed for the current thread.
* @param timeout
* The maximum number of milliseconds to spend processing pending
* events. Events are not pre-empted to honor this timeout. Rather,
* the timeout value is simply used to determine whether or not to
* process another event. Pass PR_INTERVAL_NO_TIMEOUT to specify no
* timeout.
*/
NS_METHOD NS_ProcessPendingEvents(nsIThread *thread = nsnull,
PRIntervalTime timeout = PR_INTERVAL_NO_TIMEOUT);

=== nsCOMPtr helpers ===
The following nsCOMPtr helpers are defined to simplify things further:

already_AddRefed<nsIThread> do_GetCurrentThread();
 
already_AddRefed<nsIThread> do_GetMainThread();
 
already_AddRefed<nsIThread> do_GetThread(const nsACString &name);

=== nsRunnable ===
The class <code>nsRunnable</code> is also defined to simplify the
implementation of new event types. For example, to define a new
event all you need to do is write code like this:

class MyEvent : public nsRunnable {
public:
MyEvent(... params ...);
 
NS_IMETHOD Run() {
// do stuff
return NS_OK;
}
};

Dispatching <code>MyEvent</code> is then as simple as:

nsCOMPtr<nsIThread> thread = do_GetCurrentThread();
NS_ENSURE_STATE(thread);
 
nsCOMPtr<nsIRunnable> event = new MyEvent();
NS_ENSURE_STATE(event);
 
thread->Dispatch(event, NS_DISPATCH_NORMAL);

== From JS ==

=== Event Dispatch ===
Threads and Thread Manager implement <code>nsIClassInfo</code>:

function MyEvent() {
}
MyEvent.prototype = {
QueryInterface: function(iid) {
if (iid.equals(Components.interfaces.nsIRunnable) ||
iid.equals(Components.interfaces.nsISupports))
return this;
throw Components.results.NS_ERROR_NO_INTERFACE;
},
run: function() {
// do stuff
}
};
 
function DispatchMyEvent() {
var target =
Components.classes["@mozilla.org/thread-manager;1"].
getService().currentThread;
 
target.dispatch(new MyEvent(), target.DISPATCH_NORMAL);
}

== Remarks ==

* Thread priority for native threads can be exposed via <code>nsISupportsPriority</code>.
* Thread names must be unique.
* The Necko I/O thread pool will be replaced by a generic thread pool implementation provided by XPCOM. The thread pool will implement <code>nsIEventTarget</code>, allowing events to be dispatched to any thread in the thread pool. We may even wish to define a <code>nsIThreadPool</code> interface and have it implement that as well. That interface would define methods to adjust the limits on the number of threads in the thread pool and so on.
* We will need an alternative for <code>nsIEventQueue::RevokeEvents</code>. There are several possibilities: (1) make consumers hold references to their nsIRunnable's so they can "disconnect" them manually, or (2) expose an enumeration/visitor API that allows consumers to walk the list of pending tasks and remove arbitrary tasks. I'm not sure what is best yet. The first option or something similar based on weak references is probably best as it avoids the costly O(n) <code>RevokeEvents</code> call.
* The following interfaces/classes would go away or be modified heavily: nsIEventQueue, nsIEventQueueService, nsIEventTarget, nsIThread, PLEvent.
* Issue: Perhaps we should support calling <code>nsIThread::Shutdown</code> from the thread itself. That would probably have to be implemented by posting an event to the main thread, and having that thread call shutdown. However, <code>Shutdown</code> also has the property that it does not return until the thread is gone. That obvious can't happen if <code>Shutdown</code> is called on the thread itself.

=== What about "native" event queues? ===
The main thread where UI events are processed and the socket transport thread will use the observer interface defined by <code>nsIThreadInternal</code>. The main thread will interact with the "native" event system during calls to <code>ProcessNextEvent</code> and <code>Dispatch</code>. Likewise, the socket transport thread will similarly need to poll sockets and perform I/O operations. By observing calls to <code>ProcessNextEvent</code>, observers can wait on a native event queue (or poll on a set of file descriptors) instead of waiting on the thread's internal event queue monitor. When they observe a call to <code>Dispatch</code>, they can use whatever mechanism is appropriate to unblock the thread that is waiting on the native event queue.

=== How do synchronous events work? ===

When <code>Dispatch(event, DISPATCH_SYNC)</code> is called on a <code>nsIEventTarget</code>, it first checks to see if the current thread is the same as the thread where the event would be run. If it is, then it just runs the event directly without queuing it up. However, if not, then it must queue the event to be run when the dispatch target next processes its events. To avoid returning to the caller immediately, the method gets the current thread and calls its <code>ProcessNextEvent</code> method in a loop until it receives acknowledgement that the queued event has been run.

== Development ==

Development is occuring on the THREADS_20060213_BRANCH. See also {{bug|326273}}.

== Comments ==

=== biesi: ===
* What happens if shutdown is called while an event is being processed? I assume that this event will be processed to its end, no further events are accepted, and then the thread is shut down. right?
** What happens to events that were already dispatched to this thread, but not run?
* Is it a good idea to allow other events to run on the current thread while in dispatch?
* Who is expected to call ProcessNextEvent?

==== darin: ====
* When asked to shutdown, a thread would finish dispatching all queued events, and refuse to accept any new events. Once all queued events run to completion, the thread would terminate. This is consistent with how event queues work today.
* If you are sync dispatching, then it is necessary to pump events on the calling thread or else you could end up in a dead-lock situation. For example, if thread A sync dispatches an event to thread B, which cannot complete its job without dispatching an event back to thread A, then the system will dead-lock unless thread A continues to dispatch pending events.
* <code>ProcessNextEvent</code> may be called by anybody that wishes to implement the concept of a "modal event loop." For example, XMLHttpRequest (in sync configuration) would sit in a loop calling <code>ProcessNextEvent</code> while waiting for the underlying HTTP transaction to complete. The key difference between <code>ProcessNextEvent</code> and <code>nsIEventQueue::ProcessPendingEvents</code> is that <code>ProcessNextEvent</code>, when called on the UI thread, will process UI events as well. And, it will also wait (block the thread of execution) if there are no UI events or pending <code>nsIRunnable</code> events.

XPCOM:nsIThreadManager

2006-03-04T00:45:18Z

Darin: /* nsIThreadInternal */

In a world without nested event queues, the concept of a thread and an event queue merge...

== Interfaces ==
=== nsIThreadManager ===
[scriptable, uuid(...)]
interface nsIThreadManager : nsISupports {
/**
* Create a new named thread (a global, user PRThread). If the name is
* non-empty, then the name of the thread must be unique. Specifying an
* empty name results in an anonymous thread that cannot be found later on
* using the getThread method.
*/
nsIThread newThread(in ACString name);
 
/**
* Find a named thread. If no thread exists by the given name, then null
* is returned.
*/
nsIThread getThread(in ACString name);
 
/**
* Get the nsIThread object (if any) corresponding to the given PRThread.
* This method returns null if there is no corresponding nsIThread.
*/
[noscript] nsIThread getThreadFromPRThread(in PRThread thread);
 
/**
* Get the main thread.
*/
readonly attribute nsIThread mainThread;
 
/**
* Get the current thread.
*/
readonly attribute nsIThread currentThread;
 
/**
* This attribute is true if the calling thread is the main thread of the
* application process.
*/
readonly attribute boolean isMainThread;
};

=== nsIEventTarget ===
[scriptable, uuid(...)]
interface nsIEventTarget : nsISupports {
/**
* Dispatch an event to the target. This function may be called from any
* thread. If flags specifies DISPATCH_SYNC, then the dispatch method
* will not return until the event has been processed. NOTE: Calling
* dispatch with DISPATCH_SYNC, may have the side-effect of running other
* events on the current thread while waiting for the given event to run
* to completion. This function is thread-safe and re-entrant.
*/
void dispatch(in nsIRunnable event, in unsigned long flags);
const unsigned long DISPATCH_NORMAL = 0;
const unsigned long DISPATCH_SYNC = 1;
 
/**
* Returns true if events dispatched to this target will run on the
* current thread (i.e., the thread calling this method).
*/
boolean isOnCurrentThread();
};
 
%{C++
// convenient aliases:
#define NS_DISPATCH_NORMAL nsIEventTarget::DISPATCH_NORMAL
#define NS_DISPATCH_SYNC nsIEventTarget::DISPATCH_SYNC
%}

=== nsIThread ===
[scriptable, uuid(...)]
interface nsIThread : nsIEventTarget {
/**
* Returns the name of the thread, which may be empty if this thread is
* anonymous.
*/
readonly attribute ACString name;
 
/**
* Returns the PRThread object corresponding to this nsIThread.
*/
[noscript] PRThread getPRThread();
 
/**
* Shutdown the thread. This method may not be executed from the thread
* itself. Instead, it is meant to be executed from another thread (usually
* the thread that created this thread). When this function returns, the
* thread will be shutdown, and it will no longer be possible to dispatch
* events to the thread.
*/
void shutdown();
 
/**
* Returns true if this thread has one or more pending events.
*/
boolean hasPendingEvents();
 
/**
* Process the next event. If there are no pending events, then this
* method will wait until an event is dispatched to this thread. This
* method is re-entrant but may only be called if this thread is the
* current thread.
*/
void processNextEvent();
};
=== nsIThreadInternal ===
[scriptable, uuid(...)]
interface nsIThreadInternal : nsIThread {
/**
* Get/set an observer for this thread (may be null). This attribute may
* be read from any thread, but must only be set on the thread corresponding
* to this thread object.
*/
attribute nsIThreadObserver observer;
 
/**
* This method causes any events currently enqueued on the thread to be
* suppressed until PopEventQueue is called. Additionally, any new events
* dispatched to the thread will only be processed if they are accepted by
* the given filter. If the filter is null, then new events are accepted.
* Calls to PushEventQueue may be nested and must each be paired with a call
* to PopEventQueue in order to restore the original state of the thread.
*/
void pushEventQueue(in nsIThreadEventFilter filter);
 
/**
* Revert a call to PushEventQueue. When an event queue is popped, any
* events remaining in the queue are appended to the elder queue.
*/
void popEventQueue();
};

=== nsIThreadObserver ===
[scriptable, uuid(...)]
interface nsIThreadObserver : nsISupports {
/**
* Called when an event is dispatched to the thread. This method
* may be called on any thread.
*/
void onDispatchEvent(in nsIThreadInternal thread,
in unsigned long flags);
 
/**
* Called at the beginning of nsIThread::processNextEvent.
*/
void onEnterProcessNextEvent(in nsIThreadInternal thread);
 
/**
* Called at the end of nsIThread::processNextEvent.
*/
void onLeaveProcessNextEvent(in nsIThreadInternal thread);
};
=== nsIThreadPool ===
[scriptable, uuid(...)]
interface nsIThreadPool : nsIEventTarget
{
/**
* Shutdown the thread pool. This method may not be executed from any
* thread in the thread pool. Instead, it is meant to be executed from
* another thread (usually the thread that created this thread pool).
* When this function returns, the thread pool and all of its threads will
* be shutdown, and it will no longer be possible to dispatch tasks to the
* thread pool.
*/
void shutdown()
 
/**
* Get/set the maximum number of threads allowed at one time in this pool.
*/
attribute unsigned long threadLimit;
 
/**
* Get/set the maximum number of idle threads kept alive.
*/
attribute unsigned long idleThreadLimit;
 
/**
* Get/set the amount of time in milliseconds before an idle thread is
* destroyed.
*/
attribute unsigned long idleThreadTimeout;
};

== C++ Utilities ==

=== Functions ===
nsThreadUtils.h defines the following helper functions:

/**
* Create a new thread.
*
* @param name
* The name of the thread (must be unique) or the empty string to
* create an anonymous thread.
* @param event
* The initial event to run on this thread. This can be null.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_NewThread(const nsACString &name, nsIRunnable *event,
nsIThread **result);
 
/**
* Get a reference to the current thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetCurrentThread(nsIThread **result);
 
/**
* Get a reference to the main thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetMainThread(nsIThread **result);
 
/**
* Get a reference to the thread with the given name.
*
* @param name
* The name of the requested thread. Must be non-empty.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetThread(const nsACString &name, nsIThread **result);
 
/**
* Test to see if the current thread is the main thread.
*
* @returns PR_TRUE if the current thread is the main thread, and PR_FALSE
* otherwise.
*/
PRBool NS_IsMainThread();
 
/**
* Dispatch the given event to the current thread.
*
* @param event
* The event to dispatch.
*/
NS_METHOD NS_DispatchToCurrentThread(nsIRunnable *event);
 
/**
* Dispatch the given event to the main thread.
*
* @param event
* The event to dispatch.
* @param dispatchFlags
* The flags to pass to the main thread's dispatch method.
*/
NS_METHOD NS_DispatchToMainThread(nsIRunnable *event,
PRUint32 dispatchFlags = NS_DISPATCH_NORMAL);
 
/**
* Process all pending events for the given thread before returning. This
* method simply calls ProcessNextEvent on the thread while HasPendingEvents
* continues to return true and the time spent in NS_ProcessPendingEvents
* does not exceed the given timeout value.
*
* @param thread
* The thread object for which to process pending events. If null,
* then events will be processed for the current thread.
* @param timeout
* The maximum number of milliseconds to spend processing pending
* events. Events are not pre-empted to honor this timeout. Rather,
* the timeout value is simply used to determine whether or not to
* process another event. Pass PR_INTERVAL_NO_TIMEOUT to specify no
* timeout.
*/
NS_METHOD NS_ProcessPendingEvents(nsIThread *thread = nsnull,
PRIntervalTime timeout = PR_INTERVAL_NO_TIMEOUT);

=== nsCOMPtr helpers ===
The following nsCOMPtr helpers are defined to simplify things further:

already_AddRefed<nsIThread> do_GetCurrentThread();
 
already_AddRefed<nsIThread> do_GetMainThread();
 
already_AddRefed<nsIThread> do_GetThread(const nsACString &name);

=== nsRunnable ===
The class <code>nsRunnable</code> is also defined to simplify the
implementation of new event types. For example, to define a new
event all you need to do is write code like this:

class MyEvent : public nsRunnable {
public:
MyEvent(... params ...);
 
NS_IMETHOD Run() {
// do stuff
return NS_OK;
}
};

Dispatching <code>MyEvent</code> is then as simple as:

nsCOMPtr<nsIThread> thread = do_GetCurrentThread();
NS_ENSURE_STATE(thread);
 
nsCOMPtr<nsIRunnable> event = new MyEvent();
NS_ENSURE_STATE(event);
 
thread->Dispatch(event, NS_DISPATCH_NORMAL);

== From JS ==

=== Event Dispatch ===
Threads and Thread Manager implement <code>nsIClassInfo</code>:

function MyEvent() {
}
MyEvent.prototype = {
QueryInterface: function(iid) {
if (iid.equals(Components.interfaces.nsIRunnable) ||
iid.equals(Components.interfaces.nsISupports))
return this;
throw Components.results.NS_ERROR_NO_INTERFACE;
},
run: function() {
// do stuff
}
};
 
function DispatchMyEvent() {
var target =
Components.classes["@mozilla.org/thread-manager;1"].
getService().currentThread;
 
target.dispatch(new MyEvent(), target.DISPATCH_NORMAL);
}

== Remarks ==

* Thread priority for native threads can be exposed via <code>nsISupportsPriority</code>.
* Thread names must be unique.
* The Necko I/O thread pool will be replaced by a generic thread pool implementation provided by XPCOM. The thread pool will implement <code>nsIEventTarget</code>, allowing events to be dispatched to any thread in the thread pool. We may even wish to define a <code>nsIThreadPool</code> interface and have it implement that as well. That interface would define methods to adjust the limits on the number of threads in the thread pool and so on.
* We will need an alternative for <code>nsIEventQueue::RevokeEvents</code>. There are several possibilities: (1) make consumers hold references to their nsIRunnable's so they can "disconnect" them manually, or (2) expose an enumeration/visitor API that allows consumers to walk the list of pending tasks and remove arbitrary tasks. I'm not sure what is best yet. The first option or something similar based on weak references is probably best as it avoids the costly O(n) <code>RevokeEvents</code> call.
* The following interfaces/classes would go away or be modified heavily: nsIEventQueue, nsIEventQueueService, nsIEventTarget, nsIThread, PLEvent.
* Issue: Perhaps we should support calling <code>nsIThread::Shutdown</code> from the thread itself. That would probably have to be implemented by posting an event to the main thread, and having that thread call shutdown. However, <code>Shutdown</code> also has the property that it does not return until the thread is gone. That obvious can't happen if <code>Shutdown</code> is called on the thread itself.

=== What about "native" event queues? ===
The main thread where UI events are processed and the socket transport thread will use the observer interface defined by <code>nsIThreadInternal</code>. The main thread will interact with the "native" event system during calls to <code>ProcessNextEvent</code> and <code>Dispatch</code>. Likewise, the socket transport thread will similarly need to poll sockets and perform I/O operations. By observing calls to <code>ProcessNextEvent</code>, observers can wait on a native event queue (or poll on a set of file descriptors) instead of waiting on the thread's internal event queue monitor. When they observe a call to <code>Dispatch</code>, they can use whatever mechanism is appropriate to unblock the thread that is waiting on the native event queue.

=== How do synchronous events work? ===

When <code>Dispatch(event, DISPATCH_SYNC)</code> is called on a <code>nsIEventTarget</code>, it first checks to see if the current thread is the same as the thread where the event would be run. If it is, then it just runs the event directly without queuing it up. However, if not, then it must queue the event to be run when the dispatch target next processes its events. To avoid returning to the caller immediately, the method gets the current thread and calls its <code>ProcessNextEvent</code> method in a loop until it receives acknowledgement that the queued event has been run.

== Development ==

Development is occuring on the THREADS_20060213_BRANCH. See also {{bug|326273}}.

== Comments ==

=== biesi: ===
* What happens if shutdown is called while an event is being processed? I assume that this event will be processed to its end, no further events are accepted, and then the thread is shut down. right?
** What happens to events that were already dispatched to this thread, but not run?
* Is it a good idea to allow other events to run on the current thread while in dispatch?
* Who is expected to call ProcessNextEvent?

==== darin: ====
* When asked to shutdown, a thread would finish dispatching all queued events, and refuse to accept any new events. Once all queued events run to completion, the thread would terminate. This is consistent with how event queues work today.
* If you are sync dispatching, then it is necessary to pump events on the calling thread or else you could end up in a dead-lock situation. For example, if thread A sync dispatches an event to thread B, which cannot complete its job without dispatching an event back to thread A, then the system will dead-lock unless thread A continues to dispatch pending events.
* <code>ProcessNextEvent</code> may be called by anybody that wishes to implement the concept of a "modal event loop." For example, XMLHttpRequest (in sync configuration) would sit in a loop calling <code>ProcessNextEvent</code> while waiting for the underlying HTTP transaction to complete. The key difference between <code>ProcessNextEvent</code> and <code>nsIEventQueue::ProcessPendingEvents</code> is that <code>ProcessNextEvent</code>, when called on the UI thread, will process UI events as well. And, it will also wait (block the thread of execution) if there are no UI events or pending <code>nsIRunnable</code> events.

XPCOM:nsIThreadManager

2006-03-04T00:44:09Z

Darin: /* nsIThreadInternal */

In a world without nested event queues, the concept of a thread and an event queue merge...

== Interfaces ==
=== nsIThreadManager ===
[scriptable, uuid(...)]
interface nsIThreadManager : nsISupports {
/**
* Create a new named thread (a global, user PRThread). If the name is
* non-empty, then the name of the thread must be unique. Specifying an
* empty name results in an anonymous thread that cannot be found later on
* using the getThread method.
*/
nsIThread newThread(in ACString name);
 
/**
* Find a named thread. If no thread exists by the given name, then null
* is returned.
*/
nsIThread getThread(in ACString name);
 
/**
* Get the nsIThread object (if any) corresponding to the given PRThread.
* This method returns null if there is no corresponding nsIThread.
*/
[noscript] nsIThread getThreadFromPRThread(in PRThread thread);
 
/**
* Get the main thread.
*/
readonly attribute nsIThread mainThread;
 
/**
* Get the current thread.
*/
readonly attribute nsIThread currentThread;
 
/**
* This attribute is true if the calling thread is the main thread of the
* application process.
*/
readonly attribute boolean isMainThread;
};

=== nsIEventTarget ===
[scriptable, uuid(...)]
interface nsIEventTarget : nsISupports {
/**
* Dispatch an event to the target. This function may be called from any
* thread. If flags specifies DISPATCH_SYNC, then the dispatch method
* will not return until the event has been processed. NOTE: Calling
* dispatch with DISPATCH_SYNC, may have the side-effect of running other
* events on the current thread while waiting for the given event to run
* to completion. This function is thread-safe and re-entrant.
*/
void dispatch(in nsIRunnable event, in unsigned long flags);
const unsigned long DISPATCH_NORMAL = 0;
const unsigned long DISPATCH_SYNC = 1;
 
/**
* Returns true if events dispatched to this target will run on the
* current thread (i.e., the thread calling this method).
*/
boolean isOnCurrentThread();
};
 
%{C++
// convenient aliases:
#define NS_DISPATCH_NORMAL nsIEventTarget::DISPATCH_NORMAL
#define NS_DISPATCH_SYNC nsIEventTarget::DISPATCH_SYNC
%}

=== nsIThread ===
[scriptable, uuid(...)]
interface nsIThread : nsIEventTarget {
/**
* Returns the name of the thread, which may be empty if this thread is
* anonymous.
*/
readonly attribute ACString name;
 
/**
* Returns the PRThread object corresponding to this nsIThread.
*/
[noscript] PRThread getPRThread();
 
/**
* Shutdown the thread. This method may not be executed from the thread
* itself. Instead, it is meant to be executed from another thread (usually
* the thread that created this thread). When this function returns, the
* thread will be shutdown, and it will no longer be possible to dispatch
* events to the thread.
*/
void shutdown();
 
/**
* Returns true if this thread has one or more pending events.
*/
boolean hasPendingEvents();
 
/**
* Process the next event. If there are no pending events, then this
* method will wait until an event is dispatched to this thread. This
* method is re-entrant but may only be called if this thread is the
* current thread.
*/
void processNextEvent();
};
=== nsIThreadInternal ===
[scriptable, uuid(...)]
interface nsIThreadInternal : nsIThread {
/**
* Get/set an observer for this thread.
*/
attribute nsIThreadObserver observer;
 
/**
* This method causes any events currently enqueued on the thread to be
* suppressed until PopEventQueue is called. Additionally, any new events
* dispatched to the thread will only be processed if they are accepted by
* the given filter. If the filter is null, then new events are accepted.
* Calls to PushEventQueue may be nested and must each be paired with a call
* to PopEventQueue in order to restore the original state of the thread.
*/
void pushEventQueue(in nsIThreadEventFilter filter);
 
/**
* Revert a call to PushEventQueue. When an event queue is popped, any
* events remaining in the queue are appended to the elder queue.
*/
void popEventQueue();
};

=== nsIThreadObserver ===
[scriptable, uuid(...)]
interface nsIThreadObserver : nsISupports {
/**
* Called when an event is dispatched to the thread. This method
* may be called on any thread.
*/
void onDispatchEvent(in nsIThreadInternal thread,
in unsigned long flags);
 
/**
* Called at the beginning of nsIThread::processNextEvent.
*/
void onEnterProcessNextEvent(in nsIThreadInternal thread);
 
/**
* Called at the end of nsIThread::processNextEvent.
*/
void onLeaveProcessNextEvent(in nsIThreadInternal thread);
};
=== nsIThreadPool ===
[scriptable, uuid(...)]
interface nsIThreadPool : nsIEventTarget
{
/**
* Shutdown the thread pool. This method may not be executed from any
* thread in the thread pool. Instead, it is meant to be executed from
* another thread (usually the thread that created this thread pool).
* When this function returns, the thread pool and all of its threads will
* be shutdown, and it will no longer be possible to dispatch tasks to the
* thread pool.
*/
void shutdown()
 
/**
* Get/set the maximum number of threads allowed at one time in this pool.
*/
attribute unsigned long threadLimit;
 
/**
* Get/set the maximum number of idle threads kept alive.
*/
attribute unsigned long idleThreadLimit;
 
/**
* Get/set the amount of time in milliseconds before an idle thread is
* destroyed.
*/
attribute unsigned long idleThreadTimeout;
};

== C++ Utilities ==

=== Functions ===
nsThreadUtils.h defines the following helper functions:

/**
* Create a new thread.
*
* @param name
* The name of the thread (must be unique) or the empty string to
* create an anonymous thread.
* @param event
* The initial event to run on this thread. This can be null.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_NewThread(const nsACString &name, nsIRunnable *event,
nsIThread **result);
 
/**
* Get a reference to the current thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetCurrentThread(nsIThread **result);
 
/**
* Get a reference to the main thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetMainThread(nsIThread **result);
 
/**
* Get a reference to the thread with the given name.
*
* @param name
* The name of the requested thread. Must be non-empty.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetThread(const nsACString &name, nsIThread **result);
 
/**
* Test to see if the current thread is the main thread.
*
* @returns PR_TRUE if the current thread is the main thread, and PR_FALSE
* otherwise.
*/
PRBool NS_IsMainThread();
 
/**
* Dispatch the given event to the current thread.
*
* @param event
* The event to dispatch.
*/
NS_METHOD NS_DispatchToCurrentThread(nsIRunnable *event);
 
/**
* Dispatch the given event to the main thread.
*
* @param event
* The event to dispatch.
* @param dispatchFlags
* The flags to pass to the main thread's dispatch method.
*/
NS_METHOD NS_DispatchToMainThread(nsIRunnable *event,
PRUint32 dispatchFlags = NS_DISPATCH_NORMAL);
 
/**
* Process all pending events for the given thread before returning. This
* method simply calls ProcessNextEvent on the thread while HasPendingEvents
* continues to return true and the time spent in NS_ProcessPendingEvents
* does not exceed the given timeout value.
*
* @param thread
* The thread object for which to process pending events. If null,
* then events will be processed for the current thread.
* @param timeout
* The maximum number of milliseconds to spend processing pending
* events. Events are not pre-empted to honor this timeout. Rather,
* the timeout value is simply used to determine whether or not to
* process another event. Pass PR_INTERVAL_NO_TIMEOUT to specify no
* timeout.
*/
NS_METHOD NS_ProcessPendingEvents(nsIThread *thread = nsnull,
PRIntervalTime timeout = PR_INTERVAL_NO_TIMEOUT);

=== nsCOMPtr helpers ===
The following nsCOMPtr helpers are defined to simplify things further:

already_AddRefed<nsIThread> do_GetCurrentThread();
 
already_AddRefed<nsIThread> do_GetMainThread();
 
already_AddRefed<nsIThread> do_GetThread(const nsACString &name);

=== nsRunnable ===
The class <code>nsRunnable</code> is also defined to simplify the
implementation of new event types. For example, to define a new
event all you need to do is write code like this:

class MyEvent : public nsRunnable {
public:
MyEvent(... params ...);
 
NS_IMETHOD Run() {
// do stuff
return NS_OK;
}
};

Dispatching <code>MyEvent</code> is then as simple as:

nsCOMPtr<nsIThread> thread = do_GetCurrentThread();
NS_ENSURE_STATE(thread);
 
nsCOMPtr<nsIRunnable> event = new MyEvent();
NS_ENSURE_STATE(event);
 
thread->Dispatch(event, NS_DISPATCH_NORMAL);

== From JS ==

=== Event Dispatch ===
Threads and Thread Manager implement <code>nsIClassInfo</code>:

function MyEvent() {
}
MyEvent.prototype = {
QueryInterface: function(iid) {
if (iid.equals(Components.interfaces.nsIRunnable) ||
iid.equals(Components.interfaces.nsISupports))
return this;
throw Components.results.NS_ERROR_NO_INTERFACE;
},
run: function() {
// do stuff
}
};
 
function DispatchMyEvent() {
var target =
Components.classes["@mozilla.org/thread-manager;1"].
getService().currentThread;
 
target.dispatch(new MyEvent(), target.DISPATCH_NORMAL);
}

== Remarks ==

* Thread priority for native threads can be exposed via <code>nsISupportsPriority</code>.
* Thread names must be unique.
* The Necko I/O thread pool will be replaced by a generic thread pool implementation provided by XPCOM. The thread pool will implement <code>nsIEventTarget</code>, allowing events to be dispatched to any thread in the thread pool. We may even wish to define a <code>nsIThreadPool</code> interface and have it implement that as well. That interface would define methods to adjust the limits on the number of threads in the thread pool and so on.
* We will need an alternative for <code>nsIEventQueue::RevokeEvents</code>. There are several possibilities: (1) make consumers hold references to their nsIRunnable's so they can "disconnect" them manually, or (2) expose an enumeration/visitor API that allows consumers to walk the list of pending tasks and remove arbitrary tasks. I'm not sure what is best yet. The first option or something similar based on weak references is probably best as it avoids the costly O(n) <code>RevokeEvents</code> call.
* The following interfaces/classes would go away or be modified heavily: nsIEventQueue, nsIEventQueueService, nsIEventTarget, nsIThread, PLEvent.
* Issue: Perhaps we should support calling <code>nsIThread::Shutdown</code> from the thread itself. That would probably have to be implemented by posting an event to the main thread, and having that thread call shutdown. However, <code>Shutdown</code> also has the property that it does not return until the thread is gone. That obvious can't happen if <code>Shutdown</code> is called on the thread itself.

=== What about "native" event queues? ===
The main thread where UI events are processed and the socket transport thread will use the observer interface defined by <code>nsIThreadInternal</code>. The main thread will interact with the "native" event system during calls to <code>ProcessNextEvent</code> and <code>Dispatch</code>. Likewise, the socket transport thread will similarly need to poll sockets and perform I/O operations. By observing calls to <code>ProcessNextEvent</code>, observers can wait on a native event queue (or poll on a set of file descriptors) instead of waiting on the thread's internal event queue monitor. When they observe a call to <code>Dispatch</code>, they can use whatever mechanism is appropriate to unblock the thread that is waiting on the native event queue.

=== How do synchronous events work? ===

When <code>Dispatch(event, DISPATCH_SYNC)</code> is called on a <code>nsIEventTarget</code>, it first checks to see if the current thread is the same as the thread where the event would be run. If it is, then it just runs the event directly without queuing it up. However, if not, then it must queue the event to be run when the dispatch target next processes its events. To avoid returning to the caller immediately, the method gets the current thread and calls its <code>ProcessNextEvent</code> method in a loop until it receives acknowledgement that the queued event has been run.

== Development ==

Development is occuring on the THREADS_20060213_BRANCH. See also {{bug|326273}}.

== Comments ==

=== biesi: ===
* What happens if shutdown is called while an event is being processed? I assume that this event will be processed to its end, no further events are accepted, and then the thread is shut down. right?
** What happens to events that were already dispatched to this thread, but not run?
* Is it a good idea to allow other events to run on the current thread while in dispatch?
* Who is expected to call ProcessNextEvent?

==== darin: ====
* When asked to shutdown, a thread would finish dispatching all queued events, and refuse to accept any new events. Once all queued events run to completion, the thread would terminate. This is consistent with how event queues work today.
* If you are sync dispatching, then it is necessary to pump events on the calling thread or else you could end up in a dead-lock situation. For example, if thread A sync dispatches an event to thread B, which cannot complete its job without dispatching an event back to thread A, then the system will dead-lock unless thread A continues to dispatch pending events.
* <code>ProcessNextEvent</code> may be called by anybody that wishes to implement the concept of a "modal event loop." For example, XMLHttpRequest (in sync configuration) would sit in a loop calling <code>ProcessNextEvent</code> while waiting for the underlying HTTP transaction to complete. The key difference between <code>ProcessNextEvent</code> and <code>nsIEventQueue::ProcessPendingEvents</code> is that <code>ProcessNextEvent</code>, when called on the UI thread, will process UI events as well. And, it will also wait (block the thread of execution) if there are no UI events or pending <code>nsIRunnable</code> events.

XPCOM:nsIThreadManager

2006-03-04T00:43:13Z

Darin: /* nsIThreadInternal */

In a world without nested event queues, the concept of a thread and an event queue merge...

== Interfaces ==
=== nsIThreadManager ===
[scriptable, uuid(...)]
interface nsIThreadManager : nsISupports {
/**
* Create a new named thread (a global, user PRThread). If the name is
* non-empty, then the name of the thread must be unique. Specifying an
* empty name results in an anonymous thread that cannot be found later on
* using the getThread method.
*/
nsIThread newThread(in ACString name);
 
/**
* Find a named thread. If no thread exists by the given name, then null
* is returned.
*/
nsIThread getThread(in ACString name);
 
/**
* Get the nsIThread object (if any) corresponding to the given PRThread.
* This method returns null if there is no corresponding nsIThread.
*/
[noscript] nsIThread getThreadFromPRThread(in PRThread thread);
 
/**
* Get the main thread.
*/
readonly attribute nsIThread mainThread;
 
/**
* Get the current thread.
*/
readonly attribute nsIThread currentThread;
 
/**
* This attribute is true if the calling thread is the main thread of the
* application process.
*/
readonly attribute boolean isMainThread;
};

=== nsIEventTarget ===
[scriptable, uuid(...)]
interface nsIEventTarget : nsISupports {
/**
* Dispatch an event to the target. This function may be called from any
* thread. If flags specifies DISPATCH_SYNC, then the dispatch method
* will not return until the event has been processed. NOTE: Calling
* dispatch with DISPATCH_SYNC, may have the side-effect of running other
* events on the current thread while waiting for the given event to run
* to completion. This function is thread-safe and re-entrant.
*/
void dispatch(in nsIRunnable event, in unsigned long flags);
const unsigned long DISPATCH_NORMAL = 0;
const unsigned long DISPATCH_SYNC = 1;
 
/**
* Returns true if events dispatched to this target will run on the
* current thread (i.e., the thread calling this method).
*/
boolean isOnCurrentThread();
};
 
%{C++
// convenient aliases:
#define NS_DISPATCH_NORMAL nsIEventTarget::DISPATCH_NORMAL
#define NS_DISPATCH_SYNC nsIEventTarget::DISPATCH_SYNC
%}

=== nsIThread ===
[scriptable, uuid(...)]
interface nsIThread : nsIEventTarget {
/**
* Returns the name of the thread, which may be empty if this thread is
* anonymous.
*/
readonly attribute ACString name;
 
/**
* Returns the PRThread object corresponding to this nsIThread.
*/
[noscript] PRThread getPRThread();
 
/**
* Shutdown the thread. This method may not be executed from the thread
* itself. Instead, it is meant to be executed from another thread (usually
* the thread that created this thread). When this function returns, the
* thread will be shutdown, and it will no longer be possible to dispatch
* events to the thread.
*/
void shutdown();
 
/**
* Returns true if this thread has one or more pending events.
*/
boolean hasPendingEvents();
 
/**
* Process the next event. If there are no pending events, then this
* method will wait until an event is dispatched to this thread. This
* method is re-entrant but may only be called if this thread is the
* current thread.
*/
void processNextEvent();
};
=== nsIThreadInternal ===
[scriptable, uuid(...)]
interface nsIThreadInternal : nsIThread {
/**
* Get/set an observer for this thread.
*/
attribute nsIThreadObserver observer;
 
/**
* This method causes any events currently enqueued on the thread to be
* suppressed until PopEventQueue is called. Additionally, any new events
* dispatched to the thread will only be processed if they are accepted by
* the given filter. If the filter is null, then new events are accepted.
* Calls to PushEventQueue may be nested and must each be paired with a call
* to PopEventQueue in order to restore the original state of the thread.
*/
void pushEventQueue(in nsIThreadEventFilter filter);
 
/**
* Revert a call to PushEventQueue. When an event queue is popped, any
* events remaining in the queue are appended to the elder queue.
*/
void popEventQueue();
};

=== nsIThreadObserver ===
[scriptable, uuid(...)]
interface nsIThreadObserver : nsISupports {
/**
* Called when an event is dispatched to the thread. This method
* may be called on any thread.
*/
void onDispatchEvent(in nsIThreadInternal thread,
in unsigned long flags);
 
/**
* Called at the beginning of nsIThread::processNextEvent.
*/
void onEnterProcessNextEvent(in nsIThreadInternal thread);
 
/**
* Called at the end of nsIThread::processNextEvent.
*/
void onLeaveProcessNextEvent(in nsIThreadInternal thread);
};
=== nsIThreadPool ===
[scriptable, uuid(...)]
interface nsIThreadPool : nsIEventTarget
{
/**
* Shutdown the thread pool. This method may not be executed from any
* thread in the thread pool. Instead, it is meant to be executed from
* another thread (usually the thread that created this thread pool).
* When this function returns, the thread pool and all of its threads will
* be shutdown, and it will no longer be possible to dispatch tasks to the
* thread pool.
*/
void shutdown()
 
/**
* Get/set the maximum number of threads allowed at one time in this pool.
*/
attribute unsigned long threadLimit;
 
/**
* Get/set the maximum number of idle threads kept alive.
*/
attribute unsigned long idleThreadLimit;
 
/**
* Get/set the amount of time in milliseconds before an idle thread is
* destroyed.
*/
attribute unsigned long idleThreadTimeout;
};

== C++ Utilities ==

=== Functions ===
nsThreadUtils.h defines the following helper functions:

/**
* Create a new thread.
*
* @param name
* The name of the thread (must be unique) or the empty string to
* create an anonymous thread.
* @param event
* The initial event to run on this thread. This can be null.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_NewThread(const nsACString &name, nsIRunnable *event,
nsIThread **result);
 
/**
* Get a reference to the current thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetCurrentThread(nsIThread **result);
 
/**
* Get a reference to the main thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetMainThread(nsIThread **result);
 
/**
* Get a reference to the thread with the given name.
*
* @param name
* The name of the requested thread. Must be non-empty.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetThread(const nsACString &name, nsIThread **result);
 
/**
* Test to see if the current thread is the main thread.
*
* @returns PR_TRUE if the current thread is the main thread, and PR_FALSE
* otherwise.
*/
PRBool NS_IsMainThread();
 
/**
* Dispatch the given event to the current thread.
*
* @param event
* The event to dispatch.
*/
NS_METHOD NS_DispatchToCurrentThread(nsIRunnable *event);
 
/**
* Dispatch the given event to the main thread.
*
* @param event
* The event to dispatch.
* @param dispatchFlags
* The flags to pass to the main thread's dispatch method.
*/
NS_METHOD NS_DispatchToMainThread(nsIRunnable *event,
PRUint32 dispatchFlags = NS_DISPATCH_NORMAL);
 
/**
* Process all pending events for the given thread before returning. This
* method simply calls ProcessNextEvent on the thread while HasPendingEvents
* continues to return true and the time spent in NS_ProcessPendingEvents
* does not exceed the given timeout value.
*
* @param thread
* The thread object for which to process pending events. If null,
* then events will be processed for the current thread.
* @param timeout
* The maximum number of milliseconds to spend processing pending
* events. Events are not pre-empted to honor this timeout. Rather,
* the timeout value is simply used to determine whether or not to
* process another event. Pass PR_INTERVAL_NO_TIMEOUT to specify no
* timeout.
*/
NS_METHOD NS_ProcessPendingEvents(nsIThread *thread = nsnull,
PRIntervalTime timeout = PR_INTERVAL_NO_TIMEOUT);

=== nsCOMPtr helpers ===
The following nsCOMPtr helpers are defined to simplify things further:

already_AddRefed<nsIThread> do_GetCurrentThread();
 
already_AddRefed<nsIThread> do_GetMainThread();
 
already_AddRefed<nsIThread> do_GetThread(const nsACString &name);

=== nsRunnable ===
The class <code>nsRunnable</code> is also defined to simplify the
implementation of new event types. For example, to define a new
event all you need to do is write code like this:

class MyEvent : public nsRunnable {
public:
MyEvent(... params ...);
 
NS_IMETHOD Run() {
// do stuff
return NS_OK;
}
};

Dispatching <code>MyEvent</code> is then as simple as:

nsCOMPtr<nsIThread> thread = do_GetCurrentThread();
NS_ENSURE_STATE(thread);
 
nsCOMPtr<nsIRunnable> event = new MyEvent();
NS_ENSURE_STATE(event);
 
thread->Dispatch(event, NS_DISPATCH_NORMAL);

== From JS ==

=== Event Dispatch ===
Threads and Thread Manager implement <code>nsIClassInfo</code>:

function MyEvent() {
}
MyEvent.prototype = {
QueryInterface: function(iid) {
if (iid.equals(Components.interfaces.nsIRunnable) ||
iid.equals(Components.interfaces.nsISupports))
return this;
throw Components.results.NS_ERROR_NO_INTERFACE;
},
run: function() {
// do stuff
}
};
 
function DispatchMyEvent() {
var target =
Components.classes["@mozilla.org/thread-manager;1"].
getService().currentThread;
 
target.dispatch(new MyEvent(), target.DISPATCH_NORMAL);
}

== Remarks ==

* Thread priority for native threads can be exposed via <code>nsISupportsPriority</code>.
* Thread names must be unique.
* The Necko I/O thread pool will be replaced by a generic thread pool implementation provided by XPCOM. The thread pool will implement <code>nsIEventTarget</code>, allowing events to be dispatched to any thread in the thread pool. We may even wish to define a <code>nsIThreadPool</code> interface and have it implement that as well. That interface would define methods to adjust the limits on the number of threads in the thread pool and so on.
* We will need an alternative for <code>nsIEventQueue::RevokeEvents</code>. There are several possibilities: (1) make consumers hold references to their nsIRunnable's so they can "disconnect" them manually, or (2) expose an enumeration/visitor API that allows consumers to walk the list of pending tasks and remove arbitrary tasks. I'm not sure what is best yet. The first option or something similar based on weak references is probably best as it avoids the costly O(n) <code>RevokeEvents</code> call.
* The following interfaces/classes would go away or be modified heavily: nsIEventQueue, nsIEventQueueService, nsIEventTarget, nsIThread, PLEvent.
* Issue: Perhaps we should support calling <code>nsIThread::Shutdown</code> from the thread itself. That would probably have to be implemented by posting an event to the main thread, and having that thread call shutdown. However, <code>Shutdown</code> also has the property that it does not return until the thread is gone. That obvious can't happen if <code>Shutdown</code> is called on the thread itself.

=== What about "native" event queues? ===
The main thread where UI events are processed and the socket transport thread will use the observer interface defined by <code>nsIThreadInternal</code>. The main thread will interact with the "native" event system during calls to <code>ProcessNextEvent</code> and <code>Dispatch</code>. Likewise, the socket transport thread will similarly need to poll sockets and perform I/O operations. By observing calls to <code>ProcessNextEvent</code>, observers can wait on a native event queue (or poll on a set of file descriptors) instead of waiting on the thread's internal event queue monitor. When they observe a call to <code>Dispatch</code>, they can use whatever mechanism is appropriate to unblock the thread that is waiting on the native event queue.

=== How do synchronous events work? ===

When <code>Dispatch(event, DISPATCH_SYNC)</code> is called on a <code>nsIEventTarget</code>, it first checks to see if the current thread is the same as the thread where the event would be run. If it is, then it just runs the event directly without queuing it up. However, if not, then it must queue the event to be run when the dispatch target next processes its events. To avoid returning to the caller immediately, the method gets the current thread and calls its <code>ProcessNextEvent</code> method in a loop until it receives acknowledgement that the queued event has been run.

== Development ==

Development is occuring on the THREADS_20060213_BRANCH. See also {{bug|326273}}.

== Comments ==

=== biesi: ===
* What happens if shutdown is called while an event is being processed? I assume that this event will be processed to its end, no further events are accepted, and then the thread is shut down. right?
** What happens to events that were already dispatched to this thread, but not run?
* Is it a good idea to allow other events to run on the current thread while in dispatch?
* Who is expected to call ProcessNextEvent?

==== darin: ====
* When asked to shutdown, a thread would finish dispatching all queued events, and refuse to accept any new events. Once all queued events run to completion, the thread would terminate. This is consistent with how event queues work today.
* If you are sync dispatching, then it is necessary to pump events on the calling thread or else you could end up in a dead-lock situation. For example, if thread A sync dispatches an event to thread B, which cannot complete its job without dispatching an event back to thread A, then the system will dead-lock unless thread A continues to dispatch pending events.
* <code>ProcessNextEvent</code> may be called by anybody that wishes to implement the concept of a "modal event loop." For example, XMLHttpRequest (in sync configuration) would sit in a loop calling <code>ProcessNextEvent</code> while waiting for the underlying HTTP transaction to complete. The key difference between <code>ProcessNextEvent</code> and <code>nsIEventQueue::ProcessPendingEvents</code> is that <code>ProcessNextEvent</code>, when called on the UI thread, will process UI events as well. And, it will also wait (block the thread of execution) if there are no UI events or pending <code>nsIRunnable</code> events.

XPCOM:nsIThreadManager

2006-03-04T00:40:41Z

Darin: /* nsIThreadManager */

In a world without nested event queues, the concept of a thread and an event queue merge...

== Interfaces ==
=== nsIThreadManager ===
[scriptable, uuid(...)]
interface nsIThreadManager : nsISupports {
/**
* Create a new named thread (a global, user PRThread). If the name is
* non-empty, then the name of the thread must be unique. Specifying an
* empty name results in an anonymous thread that cannot be found later on
* using the getThread method.
*/
nsIThread newThread(in ACString name);
 
/**
* Find a named thread. If no thread exists by the given name, then null
* is returned.
*/
nsIThread getThread(in ACString name);
 
/**
* Get the nsIThread object (if any) corresponding to the given PRThread.
* This method returns null if there is no corresponding nsIThread.
*/
[noscript] nsIThread getThreadFromPRThread(in PRThread thread);
 
/**
* Get the main thread.
*/
readonly attribute nsIThread mainThread;
 
/**
* Get the current thread.
*/
readonly attribute nsIThread currentThread;
 
/**
* This attribute is true if the calling thread is the main thread of the
* application process.
*/
readonly attribute boolean isMainThread;
};

=== nsIEventTarget ===
[scriptable, uuid(...)]
interface nsIEventTarget : nsISupports {
/**
* Dispatch an event to the target. This function may be called from any
* thread. If flags specifies DISPATCH_SYNC, then the dispatch method
* will not return until the event has been processed. NOTE: Calling
* dispatch with DISPATCH_SYNC, may have the side-effect of running other
* events on the current thread while waiting for the given event to run
* to completion. This function is thread-safe and re-entrant.
*/
void dispatch(in nsIRunnable event, in unsigned long flags);
const unsigned long DISPATCH_NORMAL = 0;
const unsigned long DISPATCH_SYNC = 1;
 
/**
* Returns true if events dispatched to this target will run on the
* current thread (i.e., the thread calling this method).
*/
boolean isOnCurrentThread();
};
 
%{C++
// convenient aliases:
#define NS_DISPATCH_NORMAL nsIEventTarget::DISPATCH_NORMAL
#define NS_DISPATCH_SYNC nsIEventTarget::DISPATCH_SYNC
%}

=== nsIThread ===
[scriptable, uuid(...)]
interface nsIThread : nsIEventTarget {
/**
* Returns the name of the thread, which may be empty if this thread is
* anonymous.
*/
readonly attribute ACString name;
 
/**
* Returns the PRThread object corresponding to this nsIThread.
*/
[noscript] PRThread getPRThread();
 
/**
* Shutdown the thread. This method may not be executed from the thread
* itself. Instead, it is meant to be executed from another thread (usually
* the thread that created this thread). When this function returns, the
* thread will be shutdown, and it will no longer be possible to dispatch
* events to the thread.
*/
void shutdown();
 
/**
* Returns true if this thread has one or more pending events.
*/
boolean hasPendingEvents();
 
/**
* Process the next event. If there are no pending events, then this
* method will wait until an event is dispatched to this thread. This
* method is re-entrant but may only be called if this thread is the
* current thread.
*/
void processNextEvent();
};
=== nsIThreadInternal ===
[scriptable, uuid(...)]
interface nsIThreadInternal : nsIThread {
/**
* Get/set an observer for this thread.
*/
attribute nsIThreadObserver observer;
};
=== nsIThreadObserver ===
[scriptable, uuid(...)]
interface nsIThreadObserver : nsISupports {
/**
* Called when an event is dispatched to the thread. This method
* may be called on any thread.
*/
void onDispatchEvent(in nsIThreadInternal thread,
in unsigned long flags);
 
/**
* Called at the beginning of nsIThread::processNextEvent.
*/
void onEnterProcessNextEvent(in nsIThreadInternal thread);
 
/**
* Called at the end of nsIThread::processNextEvent.
*/
void onLeaveProcessNextEvent(in nsIThreadInternal thread);
};
=== nsIThreadPool ===
[scriptable, uuid(...)]
interface nsIThreadPool : nsIEventTarget
{
/**
* Shutdown the thread pool. This method may not be executed from any
* thread in the thread pool. Instead, it is meant to be executed from
* another thread (usually the thread that created this thread pool).
* When this function returns, the thread pool and all of its threads will
* be shutdown, and it will no longer be possible to dispatch tasks to the
* thread pool.
*/
void shutdown()
 
/**
* Get/set the maximum number of threads allowed at one time in this pool.
*/
attribute unsigned long threadLimit;
 
/**
* Get/set the maximum number of idle threads kept alive.
*/
attribute unsigned long idleThreadLimit;
 
/**
* Get/set the amount of time in milliseconds before an idle thread is
* destroyed.
*/
attribute unsigned long idleThreadTimeout;
};

== C++ Utilities ==

=== Functions ===
nsThreadUtils.h defines the following helper functions:

/**
* Create a new thread.
*
* @param name
* The name of the thread (must be unique) or the empty string to
* create an anonymous thread.
* @param event
* The initial event to run on this thread. This can be null.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_NewThread(const nsACString &name, nsIRunnable *event,
nsIThread **result);
 
/**
* Get a reference to the current thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetCurrentThread(nsIThread **result);
 
/**
* Get a reference to the main thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetMainThread(nsIThread **result);
 
/**
* Get a reference to the thread with the given name.
*
* @param name
* The name of the requested thread. Must be non-empty.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetThread(const nsACString &name, nsIThread **result);
 
/**
* Test to see if the current thread is the main thread.
*
* @returns PR_TRUE if the current thread is the main thread, and PR_FALSE
* otherwise.
*/
PRBool NS_IsMainThread();
 
/**
* Dispatch the given event to the current thread.
*
* @param event
* The event to dispatch.
*/
NS_METHOD NS_DispatchToCurrentThread(nsIRunnable *event);
 
/**
* Dispatch the given event to the main thread.
*
* @param event
* The event to dispatch.
* @param dispatchFlags
* The flags to pass to the main thread's dispatch method.
*/
NS_METHOD NS_DispatchToMainThread(nsIRunnable *event,
PRUint32 dispatchFlags = NS_DISPATCH_NORMAL);
 
/**
* Process all pending events for the given thread before returning. This
* method simply calls ProcessNextEvent on the thread while HasPendingEvents
* continues to return true and the time spent in NS_ProcessPendingEvents
* does not exceed the given timeout value.
*
* @param thread
* The thread object for which to process pending events. If null,
* then events will be processed for the current thread.
* @param timeout
* The maximum number of milliseconds to spend processing pending
* events. Events are not pre-empted to honor this timeout. Rather,
* the timeout value is simply used to determine whether or not to
* process another event. Pass PR_INTERVAL_NO_TIMEOUT to specify no
* timeout.
*/
NS_METHOD NS_ProcessPendingEvents(nsIThread *thread = nsnull,
PRIntervalTime timeout = PR_INTERVAL_NO_TIMEOUT);

=== nsCOMPtr helpers ===
The following nsCOMPtr helpers are defined to simplify things further:

already_AddRefed<nsIThread> do_GetCurrentThread();
 
already_AddRefed<nsIThread> do_GetMainThread();
 
already_AddRefed<nsIThread> do_GetThread(const nsACString &name);

=== nsRunnable ===
The class <code>nsRunnable</code> is also defined to simplify the
implementation of new event types. For example, to define a new
event all you need to do is write code like this:

class MyEvent : public nsRunnable {
public:
MyEvent(... params ...);
 
NS_IMETHOD Run() {
// do stuff
return NS_OK;
}
};

Dispatching <code>MyEvent</code> is then as simple as:

nsCOMPtr<nsIThread> thread = do_GetCurrentThread();
NS_ENSURE_STATE(thread);
 
nsCOMPtr<nsIRunnable> event = new MyEvent();
NS_ENSURE_STATE(event);
 
thread->Dispatch(event, NS_DISPATCH_NORMAL);

== From JS ==

=== Event Dispatch ===
Threads and Thread Manager implement <code>nsIClassInfo</code>:

function MyEvent() {
}
MyEvent.prototype = {
QueryInterface: function(iid) {
if (iid.equals(Components.interfaces.nsIRunnable) ||
iid.equals(Components.interfaces.nsISupports))
return this;
throw Components.results.NS_ERROR_NO_INTERFACE;
},
run: function() {
// do stuff
}
};
 
function DispatchMyEvent() {
var target =
Components.classes["@mozilla.org/thread-manager;1"].
getService().currentThread;
 
target.dispatch(new MyEvent(), target.DISPATCH_NORMAL);
}

== Remarks ==

* Thread priority for native threads can be exposed via <code>nsISupportsPriority</code>.
* Thread names must be unique.
* The Necko I/O thread pool will be replaced by a generic thread pool implementation provided by XPCOM. The thread pool will implement <code>nsIEventTarget</code>, allowing events to be dispatched to any thread in the thread pool. We may even wish to define a <code>nsIThreadPool</code> interface and have it implement that as well. That interface would define methods to adjust the limits on the number of threads in the thread pool and so on.
* We will need an alternative for <code>nsIEventQueue::RevokeEvents</code>. There are several possibilities: (1) make consumers hold references to their nsIRunnable's so they can "disconnect" them manually, or (2) expose an enumeration/visitor API that allows consumers to walk the list of pending tasks and remove arbitrary tasks. I'm not sure what is best yet. The first option or something similar based on weak references is probably best as it avoids the costly O(n) <code>RevokeEvents</code> call.
* The following interfaces/classes would go away or be modified heavily: nsIEventQueue, nsIEventQueueService, nsIEventTarget, nsIThread, PLEvent.
* Issue: Perhaps we should support calling <code>nsIThread::Shutdown</code> from the thread itself. That would probably have to be implemented by posting an event to the main thread, and having that thread call shutdown. However, <code>Shutdown</code> also has the property that it does not return until the thread is gone. That obvious can't happen if <code>Shutdown</code> is called on the thread itself.

=== What about "native" event queues? ===
The main thread where UI events are processed and the socket transport thread will use the observer interface defined by <code>nsIThreadInternal</code>. The main thread will interact with the "native" event system during calls to <code>ProcessNextEvent</code> and <code>Dispatch</code>. Likewise, the socket transport thread will similarly need to poll sockets and perform I/O operations. By observing calls to <code>ProcessNextEvent</code>, observers can wait on a native event queue (or poll on a set of file descriptors) instead of waiting on the thread's internal event queue monitor. When they observe a call to <code>Dispatch</code>, they can use whatever mechanism is appropriate to unblock the thread that is waiting on the native event queue.

=== How do synchronous events work? ===

When <code>Dispatch(event, DISPATCH_SYNC)</code> is called on a <code>nsIEventTarget</code>, it first checks to see if the current thread is the same as the thread where the event would be run. If it is, then it just runs the event directly without queuing it up. However, if not, then it must queue the event to be run when the dispatch target next processes its events. To avoid returning to the caller immediately, the method gets the current thread and calls its <code>ProcessNextEvent</code> method in a loop until it receives acknowledgement that the queued event has been run.

== Development ==

Development is occuring on the THREADS_20060213_BRANCH. See also {{bug|326273}}.

== Comments ==

=== biesi: ===
* What happens if shutdown is called while an event is being processed? I assume that this event will be processed to its end, no further events are accepted, and then the thread is shut down. right?
** What happens to events that were already dispatched to this thread, but not run?
* Is it a good idea to allow other events to run on the current thread while in dispatch?
* Who is expected to call ProcessNextEvent?

==== darin: ====
* When asked to shutdown, a thread would finish dispatching all queued events, and refuse to accept any new events. Once all queued events run to completion, the thread would terminate. This is consistent with how event queues work today.
* If you are sync dispatching, then it is necessary to pump events on the calling thread or else you could end up in a dead-lock situation. For example, if thread A sync dispatches an event to thread B, which cannot complete its job without dispatching an event back to thread A, then the system will dead-lock unless thread A continues to dispatch pending events.
* <code>ProcessNextEvent</code> may be called by anybody that wishes to implement the concept of a "modal event loop." For example, XMLHttpRequest (in sync configuration) would sit in a loop calling <code>ProcessNextEvent</code> while waiting for the underlying HTTP transaction to complete. The key difference between <code>ProcessNextEvent</code> and <code>nsIEventQueue::ProcessPendingEvents</code> is that <code>ProcessNextEvent</code>, when called on the UI thread, will process UI events as well. And, it will also wait (block the thread of execution) if there are no UI events or pending <code>nsIRunnable</code> events.

XPCOM:nsIThreadManager

2006-03-01T19:27:05Z

Darin: /* Functions */

In a world without nested event queues, the concept of a thread and an event queue merge...

== Interfaces ==
=== nsIThreadManager ===
[scriptable, uuid(...)]
interface nsIThreadManager : nsISupports {
/**
* Create a new named thread (a global, user PRThread). If the name is
* non-empty, then the name of the thread must be unique. Specifying an
* empty name results in an anonymous thread that cannot be found later on
* using the getThread method.
*/
nsIThread newThread(in ACString name);
 
/**
* Find a named thread. If no thread exists by the given name, then null
* is returned.
*/
nsIThread getThread(in ACString name);
 
/**
* Get the nsIThread object (if any) corresponding to the given PRThread.
* This method returns null if there is no corresponding nsIThread.
*/
[noscript] nsIThread getThreadFromPRThread(in PRThread thread);
 
/**
* Get the main thread.
*/
readonly attribute nsIThread mainThread;
 
/**
* Get the current thread.
*/
readonly attribute nsIThread currentThread;
 
/**
* This attribute is true if the calling thread is the main thread of the
* application process.
*/
readonly attribute boolean isMainThread;
 
/**
* Set an external nsIThread instance (or null) as the nsIThread for the
* current thread. If a nsIThread is already associated with the calling
* thread, then this function will replace it with the given nsIThread. If
* the given nsIThread is non-null, then its name attribute must be unique.
* Its name may be equal to the name of the nsIThread being replaced. This
* method returns the nsIThread that was replaced by this method call or null
* if there was no previous nsIThread associated with the current thread.
*/
nsIThread setCurrentThread(in nsIThread thread);
};
=== nsIEventTarget ===
[scriptable, uuid(...)]
interface nsIEventTarget : nsISupports {
/**
* Dispatch an event to the target. This function may be called from any
* thread. If flags specifies DISPATCH_SYNC, then the dispatch method
* will not return until the event has been processed. NOTE: Calling
* dispatch with DISPATCH_SYNC, may have the side-effect of running other
* events on the current thread while waiting for the given event to run
* to completion. This function is thread-safe and re-entrant.
*/
void dispatch(in nsIRunnable event, in unsigned long flags);
const unsigned long DISPATCH_NORMAL = 0;
const unsigned long DISPATCH_SYNC = 1;
 
/**
* Returns true if events dispatched to this target will run on the
* current thread (i.e., the thread calling this method).
*/
boolean isOnCurrentThread();
};
 
%{C++
// convenient aliases:
#define NS_DISPATCH_NORMAL nsIEventTarget::DISPATCH_NORMAL
#define NS_DISPATCH_SYNC nsIEventTarget::DISPATCH_SYNC
%}

=== nsIThread ===
[scriptable, uuid(...)]
interface nsIThread : nsIEventTarget {
/**
* Returns the name of the thread, which may be empty if this thread is
* anonymous.
*/
readonly attribute ACString name;
 
/**
* Returns the PRThread object corresponding to this nsIThread.
*/
[noscript] PRThread getPRThread();
 
/**
* Shutdown the thread. This method may not be executed from the thread
* itself. Instead, it is meant to be executed from another thread (usually
* the thread that created this thread). When this function returns, the
* thread will be shutdown, and it will no longer be possible to dispatch
* events to the thread.
*/
void shutdown();
 
/**
* Returns true if this thread has one or more pending events.
*/
boolean hasPendingEvents();
 
/**
* Process the next event. If there are no pending events, then this
* method will wait until an event is dispatched to this thread. This
* method is re-entrant but may only be called if this thread is the
* current thread.
*/
void processNextEvent();
};
=== nsIThreadInternal ===
[scriptable, uuid(...)]
interface nsIThreadInternal : nsIThread {
/**
* Get/set an observer for this thread.
*/
attribute nsIThreadObserver observer;
};
=== nsIThreadObserver ===
[scriptable, uuid(...)]
interface nsIThreadObserver : nsISupports {
/**
* Called when an event is dispatched to the thread. This method
* may be called on any thread.
*/
void onDispatchEvent(in nsIThreadInternal thread,
in unsigned long flags);
 
/**
* Called at the beginning of nsIThread::processNextEvent.
*/
void onEnterProcessNextEvent(in nsIThreadInternal thread);
 
/**
* Called at the end of nsIThread::processNextEvent.
*/
void onLeaveProcessNextEvent(in nsIThreadInternal thread);
};
=== nsIThreadPool ===
[scriptable, uuid(...)]
interface nsIThreadPool : nsIEventTarget
{
/**
* Shutdown the thread pool. This method may not be executed from any
* thread in the thread pool. Instead, it is meant to be executed from
* another thread (usually the thread that created this thread pool).
* When this function returns, the thread pool and all of its threads will
* be shutdown, and it will no longer be possible to dispatch tasks to the
* thread pool.
*/
void shutdown()
 
/**
* Get/set the maximum number of threads allowed at one time in this pool.
*/
attribute unsigned long threadLimit;
 
/**
* Get/set the maximum number of idle threads kept alive.
*/
attribute unsigned long idleThreadLimit;
 
/**
* Get/set the amount of time in milliseconds before an idle thread is
* destroyed.
*/
attribute unsigned long idleThreadTimeout;
};

== C++ Utilities ==

=== Functions ===
nsThreadUtils.h defines the following helper functions:

/**
* Create a new thread.
*
* @param name
* The name of the thread (must be unique) or the empty string to
* create an anonymous thread.
* @param event
* The initial event to run on this thread. This can be null.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_NewThread(const nsACString &name, nsIRunnable *event,
nsIThread **result);
 
/**
* Get a reference to the current thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetCurrentThread(nsIThread **result);
 
/**
* Get a reference to the main thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetMainThread(nsIThread **result);
 
/**
* Get a reference to the thread with the given name.
*
* @param name
* The name of the requested thread. Must be non-empty.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetThread(const nsACString &name, nsIThread **result);
 
/**
* Test to see if the current thread is the main thread.
*
* @returns PR_TRUE if the current thread is the main thread, and PR_FALSE
* otherwise.
*/
PRBool NS_IsMainThread();
 
/**
* Dispatch the given event to the current thread.
*
* @param event
* The event to dispatch.
*/
NS_METHOD NS_DispatchToCurrentThread(nsIRunnable *event);
 
/**
* Dispatch the given event to the main thread.
*
* @param event
* The event to dispatch.
* @param dispatchFlags
* The flags to pass to the main thread's dispatch method.
*/
NS_METHOD NS_DispatchToMainThread(nsIRunnable *event,
PRUint32 dispatchFlags = NS_DISPATCH_NORMAL);
 
/**
* Process all pending events for the given thread before returning. This
* method simply calls ProcessNextEvent on the thread while HasPendingEvents
* continues to return true and the time spent in NS_ProcessPendingEvents
* does not exceed the given timeout value.
*
* @param thread
* The thread object for which to process pending events. If null,
* then events will be processed for the current thread.
* @param timeout
* The maximum number of milliseconds to spend processing pending
* events. Events are not pre-empted to honor this timeout. Rather,
* the timeout value is simply used to determine whether or not to
* process another event. Pass PR_INTERVAL_NO_TIMEOUT to specify no
* timeout.
*/
NS_METHOD NS_ProcessPendingEvents(nsIThread *thread = nsnull,
PRIntervalTime timeout = PR_INTERVAL_NO_TIMEOUT);

=== nsCOMPtr helpers ===
The following nsCOMPtr helpers are defined to simplify things further:

already_AddRefed<nsIThread> do_GetCurrentThread();
 
already_AddRefed<nsIThread> do_GetMainThread();
 
already_AddRefed<nsIThread> do_GetThread(const nsACString &name);

=== nsRunnable ===
The class <code>nsRunnable</code> is also defined to simplify the
implementation of new event types. For example, to define a new
event all you need to do is write code like this:

class MyEvent : public nsRunnable {
public:
MyEvent(... params ...);
 
NS_IMETHOD Run() {
// do stuff
return NS_OK;
}
};

Dispatching <code>MyEvent</code> is then as simple as:

nsCOMPtr<nsIThread> thread = do_GetCurrentThread();
NS_ENSURE_STATE(thread);
 
nsCOMPtr<nsIRunnable> event = new MyEvent();
NS_ENSURE_STATE(event);
 
thread->Dispatch(event, NS_DISPATCH_NORMAL);

== From JS ==

=== Event Dispatch ===
Threads and Thread Manager implement <code>nsIClassInfo</code>:

function MyEvent() {
}
MyEvent.prototype = {
QueryInterface: function(iid) {
if (iid.equals(Components.interfaces.nsIRunnable) ||
iid.equals(Components.interfaces.nsISupports))
return this;
throw Components.results.NS_ERROR_NO_INTERFACE;
},
run: function() {
// do stuff
}
};
 
function DispatchMyEvent() {
var target =
Components.classes["@mozilla.org/thread-manager;1"].
getService().currentThread;
 
target.dispatch(new MyEvent(), target.DISPATCH_NORMAL);
}

== Remarks ==

* Thread priority for native threads can be exposed via <code>nsISupportsPriority</code>.
* Thread names must be unique.
* The Necko I/O thread pool will be replaced by a generic thread pool implementation provided by XPCOM. The thread pool will implement <code>nsIEventTarget</code>, allowing events to be dispatched to any thread in the thread pool. We may even wish to define a <code>nsIThreadPool</code> interface and have it implement that as well. That interface would define methods to adjust the limits on the number of threads in the thread pool and so on.
* We will need an alternative for <code>nsIEventQueue::RevokeEvents</code>. There are several possibilities: (1) make consumers hold references to their nsIRunnable's so they can "disconnect" them manually, or (2) expose an enumeration/visitor API that allows consumers to walk the list of pending tasks and remove arbitrary tasks. I'm not sure what is best yet. The first option or something similar based on weak references is probably best as it avoids the costly O(n) <code>RevokeEvents</code> call.
* The following interfaces/classes would go away or be modified heavily: nsIEventQueue, nsIEventQueueService, nsIEventTarget, nsIThread, PLEvent.
* Issue: Perhaps we should support calling <code>nsIThread::Shutdown</code> from the thread itself. That would probably have to be implemented by posting an event to the main thread, and having that thread call shutdown. However, <code>Shutdown</code> also has the property that it does not return until the thread is gone. That obvious can't happen if <code>Shutdown</code> is called on the thread itself.

=== What about "native" event queues? ===
The main thread where UI events are processed and the socket transport thread will use the observer interface defined by <code>nsIThreadInternal</code>. The main thread will interact with the "native" event system during calls to <code>ProcessNextEvent</code> and <code>Dispatch</code>. Likewise, the socket transport thread will similarly need to poll sockets and perform I/O operations. By observing calls to <code>ProcessNextEvent</code>, observers can wait on a native event queue (or poll on a set of file descriptors) instead of waiting on the thread's internal event queue monitor. When they observe a call to <code>Dispatch</code>, they can use whatever mechanism is appropriate to unblock the thread that is waiting on the native event queue.

=== How do synchronous events work? ===

When <code>Dispatch(event, DISPATCH_SYNC)</code> is called on a <code>nsIEventTarget</code>, it first checks to see if the current thread is the same as the thread where the event would be run. If it is, then it just runs the event directly without queuing it up. However, if not, then it must queue the event to be run when the dispatch target next processes its events. To avoid returning to the caller immediately, the method gets the current thread and calls its <code>ProcessNextEvent</code> method in a loop until it receives acknowledgement that the queued event has been run.

== Development ==

Development is occuring on the THREADS_20060213_BRANCH. See also {{bug|326273}}.

== Comments ==

=== biesi: ===
* What happens if shutdown is called while an event is being processed? I assume that this event will be processed to its end, no further events are accepted, and then the thread is shut down. right?
** What happens to events that were already dispatched to this thread, but not run?
* Is it a good idea to allow other events to run on the current thread while in dispatch?
* Who is expected to call ProcessNextEvent?

==== darin: ====
* When asked to shutdown, a thread would finish dispatching all queued events, and refuse to accept any new events. Once all queued events run to completion, the thread would terminate. This is consistent with how event queues work today.
* If you are sync dispatching, then it is necessary to pump events on the calling thread or else you could end up in a dead-lock situation. For example, if thread A sync dispatches an event to thread B, which cannot complete its job without dispatching an event back to thread A, then the system will dead-lock unless thread A continues to dispatch pending events.
* <code>ProcessNextEvent</code> may be called by anybody that wishes to implement the concept of a "modal event loop." For example, XMLHttpRequest (in sync configuration) would sit in a loop calling <code>ProcessNextEvent</code> while waiting for the underlying HTTP transaction to complete. The key difference between <code>ProcessNextEvent</code> and <code>nsIEventQueue::ProcessPendingEvents</code> is that <code>ProcessNextEvent</code>, when called on the UI thread, will process UI events as well. And, it will also wait (block the thread of execution) if there are no UI events or pending <code>nsIRunnable</code> events.

XPCOM:nsIThreadManager

2006-03-01T19:14:03Z

Darin: /* Functions */

In a world without nested event queues, the concept of a thread and an event queue merge...

== Interfaces ==
=== nsIThreadManager ===
[scriptable, uuid(...)]
interface nsIThreadManager : nsISupports {
/**
* Create a new named thread (a global, user PRThread). If the name is
* non-empty, then the name of the thread must be unique. Specifying an
* empty name results in an anonymous thread that cannot be found later on
* using the getThread method.
*/
nsIThread newThread(in ACString name);
 
/**
* Find a named thread. If no thread exists by the given name, then null
* is returned.
*/
nsIThread getThread(in ACString name);
 
/**
* Get the nsIThread object (if any) corresponding to the given PRThread.
* This method returns null if there is no corresponding nsIThread.
*/
[noscript] nsIThread getThreadFromPRThread(in PRThread thread);
 
/**
* Get the main thread.
*/
readonly attribute nsIThread mainThread;
 
/**
* Get the current thread.
*/
readonly attribute nsIThread currentThread;
 
/**
* This attribute is true if the calling thread is the main thread of the
* application process.
*/
readonly attribute boolean isMainThread;
 
/**
* Set an external nsIThread instance (or null) as the nsIThread for the
* current thread. If a nsIThread is already associated with the calling
* thread, then this function will replace it with the given nsIThread. If
* the given nsIThread is non-null, then its name attribute must be unique.
* Its name may be equal to the name of the nsIThread being replaced. This
* method returns the nsIThread that was replaced by this method call or null
* if there was no previous nsIThread associated with the current thread.
*/
nsIThread setCurrentThread(in nsIThread thread);
};
=== nsIEventTarget ===
[scriptable, uuid(...)]
interface nsIEventTarget : nsISupports {
/**
* Dispatch an event to the target. This function may be called from any
* thread. If flags specifies DISPATCH_SYNC, then the dispatch method
* will not return until the event has been processed. NOTE: Calling
* dispatch with DISPATCH_SYNC, may have the side-effect of running other
* events on the current thread while waiting for the given event to run
* to completion. This function is thread-safe and re-entrant.
*/
void dispatch(in nsIRunnable event, in unsigned long flags);
const unsigned long DISPATCH_NORMAL = 0;
const unsigned long DISPATCH_SYNC = 1;
 
/**
* Returns true if events dispatched to this target will run on the
* current thread (i.e., the thread calling this method).
*/
boolean isOnCurrentThread();
};
 
%{C++
// convenient aliases:
#define NS_DISPATCH_NORMAL nsIEventTarget::DISPATCH_NORMAL
#define NS_DISPATCH_SYNC nsIEventTarget::DISPATCH_SYNC
%}

=== nsIThread ===
[scriptable, uuid(...)]
interface nsIThread : nsIEventTarget {
/**
* Returns the name of the thread, which may be empty if this thread is
* anonymous.
*/
readonly attribute ACString name;
 
/**
* Returns the PRThread object corresponding to this nsIThread.
*/
[noscript] PRThread getPRThread();
 
/**
* Shutdown the thread. This method may not be executed from the thread
* itself. Instead, it is meant to be executed from another thread (usually
* the thread that created this thread). When this function returns, the
* thread will be shutdown, and it will no longer be possible to dispatch
* events to the thread.
*/
void shutdown();
 
/**
* Returns true if this thread has one or more pending events.
*/
boolean hasPendingEvents();
 
/**
* Process the next event. If there are no pending events, then this
* method will wait until an event is dispatched to this thread. This
* method is re-entrant but may only be called if this thread is the
* current thread.
*/
void processNextEvent();
};
=== nsIThreadInternal ===
[scriptable, uuid(...)]
interface nsIThreadInternal : nsIThread {
/**
* Get/set an observer for this thread.
*/
attribute nsIThreadObserver observer;
};
=== nsIThreadObserver ===
[scriptable, uuid(...)]
interface nsIThreadObserver : nsISupports {
/**
* Called when an event is dispatched to the thread. This method
* may be called on any thread.
*/
void onDispatchEvent(in nsIThreadInternal thread,
in unsigned long flags);
 
/**
* Called at the beginning of nsIThread::processNextEvent.
*/
void onEnterProcessNextEvent(in nsIThreadInternal thread);
 
/**
* Called at the end of nsIThread::processNextEvent.
*/
void onLeaveProcessNextEvent(in nsIThreadInternal thread);
};
=== nsIThreadPool ===
[scriptable, uuid(...)]
interface nsIThreadPool : nsIEventTarget
{
/**
* Shutdown the thread pool. This method may not be executed from any
* thread in the thread pool. Instead, it is meant to be executed from
* another thread (usually the thread that created this thread pool).
* When this function returns, the thread pool and all of its threads will
* be shutdown, and it will no longer be possible to dispatch tasks to the
* thread pool.
*/
void shutdown()
 
/**
* Get/set the maximum number of threads allowed at one time in this pool.
*/
attribute unsigned long threadLimit;
 
/**
* Get/set the maximum number of idle threads kept alive.
*/
attribute unsigned long idleThreadLimit;
 
/**
* Get/set the amount of time in milliseconds before an idle thread is
* destroyed.
*/
attribute unsigned long idleThreadTimeout;
};

== C++ Utilities ==

=== Functions ===
nsThreadUtils.h defines the following helper functions:

/**
* Create a new thread.
*
* @param name
* The name of the thread (must be unique) or the empty string to
* create an anonymous thread.
* @param event
* The initial event to run on this thread. This can be null.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_NewThread(const nsACString &name, nsIRunnable *event,
nsIThread **result);
 
/**
* Get a reference to the current thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetCurrentThread(nsIThread **result);
 
/**
* Get a reference to the main thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetMainThread(nsIThread **result);
 
/**
* Get a reference to the thread with the given name.
*
* @param name
* The name of the requested thread. Must be non-empty.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetThread(const nsACString &name, nsIThread **result);
 
/**
* Test to see if the current thread is the main thread.
*
* @returns PR_TRUE if the current thread is the main thread, and PR_FALSE
* otherwise.
*/
PRBool NS_IsMainThread();
 
/**
* Dispatch the given event to the current thread.
*
* @param event
* The event to dispatch.
*/
NS_METHOD NS_DispatchToCurrentThread(nsIRunnable *event);
 
/**
* Dispatch the given event to the main thread.
*
* @param event
* The event to dispatch.
* @param dispatchFlags
* The flags to pass to the main thread's dispatch method.
*/
NS_METHOD NS_DispatchToMainThread(nsIRunnable *event,
PRUint32 dispatchFlags = NS_DISPATCH_NORMAL);

 
/**
* Process all pending events for the given thread before returning. This
* method simply calls ProcessNextEvent on the thread while HasPendingEvents
* continues to return true and the time spent in NS_ProcessPendingEvents
* does not exceed the given timeout value.
*
* @param thread
* The thread object for which to process pending events. If null,
* then events will be processed for the current thread.
* @param timeout
* The maximum number of milliseconds to spend processing pending
* events. Events are not pre-empted to honor this timeout. Rather,
* the timeout value is simply used to determine whether or not to
* process another event. Pass PR_INTERVAL_NO_TIMEOUT to specify no
* timeout.
*/
NS_METHOD NS_ProcessPendingEvents(nsIThread *thread = nsnull,
PRIntervalTime timeout = PR_INTERVAL_NO_TIMEOUT);

=== nsCOMPtr helpers ===
The following nsCOMPtr helpers are defined to simplify things further:

already_AddRefed<nsIThread> do_GetCurrentThread();
 
already_AddRefed<nsIThread> do_GetMainThread();
 
already_AddRefed<nsIThread> do_GetThread(const nsACString &name);

=== nsRunnable ===
The class <code>nsRunnable</code> is also defined to simplify the
implementation of new event types. For example, to define a new
event all you need to do is write code like this:

class MyEvent : public nsRunnable {
public:
MyEvent(... params ...);
 
NS_IMETHOD Run() {
// do stuff
return NS_OK;
}
};

Dispatching <code>MyEvent</code> is then as simple as:

nsCOMPtr<nsIThread> thread = do_GetCurrentThread();
NS_ENSURE_STATE(thread);
 
nsCOMPtr<nsIRunnable> event = new MyEvent();
NS_ENSURE_STATE(event);
 
thread->Dispatch(event, NS_DISPATCH_NORMAL);

== From JS ==

=== Event Dispatch ===
Threads and Thread Manager implement <code>nsIClassInfo</code>:

function MyEvent() {
}
MyEvent.prototype = {
QueryInterface: function(iid) {
if (iid.equals(Components.interfaces.nsIRunnable) ||
iid.equals(Components.interfaces.nsISupports))
return this;
throw Components.results.NS_ERROR_NO_INTERFACE;
},
run: function() {
// do stuff
}
};
 
function DispatchMyEvent() {
var target =
Components.classes["@mozilla.org/thread-manager;1"].
getService().currentThread;
 
target.dispatch(new MyEvent(), target.DISPATCH_NORMAL);
}

== Remarks ==

* Thread priority for native threads can be exposed via <code>nsISupportsPriority</code>.
* Thread names must be unique.
* The Necko I/O thread pool will be replaced by a generic thread pool implementation provided by XPCOM. The thread pool will implement <code>nsIEventTarget</code>, allowing events to be dispatched to any thread in the thread pool. We may even wish to define a <code>nsIThreadPool</code> interface and have it implement that as well. That interface would define methods to adjust the limits on the number of threads in the thread pool and so on.
* We will need an alternative for <code>nsIEventQueue::RevokeEvents</code>. There are several possibilities: (1) make consumers hold references to their nsIRunnable's so they can "disconnect" them manually, or (2) expose an enumeration/visitor API that allows consumers to walk the list of pending tasks and remove arbitrary tasks. I'm not sure what is best yet. The first option or something similar based on weak references is probably best as it avoids the costly O(n) <code>RevokeEvents</code> call.
* The following interfaces/classes would go away or be modified heavily: nsIEventQueue, nsIEventQueueService, nsIEventTarget, nsIThread, PLEvent.
* Issue: Perhaps we should support calling <code>nsIThread::Shutdown</code> from the thread itself. That would probably have to be implemented by posting an event to the main thread, and having that thread call shutdown. However, <code>Shutdown</code> also has the property that it does not return until the thread is gone. That obvious can't happen if <code>Shutdown</code> is called on the thread itself.

=== What about "native" event queues? ===
The main thread where UI events are processed and the socket transport thread will use the observer interface defined by <code>nsIThreadInternal</code>. The main thread will interact with the "native" event system during calls to <code>ProcessNextEvent</code> and <code>Dispatch</code>. Likewise, the socket transport thread will similarly need to poll sockets and perform I/O operations. By observing calls to <code>ProcessNextEvent</code>, observers can wait on a native event queue (or poll on a set of file descriptors) instead of waiting on the thread's internal event queue monitor. When they observe a call to <code>Dispatch</code>, they can use whatever mechanism is appropriate to unblock the thread that is waiting on the native event queue.

=== How do synchronous events work? ===

When <code>Dispatch(event, DISPATCH_SYNC)</code> is called on a <code>nsIEventTarget</code>, it first checks to see if the current thread is the same as the thread where the event would be run. If it is, then it just runs the event directly without queuing it up. However, if not, then it must queue the event to be run when the dispatch target next processes its events. To avoid returning to the caller immediately, the method gets the current thread and calls its <code>ProcessNextEvent</code> method in a loop until it receives acknowledgement that the queued event has been run.

== Development ==

Development is occuring on the THREADS_20060213_BRANCH. See also {{bug|326273}}.

== Comments ==

=== biesi: ===
* What happens if shutdown is called while an event is being processed? I assume that this event will be processed to its end, no further events are accepted, and then the thread is shut down. right?
** What happens to events that were already dispatched to this thread, but not run?
* Is it a good idea to allow other events to run on the current thread while in dispatch?
* Who is expected to call ProcessNextEvent?

==== darin: ====
* When asked to shutdown, a thread would finish dispatching all queued events, and refuse to accept any new events. Once all queued events run to completion, the thread would terminate. This is consistent with how event queues work today.
* If you are sync dispatching, then it is necessary to pump events on the calling thread or else you could end up in a dead-lock situation. For example, if thread A sync dispatches an event to thread B, which cannot complete its job without dispatching an event back to thread A, then the system will dead-lock unless thread A continues to dispatch pending events.
* <code>ProcessNextEvent</code> may be called by anybody that wishes to implement the concept of a "modal event loop." For example, XMLHttpRequest (in sync configuration) would sit in a loop calling <code>ProcessNextEvent</code> while waiting for the underlying HTTP transaction to complete. The key difference between <code>ProcessNextEvent</code> and <code>nsIEventQueue::ProcessPendingEvents</code> is that <code>ProcessNextEvent</code>, when called on the UI thread, will process UI events as well. And, it will also wait (block the thread of execution) if there are no UI events or pending <code>nsIRunnable</code> events.

XPCOM:nsIThreadManager

2006-03-01T19:04:07Z

Darin: /* Functions */

In a world without nested event queues, the concept of a thread and an event queue merge...

== Interfaces ==
=== nsIThreadManager ===
[scriptable, uuid(...)]
interface nsIThreadManager : nsISupports {
/**
* Create a new named thread (a global, user PRThread). If the name is
* non-empty, then the name of the thread must be unique. Specifying an
* empty name results in an anonymous thread that cannot be found later on
* using the getThread method.
*/
nsIThread newThread(in ACString name);
 
/**
* Find a named thread. If no thread exists by the given name, then null
* is returned.
*/
nsIThread getThread(in ACString name);
 
/**
* Get the nsIThread object (if any) corresponding to the given PRThread.
* This method returns null if there is no corresponding nsIThread.
*/
[noscript] nsIThread getThreadFromPRThread(in PRThread thread);
 
/**
* Get the main thread.
*/
readonly attribute nsIThread mainThread;
 
/**
* Get the current thread.
*/
readonly attribute nsIThread currentThread;
 
/**
* This attribute is true if the calling thread is the main thread of the
* application process.
*/
readonly attribute boolean isMainThread;
 
/**
* Set an external nsIThread instance (or null) as the nsIThread for the
* current thread. If a nsIThread is already associated with the calling
* thread, then this function will replace it with the given nsIThread. If
* the given nsIThread is non-null, then its name attribute must be unique.
* Its name may be equal to the name of the nsIThread being replaced. This
* method returns the nsIThread that was replaced by this method call or null
* if there was no previous nsIThread associated with the current thread.
*/
nsIThread setCurrentThread(in nsIThread thread);
};
=== nsIEventTarget ===
[scriptable, uuid(...)]
interface nsIEventTarget : nsISupports {
/**
* Dispatch an event to the target. This function may be called from any
* thread. If flags specifies DISPATCH_SYNC, then the dispatch method
* will not return until the event has been processed. NOTE: Calling
* dispatch with DISPATCH_SYNC, may have the side-effect of running other
* events on the current thread while waiting for the given event to run
* to completion. This function is thread-safe and re-entrant.
*/
void dispatch(in nsIRunnable event, in unsigned long flags);
const unsigned long DISPATCH_NORMAL = 0;
const unsigned long DISPATCH_SYNC = 1;
 
/**
* Returns true if events dispatched to this target will run on the
* current thread (i.e., the thread calling this method).
*/
boolean isOnCurrentThread();
};
 
%{C++
// convenient aliases:
#define NS_DISPATCH_NORMAL nsIEventTarget::DISPATCH_NORMAL
#define NS_DISPATCH_SYNC nsIEventTarget::DISPATCH_SYNC
%}

=== nsIThread ===
[scriptable, uuid(...)]
interface nsIThread : nsIEventTarget {
/**
* Returns the name of the thread, which may be empty if this thread is
* anonymous.
*/
readonly attribute ACString name;
 
/**
* Returns the PRThread object corresponding to this nsIThread.
*/
[noscript] PRThread getPRThread();
 
/**
* Shutdown the thread. This method may not be executed from the thread
* itself. Instead, it is meant to be executed from another thread (usually
* the thread that created this thread). When this function returns, the
* thread will be shutdown, and it will no longer be possible to dispatch
* events to the thread.
*/
void shutdown();
 
/**
* Returns true if this thread has one or more pending events.
*/
boolean hasPendingEvents();
 
/**
* Process the next event. If there are no pending events, then this
* method will wait until an event is dispatched to this thread. This
* method is re-entrant but may only be called if this thread is the
* current thread.
*/
void processNextEvent();
};
=== nsIThreadInternal ===
[scriptable, uuid(...)]
interface nsIThreadInternal : nsIThread {
/**
* Get/set an observer for this thread.
*/
attribute nsIThreadObserver observer;
};
=== nsIThreadObserver ===
[scriptable, uuid(...)]
interface nsIThreadObserver : nsISupports {
/**
* Called when an event is dispatched to the thread. This method
* may be called on any thread.
*/
void onDispatchEvent(in nsIThreadInternal thread,
in unsigned long flags);
 
/**
* Called at the beginning of nsIThread::processNextEvent.
*/
void onEnterProcessNextEvent(in nsIThreadInternal thread);
 
/**
* Called at the end of nsIThread::processNextEvent.
*/
void onLeaveProcessNextEvent(in nsIThreadInternal thread);
};
=== nsIThreadPool ===
[scriptable, uuid(...)]
interface nsIThreadPool : nsIEventTarget
{
/**
* Shutdown the thread pool. This method may not be executed from any
* thread in the thread pool. Instead, it is meant to be executed from
* another thread (usually the thread that created this thread pool).
* When this function returns, the thread pool and all of its threads will
* be shutdown, and it will no longer be possible to dispatch tasks to the
* thread pool.
*/
void shutdown()
 
/**
* Get/set the maximum number of threads allowed at one time in this pool.
*/
attribute unsigned long threadLimit;
 
/**
* Get/set the maximum number of idle threads kept alive.
*/
attribute unsigned long idleThreadLimit;
 
/**
* Get/set the amount of time in milliseconds before an idle thread is
* destroyed.
*/
attribute unsigned long idleThreadTimeout;
};

== C++ Utilities ==

=== Functions ===
nsThreadUtils.h defines the following helper functions:

/**
* Create a new thread.
*
* @param name
* The name of the thread (must be unique) or the empty string to
* create an anonymous thread.
* @param event
* The initial event to run on this thread. This can be null.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_NewThread(const nsACString &name, nsIRunnable *event,
nsIThread **result);
 
/**
* Get a reference to the current thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetCurrentThread(nsIThread **result);
 
/**
* Get a reference to the main thread.
*
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetMainThread(nsIThread **result);
 
/**
* Get a reference to the thread with the given name.
*
* @param name
* The name of the requested thread. Must be non-empty.
* @param result
* The resulting nsIThread object.
*/
NS_METHOD NS_GetThread(const nsACString &name, nsIThread **result);
 
/**
* Test to see if the current thread is the main thread.
*
* @returns PR_TRUE if the current thread is the main thread, and PR_FALSE
* otherwise.
*/
PRBool NS_IsMainThread();
 
/**
* Dispatch the given event to the current thread.
*
* @param event
* The event to dispatch.
*/
NS_METHOD NS_DispatchToCurrentThread(nsIRunnable *event);
 
/**
* Dispatch the given event to the main thread.
*
* @param event
* The event to dispatch.
* @param dispatchFlags
* The flags to pass to the main thread's dispatch method.
*/
NS_METHOD NS_DispatchToMainThread(nsIRunnable *event,
PRUint32 dispatchFlags = NS_DISPATCH_NORMAL);

=== nsCOMPtr helpers ===
The following nsCOMPtr helpers are defined to simplify things further:

already_AddRefed<nsIThread> do_GetCurrentThread();
 
already_AddRefed<nsIThread> do_GetMainThread();
 
already_AddRefed<nsIThread> do_GetThread(const nsACString &name);

=== nsRunnable ===
The class <code>nsRunnable</code> is also defined to simplify the
implementation of new event types. For example, to define a new
event all you need to do is write code like this:

class MyEvent : public nsRunnable {
public:
MyEvent(... params ...);
 
NS_IMETHOD Run() {
// do stuff
return NS_OK;
}
};

Dispatching <code>MyEvent</code> is then as simple as:

nsCOMPtr<nsIThread> thread = do_GetCurrentThread();
NS_ENSURE_STATE(thread);
 
nsCOMPtr<nsIRunnable> event = new MyEvent();
NS_ENSURE_STATE(event);
 
thread->Dispatch(event, NS_DISPATCH_NORMAL);

== From JS ==

=== Event Dispatch ===
Threads and Thread Manager implement <code>nsIClassInfo</code>:

function MyEvent() {
}
MyEvent.prototype = {
QueryInterface: function(iid) {
if (iid.equals(Components.interfaces.nsIRunnable) ||
iid.equals(Components.interfaces.nsISupports))
return this;
throw Components.results.NS_ERROR_NO_INTERFACE;
},
run: function() {
// do stuff
}
};
 
function DispatchMyEvent() {
var target =
Components.classes["@mozilla.org/thread-manager;1"].
getService().currentThread;
 
target.dispatch(new MyEvent(), target.DISPATCH_NORMAL);
}

== Remarks ==

* Thread priority for native threads can be exposed via <code>nsISupportsPriority</code>.
* Thread names must be unique.
* The Necko I/O thread pool will be replaced by a generic thread pool implementation provided by XPCOM. The thread pool will implement <code>nsIEventTarget</code>, allowing events to be dispatched to any thread in the thread pool. We may even wish to define a <code>nsIThreadPool</code> interface and have it implement that as well. That interface would define methods to adjust the limits on the number of threads in the thread pool and so on.
* We will need an alternative for <code>nsIEventQueue::RevokeEvents</code>. There are several possibilities: (1) make consumers hold references to their nsIRunnable's so they can "disconnect" them manually, or (2) expose an enumeration/visitor API that allows consumers to walk the list of pending tasks and remove arbitrary tasks. I'm not sure what is best yet. The first option or something similar based on weak references is probably best as it avoids the costly O(n) <code>RevokeEvents</code> call.
* The following interfaces/classes would go away or be modified heavily: nsIEventQueue, nsIEventQueueService, nsIEventTarget, nsIThread, PLEvent.
* Issue: Perhaps we should support calling <code>nsIThread::Shutdown</code> from the thread itself. That would probably have to be implemented by posting an event to the main thread, and having that thread call shutdown. However, <code>Shutdown</code> also has the property that it does not return until the thread is gone. That obvious can't happen if <code>Shutdown</code> is called on the thread itself.

=== What about "native" event queues? ===
The main thread where UI events are processed and the socket transport thread will use the observer interface defined by <code>nsIThreadInternal</code>. The main thread will interact with the "native" event system during calls to <code>ProcessNextEvent</code> and <code>Dispatch</code>. Likewise, the socket transport thread will similarly need to poll sockets and perform I/O operations. By observing calls to <code>ProcessNextEvent</code>, observers can wait on a native event queue (or poll on a set of file descriptors) instead of waiting on the thread's internal event queue monitor. When they observe a call to <code>Dispatch</code>, they can use whatever mechanism is appropriate to unblock the thread that is waiting on the native event queue.

=== How do synchronous events work? ===

When <code>Dispatch(event, DISPATCH_SYNC)</code> is called on a <code>nsIEventTarget</code>, it first checks to see if the current thread is the same as the thread where the event would be run. If it is, then it just runs the event directly without queuing it up. However, if not, then it must queue the event to be run when the dispatch target next processes its events. To avoid returning to the caller immediately, the method gets the current thread and calls its <code>ProcessNextEvent</code> method in a loop until it receives acknowledgement that the queued event has been run.

== Development ==

Development is occuring on the THREADS_20060213_BRANCH. See also {{bug|326273}}.

== Comments ==

=== biesi: ===
* What happens if shutdown is called while an event is being processed? I assume that this event will be processed to its end, no further events are accepted, and then the thread is shut down. right?
** What happens to events that were already dispatched to this thread, but not run?
* Is it a good idea to allow other events to run on the current thread while in dispatch?
* Who is expected to call ProcessNextEvent?

==== darin: ====
* When asked to shutdown, a thread would finish dispatching all queued events, and refuse to accept any new events. Once all queued events run to completion, the thread would terminate. This is consistent with how event queues work today.
* If you are sync dispatching, then it is necessary to pump events on the calling thread or else you could end up in a dead-lock situation. For example, if thread A sync dispatches an event to thread B, which cannot complete its job without dispatching an event back to thread A, then the system will dead-lock unless thread A continues to dispatch pending events.
* <code>ProcessNextEvent</code> may be called by anybody that wishes to implement the concept of a "modal event loop." For example, XMLHttpRequest (in sync configuration) would sit in a loop calling <code>ProcessNextEvent</code> while waiting for the underlying HTTP transaction to complete. The key difference between <code>ProcessNextEvent</code> and <code>nsIEventQueue::ProcessPendingEvents</code> is that <code>ProcessNextEvent</code>, when called on the UI thread, will process UI events as well. And, it will also wait (block the thread of execution) if there are no UI events or pending <code>nsIRunnable</code> events.

XPCOM:nsIThreadManager

2006-03-01T19:01:31Z

Darin: /* Functions */

Firefox2/StatusMeetings/2006-02-28

2006-03-01T04:51:32Z

Darin: /* Features */

[[Firefox2/StatusMeetings/2006-02-21|<< previous week]] | [[Firefox2/StatusMeetings|index]] | [[Firefox2/StatusMeetings/2006-03-07|next week>>]]

= In Attendance =
brettw, linus, annie, darin, ben, jhughes, brakowski, timr, rob_strong, dveditz, rebron, Axel, gavin_, autonome, bsmedberg, markp, mconnor

= Agenda =
# Alpha 1 Status
# Firefox 2 Feature Status Roundtable
# Any other business

= Alpha 1 Status =
== Features ==
* '''Places infrastructure (performance, stability, toolbar drag & drop)'''
** performance (Tp, Ts) has gotten better, close to status quo if not better
** problems with memory leak on balsa that we're trying to track down; this is blocking us as we can't turn it on. We're not sure that this is even Places that's doing it.
*** dveditz: the whole point of "WARN_IF_FALSE" was to warn instead of fail on an assertion.
*** darin: I'm gonna rack that up to maybe a typo in nsDebug.h?
*** ben: maybe we can flip places on?
*** beltzner: will post to devnews tonight, then flip it on for Weds morning

* '''Undo Close Tab'''
** at a hard decision about what approach to take
*** either hide-the-tab, try to leverage bfcache, or just try to preserve form data retention
** will be able to get it ready for A1 based on one of these directions, assuming we still want to
*** beltzner: I think we should get at least one of these directions in place
** darin: why would we use bfcache?
** bsmedberg: it might help persist full state while not allowing plugins and media to run in the background (which would happen with hide-the-tab)
** darin: need to be careful about <code>onunload</code> handlers and other things that disable bfcache
** mconnor: if I can't figure out a way to make it work consistently, we might want to push this off to A2 or even extension-land

* '''Tab Overflow'''
**

* '''Extension Blacklisting'''
** patch waiting for review

* '''Extension Dependencies'''
** landed, no regressions

* '''Search Plugin Format Changeover (with sherlock import)'''
** review going well, working through Ben's comments
** not going to move to toolkit based on feedback in d-a-f
** looking to have a new patch for review soon (today/tomorrow)

* '''Spell-As-You-Type (english only)'''
** it's on trunk already (without the dictionary) --enable-extension: spellcheck? there are instructions in the enable spell check bug
** still blocked on licensing, who do I talk to about this? mscott for starters.
** ben: where does the dictionary file? what needs to happen with the build system to get it included?
** bsmedberg: point me to that please and we can get this started

* '''Instrumentation Infrastructure'''
** good progress on getting server infrastructure up and running
** should move this off to A2
** the exit survey will be in place for Firefox 1.5.0.2, morgamic is doing the final bits of work for the web app
*** also thinking about entrance survey
*** action '''beltzner''' cc darin on bug 314119

* '''RSS parser'''
** ben needs to check in with robert, think it's stuck waiting for a review

* '''RSS content detection (?)'''
** we ''think'' we're good here; not in darin's review queue anymore, at any rate

== Blockers ==
* version number / branding
** currently set at 1.5, should it be 2.0a1?
** benjamin: yes, that's what mscott's doing
** dveditz: should we also change the trunk, which is currently 1.6a1?
** benjamin: mscott has all of these under proposal
** '''action''' beltzner to take this as an action
* davel: when we push 2.0a1 to the beta-update channel, will these users get a choice?
** darin: yes, if we set something as a "major" release, they'll get a choice
** bsmedberg: it would be a good idea to test this code path on the nightly?
** annie: I think there's a lot of users who don't realize that they're on a beta channel right now, so we shouldn't be pushing the alpha onto the 1.5 beta channel
** '''action''' for darin to synch up with preed(?) to make sure that everyone's up to speed
** '''action''' for QA to test the 1.5.x update logic for user choice
* ben: release notes? documentation for MDC?
** promote it as a developer release
** mconnor: do we even want to promote it as that? some of these APIs are going to change?
** beltzner: but we want that feedback, don't we?
** mconnor: I'm worried about getting dugg, and getting bug feedback that we don't really care about anyway
** ben: maybe do it invite only?
** mconnor: get the release download numbers from Asa

= Status Updates =
== Places ==
* performance was good, no known data corruption issues
* annie's prepared some solid estimates, I need to do that and get it from the rest of the team
* '''action''' ben to meet with schrep next monday

== Tabbed Browsing ==
* nothing beyond what's been discussed

== Extension Manager Enhancements ==
* Extension Dependencies - phase 1 landed - no regressions so far
* Extension Blacklisting - patch ready for review last Friday
* Extension Locales - started
* Extension UI - mockups and proof of concept started

== Installer ==
* Windows Installer - nothing new other than work on this will start again this week
** bsmedberg: is DOM Inspector part of the product or not?
** first requirement is to be able to provide variable paths for distribution and packaging of our installer
** now we're starting to talk about creating various levels of stub install: stub with full code, stub with all code but not optional code, stub with no code.
*** bsmedberg: but do we consider DOM inspector part of the application or not?
*** rob_strong: put it on AMO?
*** beltzner: we need to figure out a way to make sure that it's there for users who need it, but not there for users who aren't there
* Branding and Locale installer customization - nothing new

== Search Engine UI ==
*Back end work complete
*Updated patch today or tomorrow - needs review from mconnor
**Addressed ben's SR comments
*Code to remain in /browser per discussion on dev.apps.firefox
*Re-factoring of the Sherlock parsing code to be completed seperately if time permits (low priority)
*Need to discuss search plugin format further

== Visual/UI Refresh ==
* requirements for the visual refresh are [[FX2_Visual_Update|on the wiki]]
** will be creating a new space for discussion of this theme (dev.apps.firefox.newtheme) and trying to figure out some place to provide hosting for mockups and images
* met with ben and jhughes yesterday to discuss changes to the default chrome for the browser window, the outcome of which was posted to [http://groups.google.com/group/mozilla.dev.apps.firefox dev.apps.firefox]

== Platform Uplift ==

* SVG textPath needs to get an answer and attention in the next 2 weeks, thus I make a commitment here that I will produce a landing scenario for them by March 10.

* no new status on UTF-16 XPCOM I/O fixes.

* schedule for platform uplift deadlines no longer clear due to schedule strategy shift; will try to build something new there for next week.

* need to produce a plan for tracking 1.8.1 approval queues and setting expectations there appropriately.

== Inline Spell Check ==
Waiting for clarification on licensing.

== Instrumentation / Exit Surveys ==
* Mostly working on server backend. Not much new status to report.
* {{bug|189570}} is fixed on the trunk.

== Session Saver ==
* SessionStore service mostly working in Bon Echo
* Currently pulling from cache or reloading, not dump/restoring DOM
* This week: define and document API, finish code review and post patch

== Branding & Update Systems ==
* nothing new here

== RSS ==
* need to check in with robert sayre

== Offline mode / better use of cache ==
* patch is in, waiting for branch approval
* continuing to investigate low hanging fruit

== Anti-Phishing ==
* fritz, darin, neils, mmc and brakowski meeting this afternoon to talk about ways of bundling/integrating Google phishing protector
* also investigating heuristic-based approaches and UI rendering for warnings about phishing

== EULA ==
* nothing new here

== Performance ==
* schrep's out of town, but is still planning to kick off a meeting on collecting better performance data on daily builds to continually monitor this issue

= Other Business =
* annie: maybe use Google's QA to help us here
** '''action''' annie and timr to talk about this

Firefox2/StatusMeetings/2006-02-28

2006-03-01T04:51:07Z

Darin: /* Features */

[[Firefox2/StatusMeetings/2006-02-21|<< previous week]] | [[Firefox2/StatusMeetings|index]] | [[Firefox2/StatusMeetings/2006-03-07|next week>>]]

= In Attendance =
brettw, linus, annie, darin, ben, jhughes, brakowski, timr, rob_strong, dveditz, rebron, Axel, gavin_, autonome, bsmedberg, markp, mconnor

= Agenda =
# Alpha 1 Status
# Firefox 2 Feature Status Roundtable
# Any other business

= Alpha 1 Status =
== Features ==
* '''Places infrastructure (performance, stability, toolbar drag & drop)'''
** performance (Tp, Ts) has gotten better, close to status quo if not better
** problems with memory leak on balsa that we're trying to track down; this is blocking us as we can't turn it on. We're not sure that this is even Places that's doing it.
*** dveditz: the whole point of "WARN_IF_FALSE" was to warn instead of fail on an assertion.
*** darin: I'm gonna rack that up to maybe a typo in nsDebug.h?
*** ben: maybe we can flip places on?
*** beltzner: will post to devnews tonight, then flip it on for Weds morning

* '''Undo Close Tab'''
** at a hard decision about what approach to take
*** either hide-the-tab, try to leverage bfcache, or just try to preserve form data retention
** will be able to get it ready for A1 based on one of these directions, assuming we still want to
*** beltzner: I think we should get at least one of these directions in place
** darin: why would we use bfcache?
** bsmedberg: it might help persist full state while not allowing plugins and media to run in the background (which would happen with hide-the-tab)
** darin: need to be careful about onunload() handlers
** mconnor: if I can't figure out a way to make it work consistently, we might want to push this off to A2 or even extension-land

* '''Tab Overflow'''
**

* '''Extension Blacklisting'''
** patch waiting for review

* '''Extension Dependencies'''
** landed, no regressions

* '''Search Plugin Format Changeover (with sherlock import)'''
** review going well, working through Ben's comments
** not going to move to toolkit based on feedback in d-a-f
** looking to have a new patch for review soon (today/tomorrow)

* '''Spell-As-You-Type (english only)'''
** it's on trunk already (without the dictionary) --enable-extension: spellcheck? there are instructions in the enable spell check bug
** still blocked on licensing, who do I talk to about this? mscott for starters.
** ben: where does the dictionary file? what needs to happen with the build system to get it included?
** bsmedberg: point me to that please and we can get this started

* '''Instrumentation Infrastructure'''
** good progress on getting server infrastructure up and running
** should move this off to A2
** the exit survey will be in place for Firefox 1.5.0.2, morgamic is doing the final bits of work for the web app
*** also thinking about entrance survey
*** action '''beltzner''' cc darin on bug 314119

* '''RSS parser'''
** ben needs to check in with robert, think it's stuck waiting for a review

* '''RSS content detection (?)'''
** we ''think'' we're good here; not in darin's review queue anymore, at any rate

== Blockers ==
* version number / branding
** currently set at 1.5, should it be 2.0a1?
** benjamin: yes, that's what mscott's doing
** dveditz: should we also change the trunk, which is currently 1.6a1?
** benjamin: mscott has all of these under proposal
** '''action''' beltzner to take this as an action
* davel: when we push 2.0a1 to the beta-update channel, will these users get a choice?
** darin: yes, if we set something as a "major" release, they'll get a choice
** bsmedberg: it would be a good idea to test this code path on the nightly?
** annie: I think there's a lot of users who don't realize that they're on a beta channel right now, so we shouldn't be pushing the alpha onto the 1.5 beta channel
** '''action''' for darin to synch up with preed(?) to make sure that everyone's up to speed
** '''action''' for QA to test the 1.5.x update logic for user choice
* ben: release notes? documentation for MDC?
** promote it as a developer release
** mconnor: do we even want to promote it as that? some of these APIs are going to change?
** beltzner: but we want that feedback, don't we?
** mconnor: I'm worried about getting dugg, and getting bug feedback that we don't really care about anyway
** ben: maybe do it invite only?
** mconnor: get the release download numbers from Asa

= Status Updates =
== Places ==
* performance was good, no known data corruption issues
* annie's prepared some solid estimates, I need to do that and get it from the rest of the team
* '''action''' ben to meet with schrep next monday

== Tabbed Browsing ==
* nothing beyond what's been discussed

== Extension Manager Enhancements ==
* Extension Dependencies - phase 1 landed - no regressions so far
* Extension Blacklisting - patch ready for review last Friday
* Extension Locales - started
* Extension UI - mockups and proof of concept started

== Installer ==
* Windows Installer - nothing new other than work on this will start again this week
** bsmedberg: is DOM Inspector part of the product or not?
** first requirement is to be able to provide variable paths for distribution and packaging of our installer
** now we're starting to talk about creating various levels of stub install: stub with full code, stub with all code but not optional code, stub with no code.
*** bsmedberg: but do we consider DOM inspector part of the application or not?
*** rob_strong: put it on AMO?
*** beltzner: we need to figure out a way to make sure that it's there for users who need it, but not there for users who aren't there
* Branding and Locale installer customization - nothing new

== Search Engine UI ==
*Back end work complete
*Updated patch today or tomorrow - needs review from mconnor
**Addressed ben's SR comments
*Code to remain in /browser per discussion on dev.apps.firefox
*Re-factoring of the Sherlock parsing code to be completed seperately if time permits (low priority)
*Need to discuss search plugin format further

== Visual/UI Refresh ==
* requirements for the visual refresh are [[FX2_Visual_Update|on the wiki]]
** will be creating a new space for discussion of this theme (dev.apps.firefox.newtheme) and trying to figure out some place to provide hosting for mockups and images
* met with ben and jhughes yesterday to discuss changes to the default chrome for the browser window, the outcome of which was posted to [http://groups.google.com/group/mozilla.dev.apps.firefox dev.apps.firefox]

== Platform Uplift ==

* SVG textPath needs to get an answer and attention in the next 2 weeks, thus I make a commitment here that I will produce a landing scenario for them by March 10.

* no new status on UTF-16 XPCOM I/O fixes.

* schedule for platform uplift deadlines no longer clear due to schedule strategy shift; will try to build something new there for next week.

* need to produce a plan for tracking 1.8.1 approval queues and setting expectations there appropriately.

== Inline Spell Check ==
Waiting for clarification on licensing.

== Instrumentation / Exit Surveys ==
* Mostly working on server backend. Not much new status to report.
* {{bug|189570}} is fixed on the trunk.

== Session Saver ==
* SessionStore service mostly working in Bon Echo
* Currently pulling from cache or reloading, not dump/restoring DOM
* This week: define and document API, finish code review and post patch

== Branding & Update Systems ==
* nothing new here

== RSS ==
* need to check in with robert sayre

== Offline mode / better use of cache ==
* patch is in, waiting for branch approval
* continuing to investigate low hanging fruit

== Anti-Phishing ==
* fritz, darin, neils, mmc and brakowski meeting this afternoon to talk about ways of bundling/integrating Google phishing protector
* also investigating heuristic-based approaches and UI rendering for warnings about phishing

== EULA ==
* nothing new here

== Performance ==
* schrep's out of town, but is still planning to kick off a meeting on collecting better performance data on daily builds to continually monitor this issue

= Other Business =
* annie: maybe use Google's QA to help us here
** '''action''' annie and timr to talk about this

Firefox2/StatusMeetings/2006-02-28

2006-02-28T19:54:10Z

Darin: /* Offline mode / better use of cache */

[[Firefox2/StatusMeetings/2006-02-21|<< previous week]] | [[Firefox2/StatusMeetings|index]] | [[Firefox2/StatusMeetings/2006-03-07|next week>>]]

= In Attendance =

= Agenda =
# Alpha 1 Status
# Firefox 2 Feature Status Roundtable
# Any other business

= Alpha 1 Status =
== Features ==
* '''Places infrastructure (performance, stability, toolbar drag & drop)'''
* '''Undo Close Tab'''
* '''Tab Overflow'''
* '''Extension Blacklisting'''
* '''Extension Dependencies'''
* '''Search Plugin Format Changeover (with sherlock import)'''
* '''Spell-As-You-Type (english only)'''
* '''Instrumentation Infrastructure'''
* '''RSS parser'''
* '''RSS content detection (?)'''

== Blockers ==
* version number / branding
** currently set at 1.5, should it be 2.0a1?
* ''any others?''

== Release ==
* ''should we start the countdown?''

= Status Updates =
== Places ==

''update from ben''

Brett: "Performance is good, no known data corruption issues."

== Tabbed Browsing ==
''update from mconnor''

== Extension Manager Enhancements ==
* Extension Dependencies - phase 1 landed - no regressions so far
* Extension Blacklisting - patch ready for review last Friday
* Extension Locales - started
* Extension UI - mockups and proof of concept started

== Installer ==
* Windows Installer - nothing new other than work on this will start again this week
* Branding and Locale installer customization - nothing new

== Search Engine UI ==
*Back end work complete
*Updated patch today or tomorrow - needs review from mconnor
**Addressed ben's SR comments
*Code to remain in /browser per discussion on dev.apps.firefox
*Re-factoring of the Sherlock parsing code to be completed seperately if time permits (low priority)
*Need to discuss search plugin format further

== Visual/UI Refresh ==
* requirements for the visual refresh are [[FX2_Visual_Update|on the wiki]]
** will be creating a new space for discussion of this theme (dev.apps.firefox.newtheme) and trying to figure out some place to provide hosting for mockups and images
* met with ben and jhughes yesterday to discuss changes to the default chrome for the browser window, the outcome of which was posted to [http://groups.google.com/group/mozilla.dev.apps.firefox dev.apps.firefox]

== Platform Uplift ==

* SVG textPath needs to get an answer and attention in the next 2 weeks, thus I make a commitment here that I will produce a landing scenario for them by March 10.

* no new status on UTF-16 XPCOM I/O fixes.

* schedule for platform uplift deadlines no longer clear due to schedule strategy shift; will try to build something new there for next week.

* need to produce a plan for tracking 1.8.1 approval queues and setting expectations there appropriately.

== Inline Spell Check ==
Waiting for clarification on licensing.

== Instrumentation / Exit Surveys ==
Mostly working on server backend. Not much new status to report.

== Session Saver ==

* SessionStore service mostly working in Bon Echo
* Currently pulling from cache or reloading, not dump/restoring DOM
* This week: define and document API, finish code review and post patch

== Branding & Update Systems ==
* nothing new here

== RSS ==
''update from ben''

== Offline mode / better use of cache ==

{{bug|189570}} is fixed on the trunk.

== Anti-Phishing ==
* fritz, darin, neils, mmc and brakowski meeting this afternoon to talk about ways of bundling/integrating Google phishing protector
* also investigating heuristic-based approaches and UI rendering for warnings about phishing

== EULA ==
* nothing new here

== Performance ==
* schrep's out of town, but is still planning to kick off a meeting on collecting better performance data on daily builds to continually monitor this issue

= Other Business =

XPCOM:nsIThreadManager

2006-02-24T23:46:26Z

Darin: /* biesi: */