xpcom/threads/nsIThread.idl@b8a032363ba2
xpcom/threads/nsIThread.idl
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* vim:set ts=2 sw=2 sts=2 et cindent: */
3 /* This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
7 #include "nsIEventTarget.idl"
9 [ptr] native PRThread(PRThread);
11 /**
12 * This interface provides a high-level abstraction for an operating system
13 * thread.
14 *
15 * Threads have a built-in event queue, and a thread is an event target that
16 * can receive nsIRunnable objects (events) to be processed on the thread.
17 *
18 * See nsIThreadManager for the API used to create and locate threads.
19 */
20 [scriptable, uuid(9c889946-a73a-4af3-ae9a-ea64f7d4e3ca)]
21 interface nsIThread : nsIEventTarget
22 {
23 /**
24 * @returns
25 * The NSPR thread object corresponding to this nsIThread.
26 */
27 [noscript] readonly attribute PRThread PRThread;
29 /**
30 * Shutdown the thread. This method prevents further dispatch of events to
31 * the thread, and it causes any pending events to run to completion before
32 * the thread joins (see PR_JoinThread) with the current thread. During this
33 * method call, events for the current thread may be processed.
34 *
35 * This method MAY NOT be executed from the thread itself. Instead, it is
36 * meant to be executed from another thread (usually the thread that created
37 * this thread or the main application thread). When this function returns,
38 * the thread will be shutdown, and it will no longer be possible to dispatch
39 * events to the thread.
40 *
41 * @throws NS_ERROR_UNEXPECTED
42 * Indicates that this method was erroneously called when this thread was
43 * the current thread, that this thread was not created with a call to
44 * nsIThreadManager::NewThread, or if this method was called more than once
45 * on the thread object.
46 */
47 void shutdown();
49 /**
50 * This method may be called to determine if there are any events ready to be
51 * processed. It may only be called when this thread is the current thread.
52 *
53 * Because events may be added to this thread by another thread, a "false"
54 * result does not mean that this thread has no pending events. It only
55 * means that there were no pending events when this method was called.
56 *
57 * @returns
58 * A boolean value that if "true" indicates that this thread has one or
59 * more pending events.
60 *
61 * @throws NS_ERROR_UNEXPECTED
62 * Indicates that this method was erroneously called when this thread was
63 * not the current thread.
64 */
65 boolean hasPendingEvents();
67 /**
68 * Process the next event. If there are no pending events, then this method
69 * may wait -- depending on the value of the mayWait parameter -- until an
70 * event is dispatched to this thread. This method is re-entrant but may
71 * only be called if this thread is the current thread.
72 *
73 * @param mayWait
74 * A boolean parameter that if "true" indicates that the method may block
75 * the calling thread to wait for a pending event.
76 *
77 * @returns
78 * A boolean value that if "true" indicates that an event was processed.
79 *
80 * @throws NS_ERROR_UNEXPECTED
81 * Indicates that this method was erroneously called when this thread was
82 * not the current thread.
83 */
84 boolean processNextEvent(in boolean mayWait);
85 };
