This interface provides a high-level abstraction for an operating system thread.

Threads have a built-in event queue, and a thread is an event target that can receive nsIRunnable objects (events) to be processed on the thread.

To create a thread, use the nsIThreadManager interface.

xpcom/threads/nsIThread.idlScriptable
Please add a summary to this article.
  Last changed in Gecko 1.9 (Firefox 3)

Inherits from: nsIEventTarget

Method overview

void shutdown()
boolean hasPendingEvents()
boolean processNextEvent(in boolean mayWait)

Attributes

Attribute Type Description
PRThread PRThread The NSPR thread object corresponding to the nsIThread. Read only.

Methods

shutdown()

Shuts down the thread. This causes events to stop being dispatched to the thread, and causes any pending events to run to completion before the thread joins with the current thread (see PR_JoinThread() for details). During the execution of this method call, events for the current thread may continue to be processed.

Warning: This method may not be called from the thread itself. Instead, you must only call it from another thread (usually the thread that created it, or the main application thread). When this function returns, the thread will be shut down and will no longer be available to receive events.

void shutdown()
Parameters

None.

Exceptions thrown
NS_ERROR_UNEXPECTED
shutdown() was erroneously called from within the thread itself, the thread was not created with the Thread Manager's nsIThreadManager.newThread() method, or the thread is already in the process of being shut down.

hasPendingEvents()

Determines whether or not the thread has events that are ready to be processed.

Note: This method must be called from within the thread itself, and not from another thread.

boolean hasPendingEvents()
Parameters

None.

Return value

true if there are pending events at the time the function was called. Since other threads may add events to the current thread, it's possible that by the time this method returns, the event queue may no longer be empty, even if a false result is reported.

Exceptions thrown
NS_ERROR_UNEXPECTED
The method was called when this thread wasn't the current thread.

processNextEvent()

Processes the next pending event. If there aren't any pending events, this method may wait -- depending on the value of the mayWait parameter -- until an event is dispatched to the thread.

This method is re-entrant but may only be called if this thread is the current thread.

Warning: Calling nsIThread.processNextEvent allows network and UI events to run which can modify data structures that your code isn't expecting to be modified during a synchronous method call. This can cause random crashes and other bugs that may be hard to find and fix. Consider use asynchronous callbacks instead.

boolean processNextEvent(
  in boolean mayWait
);
Parameters
mayWait
If true, this method blocks until an event is available to process if the event queue is empty. If false, this method returns immediately if the queue is empty.
Return value

Returns true if an event was processed, or false if there were no pending events.

Exceptions thrown
NS_ERROR_UNEXPECTED
This method was called when this thread wasn't the current thread.

See also