| 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___ */ |