Debian Codegraph @

nsprpub/pr/include/private/pprthred.h

raw
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5
6 #ifndef pprthred_h___
7 #define pprthred_h___
8
9 /*
10 ** API for PR private functions. These calls are to be used by internal
11 ** developers only.
12 */
13 #include "nspr.h"
14
15 PR_BEGIN_EXTERN_C
16
17 /*---------------------------------------------------------------------------
18 ** THREAD PRIVATE FUNCTIONS
19 ---------------------------------------------------------------------------*/
20
21 /*
22 ** Associate a thread object with an existing native thread.
23 ** "type" is the type of thread object to attach
24 ** "priority" is the priority to assign to the thread
25 ** "stack" defines the shape of the threads stack
26 **
27 ** This can return NULL if some kind of error occurs, or if memory is
28 ** tight. This call invokes "start(obj,arg)" and returns when the
29 ** function returns. The thread object is automatically destroyed.
30 **
31 ** This call is not normally needed unless you create your own native
32 ** thread. PR_Init does this automatically for the primordial thread.
33 */
34 NSPR_API(PRThread*) PR_AttachThread(PRThreadType type,
35 PRThreadPriority priority,
36 PRThreadStack *stack);
37
38 /*
39 ** Detach the nspr thread from the currently executing native thread.
40 ** The thread object will be destroyed and all related data attached
41 ** to it. The exit procs will be invoked.
42 **
43 ** This call is not normally needed unless you create your own native
44 ** thread. PR_Exit will automatially detach the nspr thread object
45 ** created by PR_Init for the primordial thread.
46 **
47 ** This call returns after the nspr thread object is destroyed.
48 */
49 NSPR_API(void) PR_DetachThread(void);
50
51 /*
52 ** Get the id of the named thread. Each thread is assigned a unique id
53 ** when it is created or attached.
54 */
55 NSPR_API(PRUint32) PR_GetThreadID(PRThread *thread);
56
57 /*
58 ** Set the procedure that is called when a thread is dumped. The procedure
59 ** will be applied to the argument, arg, when called. Setting the procedure
60 ** to NULL effectively removes it.
61 */
62 typedef void (*PRThreadDumpProc)(PRFileDesc *fd, PRThread *t, void *arg);
63 NSPR_API(void) PR_SetThreadDumpProc(
64 PRThread* thread, PRThreadDumpProc dump, void *arg);
65
66 /*
67 ** Get this thread's affinity mask. The affinity mask is a 32 bit quantity
68 ** marking a bit for each processor this process is allowed to run on.
69 ** The processor mask is returned in the mask argument.
70 ** The least-significant-bit represents processor 0.
71 **
72 ** Returns 0 on success, -1 on failure.
73 */
74 NSPR_API(PRInt32) PR_GetThreadAffinityMask(PRThread *thread, PRUint32 *mask);
75
76 /*
77 ** Set this thread's affinity mask.
78 **
79 ** Returns 0 on success, -1 on failure.
80 */
81 NSPR_API(PRInt32) PR_SetThreadAffinityMask(PRThread *thread, PRUint32 mask );
82
83 /*
84 ** Set the default CPU Affinity mask.
85 **
86 */
87 NSPR_API(PRInt32) PR_SetCPUAffinityMask(PRUint32 mask);
88
89 /*
90 ** Show status of all threads to standard error output.
91 */
92 NSPR_API(void) PR_ShowStatus(void);
93
94 /*
95 ** Set thread recycle mode to on (1) or off (0)
96 */
97 NSPR_API(void) PR_SetThreadRecycleMode(PRUint32 flag);
98
99
100 /*---------------------------------------------------------------------------
101 ** THREAD PRIVATE FUNCTIONS FOR GARBAGE COLLECTIBLE THREADS
102 ---------------------------------------------------------------------------*/
103
104 /*
105 ** Only Garbage collectible threads participate in resume all, suspend all and
106 ** enumeration operations. They are also different during creation when
107 ** platform specific action may be needed (For example, all Solaris GC able
108 ** threads are bound threads).
109 */
110
111 /*
112 ** Same as PR_CreateThread except that the thread is marked as garbage
113 ** collectible.
114 */
115 NSPR_API(PRThread*) PR_CreateThreadGCAble(PRThreadType type,
116 void (*start)(void *arg),
117 void *arg,
118 PRThreadPriority priority,
119 PRThreadScope scope,
120 PRThreadState state,
121 PRUint32 stackSize);
122
123 /*
124 ** Same as PR_AttachThread except that the thread being attached is marked as
125 ** garbage collectible.
126 */
127 NSPR_API(PRThread*) PR_AttachThreadGCAble(PRThreadType type,
128 PRThreadPriority priority,
129 PRThreadStack *stack);
130
131 /*
132 ** Mark the thread as garbage collectible.
133 */
134 NSPR_API(void) PR_SetThreadGCAble(void);
135
136 /*
137 ** Unmark the thread as garbage collectible.
138 */
139 NSPR_API(void) PR_ClearThreadGCAble(void);
140
141 /*
142 ** This routine prevents all other GC able threads from running. This call is needed by
143 ** the garbage collector.
144 */
145 NSPR_API(void) PR_SuspendAll(void);
146
147 /*
148 ** This routine unblocks all other GC able threads that were suspended from running by
149 ** PR_SuspendAll(). This call is needed by the garbage collector.
150 */
151 NSPR_API(void) PR_ResumeAll(void);
152
153 /*
154 ** Return the thread stack pointer of the given thread.
155 ** Needed by the garbage collector.
156 */
157 NSPR_API(void *) PR_GetSP(PRThread *thread);
158
159 /*
160 ** Save the registers that the GC would find interesting into the thread
161 ** "t". isCurrent will be non-zero if the thread state that is being
162 ** saved is the currently executing thread. Return the address of the
163 ** first register to be scanned as well as the number of registers to
164 ** scan in "np".
165 **
166 ** If "isCurrent" is non-zero then it is allowed for the thread context
167 ** area to be used as scratch storage to hold just the registers
168 ** necessary for scanning.
169 **
170 ** This function simply calls the internal function _MD_HomeGCRegisters().
171 */
172 NSPR_API(PRWord *) PR_GetGCRegisters(PRThread *t, int isCurrent, int *np);
173
174 /*
175 ** (Get|Set)ExecutionEnvironent
176 **
177 ** Used by Java to associate it's execution environment so garbage collector
178 ** can find it. If return is NULL, then it's probably not a collectable thread.
179 **
180 ** There's no locking required around these calls.
181 */
182 NSPR_API(void*) GetExecutionEnvironment(PRThread *thread);
183 NSPR_API(void) SetExecutionEnvironment(PRThread* thread, void *environment);
184
185 /*
186 ** Enumeration function that applies "func(thread,i,arg)" to each active
187 ** thread in the process. The enumerator returns PR_SUCCESS if the enumeration
188 ** should continue, any other value is considered failure, and enumeration
189 ** stops, returning the failure value from PR_EnumerateThreads.
190 ** Needed by the garbage collector.
191 */
192 typedef PRStatus (PR_CALLBACK *PREnumerator)(PRThread *t, int i, void *arg);
193 NSPR_API(PRStatus) PR_EnumerateThreads(PREnumerator func, void *arg);
194
195 /*
196 ** Signature of a thread stack scanning function. It is applied to every
197 ** contiguous group of potential pointers within a thread. Count denotes the
198 ** number of pointers.
199 */
200 typedef PRStatus
201 (PR_CALLBACK *PRScanStackFun)(PRThread* t,
202 void** baseAddr, PRUword count, void* closure);
203
204 /*
205 ** Applies scanFun to all contiguous groups of potential pointers
206 ** within a thread. This includes the stack, registers, and thread-local
207 ** data. If scanFun returns a status value other than PR_SUCCESS the scan
208 ** is aborted, and the status value is returned.
209 */
210 NSPR_API(PRStatus)
211 PR_ThreadScanStackPointers(PRThread* t,
212 PRScanStackFun scanFun, void* scanClosure);
213
214 /*
215 ** Calls PR_ThreadScanStackPointers for every thread.
216 */
217 NSPR_API(PRStatus)
218 PR_ScanStackPointers(PRScanStackFun scanFun, void* scanClosure);
219
220 /*
221 ** Returns a conservative estimate on the amount of stack space left
222 ** on a thread in bytes, sufficient for making decisions about whether
223 ** to continue recursing or not.
224 */
225 NSPR_API(PRUword)
226 PR_GetStackSpaceLeft(PRThread* t);
227
228 /*---------------------------------------------------------------------------
229 ** THREAD CPU PRIVATE FUNCTIONS
230 ---------------------------------------------------------------------------*/
231
232 /*
233 ** Get a pointer to the primordial CPU.
234 */
235 NSPR_API(struct _PRCPU *) _PR_GetPrimordialCPU(void);
236
237 /*---------------------------------------------------------------------------
238 ** THREAD SYNCHRONIZATION PRIVATE FUNCTIONS
239 ---------------------------------------------------------------------------*/
240
241 /*
242 ** Create a new named monitor (named for debugging purposes).
243 ** Monitors are re-entrant locks with a built-in condition variable.
244 **
245 ** This may fail if memory is tight or if some operating system resource
246 ** is low.
247 */
248 NSPR_API(PRMonitor*) PR_NewNamedMonitor(const char* name);
249
250 /*
251 ** Test and then lock the lock if it's not already locked by some other
252 ** thread. Return PR_FALSE if some other thread owned the lock at the
253 ** time of the call.
254 */
255 NSPR_API(PRBool) PR_TestAndLock(PRLock *lock);
256
257 /*
258 ** Test and then enter the mutex associated with the monitor if it's not
259 ** already entered by some other thread. Return PR_FALSE if some other
260 ** thread owned the mutex at the time of the call.
261 */
262 NSPR_API(PRBool) PR_TestAndEnterMonitor(PRMonitor *mon);
263
264 /*
265 ** Return the number of times that the current thread has entered the
266 ** mutex. Returns zero if the current thread has not entered the mutex.
267 */
268 NSPR_API(PRIntn) PR_GetMonitorEntryCount(PRMonitor *mon);
269
270 /*
271 ** Just like PR_CEnterMonitor except that if the monitor is owned by
272 ** another thread NULL is returned.
273 */
274 NSPR_API(PRMonitor*) PR_CTestAndEnterMonitor(void *address);
275
276 /*---------------------------------------------------------------------------
277 ** PLATFORM-SPECIFIC INITIALIZATION FUNCTIONS
278 ---------------------------------------------------------------------------*/
279
280 /* I think PR_GetMonitorEntryCount is useless. All you really want is this... */
281 #define PR_InMonitor(m) (PR_GetMonitorEntryCount(m) > 0)
282
283 /*---------------------------------------------------------------------------
284 ** Special X-Lock hack for client
285 ---------------------------------------------------------------------------*/
286
287 #ifdef XP_UNIX
288 extern void _PR_XLock(void);
289 extern void _PR_XUnlock(void);
290 extern PRBool _PR_XIsLocked(void);
291 #endif /* XP_UNIX */
292
293 PR_END_EXTERN_C
294
295 #endif /* pprthred_h___ */