1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim:set ts=2 sw=2 sts=2 et cindent: */
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
#include "nsIEventTarget.idl"
#include "nsIIdlePeriod.idl"
%{C++
#include "mozilla/AlreadyAddRefed.h"
%}
[ptr] native PRThread(PRThread);
native alreadyAddRefed_nsIIdlePeriod(already_AddRefed<nsIIdlePeriod>);
/**
* 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.
*
* See nsIThreadManager for the API used to create and locate threads.
*/
[scriptable, uuid(5801d193-29d1-4964-a6b7-70eb697ddf2b)]
interface nsIThread : nsIEventTarget
{
/**
* @returns
* The NSPR thread object corresponding to this nsIThread.
*/
[noscript] readonly attribute PRThread PRThread;
/**
* @returns
* Whether or not this thread may call into JS. Used in the profiler
* to avoid some unnecessary locking.
*/
[noscript] attribute boolean CanInvokeJS;
/**
* Shutdown the thread. This method prevents further dispatch of events to
* the thread, and it causes any pending events to run to completion before
* the thread joins (see PR_JoinThread) with the current thread. During this
* method call, events for the current thread may be processed.
*
* 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 or the main application thread). When this function returns,
* the thread will be shutdown, and it will no longer be possible to dispatch
* events to the thread.
*
* @throws NS_ERROR_UNEXPECTED
* Indicates that this method was erroneously called when this thread was
* the current thread, that this thread was not created with a call to
* nsIThreadManager::NewThread, or if this method was called more than once
* on the thread object.
*/
void shutdown();
/**
* This method may be called to determine if there are any events ready to be
* processed. It may only be called when this thread is the current thread.
*
* Because events may be added to this thread by another thread, a "false"
* result does not mean that this thread has no pending events. It only
* means that there were no pending events when this method was called.
*
* @returns
* A boolean value that if "true" indicates that this thread has one or
* more pending events.
*
* @throws NS_ERROR_UNEXPECTED
* Indicates that this method was erroneously called when this thread was
* not the current thread.
*/
boolean hasPendingEvents();
/**
* Process the next event. If there are no pending events, then this method
* may wait -- depending on the value of the mayWait parameter -- 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.
*
* @param mayWait
* A boolean parameter that if "true" indicates that the method may block
* the calling thread to wait for a pending event.
*
* @returns
* A boolean value that if "true" indicates that an event was processed.
*
* @throws NS_ERROR_UNEXPECTED
* Indicates that this method was erroneously called when this thread was
* not the current thread.
*/
boolean processNextEvent(in boolean mayWait);
/**
* Shutdown the thread asynchronously. This method immediately prevents
* further dispatch of events to the thread, and it causes any pending events
* to run to completion before this thread joins with the current thread.
*
* UNLIKE shutdown() this does not process events on the current thread.
* Instead it merely ensures that the current thread continues running until
* this thread has shut down.
*
* 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 or the main application thread). When this function returns,
* the thread will continue running until it exhausts its event queue.
*
* @throws NS_ERROR_UNEXPECTED
* Indicates that this method was erroneously called when this thread was
* the current thread, that this thread was not created with a call to
* nsIThreadManager::NewThread, or if this method was called more than once
* on the thread object.
*/
void asyncShutdown();
/**
* Register an instance of nsIIdlePeriod which works as a facade of
* the abstract notion of a "current idle period". The
* nsIIdlePeriod should always represent the "current" idle period
* with regard to expected work for the thread. The thread is free
* to use this when there are no higher prioritized tasks to process
* to determine if it is reasonable to schedule tasks that could run
* when the thread is idle. The responsibility of the registered
* nsIIdlePeriod is to answer with an estimated deadline at which
* the thread should expect that it could receive new higher
* priority tasks.
*/
[noscript] void registerIdlePeriod(in alreadyAddRefed_nsIIdlePeriod aIdlePeriod);
/**
* Dispatch an event to the thread's idle queue. This function may be called
* from any thread, and it may be called re-entrantly.
*
* @param event
* The alreadyAddRefed<> event to dispatch.
* NOTE that the event will be leaked if it fails to dispatch.
*
* @throws NS_ERROR_INVALID_ARG
* Indicates that event is null.
*/
[noscript] void idleDispatch(in alreadyAddRefed_nsIRunnable event);
};
|
