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