pprthred.h (9941B)
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___ */