1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 /* 3 * The contents of this file are subject to the Mozilla Public 4 * License Version 1.1 (the "License"); you may not use this file 5 * except in compliance with the License. You may obtain a copy of 6 * the License at http://www.mozilla.org/MPL/ 7 * 8 * Software distributed under the License is distributed on an "AS 9 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or 10 * implied. See the License for the specific language governing 11 * rights and limitations under the License. 12 * 13 * The Original Code is the Netscape Portable Runtime (NSPR). 14 * 15 * The Initial Developer of the Original Code is Netscape 16 * Communications Corporation. Portions created by Netscape are 17 * Copyright (C) 1998-2000 Netscape Communications Corporation. All 18 * Rights Reserved. 19 * 20 * Contributor(s): 21 * 22 * Alternatively, the contents of this file may be used under the 23 * terms of the GNU General Public License Version 2 or later (the 24 * "GPL"), in which case the provisions of the GPL are applicable 25 * instead of those above. If you wish to allow use of your 26 * version of this file only under the terms of the GPL and not to 27 * allow others to use your version of this file under the MPL, 28 * indicate your decision by deleting the provisions above and 29 * replace them with the notice and other provisions required by 30 * the GPL. If you do not delete the provisions above, a recipient 31 * may use your version of this file under either the MPL or the 32 * GPL. 33 */ 34 35 #ifndef pprthred_h___ 36 #define pprthred_h___ 37 38 /* 39 ** API for PR private functions. These calls are to be used by internal 40 ** developers only. 41 */ 42 #include "nspr.h" 43 44 #if defined(XP_OS2) 45 #define INCL_DOS 46 #define INCL_DOSERRORS 47 #define INCL_WIN 48 #include <os2.h> 49 #endif 50 51 PR_BEGIN_EXTERN_C 52 53 /*--------------------------------------------------------------------------- 54 ** THREAD PRIVATE FUNCTIONS 55 ---------------------------------------------------------------------------*/ 56 57 /* 58 ** Associate a thread object with an existing native thread. 59 ** "type" is the type of thread object to attach 60 ** "priority" is the priority to assign to the thread 61 ** "stack" defines the shape of the threads stack 62 ** 63 ** This can return NULL if some kind of error occurs, or if memory is 64 ** tight. This call invokes "start(obj,arg)" and returns when the 65 ** function returns. The thread object is automatically destroyed. 66 ** 67 ** This call is not normally needed unless you create your own native 68 ** thread. PR_Init does this automatically for the primordial thread. 69 */ 70 NSPR_API(PRThread*) PR_AttachThread(PRThreadType type, 71 PRThreadPriority priority, 72 PRThreadStack *stack); 73 74 /* 75 ** Detach the nspr thread from the currently executing native thread. 76 ** The thread object will be destroyed and all related data attached 77 ** to it. The exit procs will be invoked. 78 ** 79 ** This call is not normally needed unless you create your own native 80 ** thread. PR_Exit will automatially detach the nspr thread object 81 ** created by PR_Init for the primordial thread. 82 ** 83 ** This call returns after the nspr thread object is destroyed. 84 */ 85 NSPR_API(void) PR_DetachThread(void); 86 87 /* 88 ** Get the id of the named thread. Each thread is assigned a unique id 89 ** when it is created or attached. 90 */ 91 NSPR_API(PRUint32) PR_GetThreadID(PRThread *thread); 92 93 /* 94 ** Set the procedure that is called when a thread is dumped. The procedure 95 ** will be applied to the argument, arg, when called. Setting the procedure 96 ** to NULL effectively removes it. 97 */ 98 typedef void (*PRThreadDumpProc)(PRFileDesc *fd, PRThread *t, void *arg); 99 NSPR_API(void) PR_SetThreadDumpProc( 100 PRThread* thread, PRThreadDumpProc dump, void *arg); 101 102 /* 103 ** Get this thread's affinity mask. The affinity mask is a 32 bit quantity 104 ** marking a bit for each processor this process is allowed to run on. 105 ** The processor mask is returned in the mask argument. 106 ** The least-significant-bit represents processor 0. 107 ** 108 ** Returns 0 on success, -1 on failure. 109 */ 110 NSPR_API(PRInt32) PR_GetThreadAffinityMask(PRThread *thread, PRUint32 *mask); 111 112 /* 113 ** Set this thread's affinity mask. 114 ** 115 ** Returns 0 on success, -1 on failure. 116 */ 117 NSPR_API(PRInt32) PR_SetThreadAffinityMask(PRThread *thread, PRUint32 mask ); 118 119 /* 120 ** Set the default CPU Affinity mask. 121 ** 122 */ 123 NSPR_API(PRInt32) PR_SetCPUAffinityMask(PRUint32 mask); 124 125 /* 126 ** Show status of all threads to standard error output. 127 */ 128 NSPR_API(void) PR_ShowStatus(void); 129 130 /* 131 ** Set thread recycle mode to on (1) or off (0) 132 */ 133 NSPR_API(void) PR_SetThreadRecycleMode(PRUint32 flag); 134 135 136 /*--------------------------------------------------------------------------- 137 ** THREAD PRIVATE FUNCTIONS FOR GARBAGE COLLECTIBLE THREADS 138 ---------------------------------------------------------------------------*/ 139 140 /* 141 ** Only Garbage collectible threads participate in resume all, suspend all and 142 ** enumeration operations. They are also different during creation when 143 ** platform specific action may be needed (For example, all Solaris GC able 144 ** threads are bound threads). 145 */ 146 147 /* 148 ** Same as PR_CreateThread except that the thread is marked as garbage 149 ** collectible. 150 */ 151 NSPR_API(PRThread*) PR_CreateThreadGCAble(PRThreadType type, 152 void (*start)(void *arg), 153 void *arg, 154 PRThreadPriority priority, 155 PRThreadScope scope, 156 PRThreadState state, 157 PRUint32 stackSize); 158 159 /* 160 ** Same as PR_AttachThread except that the thread being attached is marked as 161 ** garbage collectible. 162 */ 163 NSPR_API(PRThread*) PR_AttachThreadGCAble(PRThreadType type, 164 PRThreadPriority priority, 165 PRThreadStack *stack); 166 167 /* 168 ** Mark the thread as garbage collectible. 169 */ 170 NSPR_API(void) PR_SetThreadGCAble(void); 171 172 /* 173 ** Unmark the thread as garbage collectible. 174 */ 175 NSPR_API(void) PR_ClearThreadGCAble(void); 176 177 /* 178 ** This routine prevents all other GC able threads from running. This call is needed by 179 ** the garbage collector. 180 */ 181 NSPR_API(void) PR_SuspendAll(void); 182 183 /* 184 ** This routine unblocks all other GC able threads that were suspended from running by 185 ** PR_SuspendAll(). This call is needed by the garbage collector. 186 */ 187 NSPR_API(void) PR_ResumeAll(void); 188 189 /* 190 ** Return the thread stack pointer of the given thread. 191 ** Needed by the garbage collector. 192 */ 193 NSPR_API(void *) PR_GetSP(PRThread *thread); 194 195 /* 196 ** Save the registers that the GC would find interesting into the thread 197 ** "t". isCurrent will be non-zero if the thread state that is being 198 ** saved is the currently executing thread. Return the address of the 199 ** first register to be scanned as well as the number of registers to 200 ** scan in "np". 201 ** 202 ** If "isCurrent" is non-zero then it is allowed for the thread context 203 ** area to be used as scratch storage to hold just the registers 204 ** necessary for scanning. 205 ** 206 ** This function simply calls the internal function _MD_HomeGCRegisters(). 207 */ 208 NSPR_API(PRWord *) PR_GetGCRegisters(PRThread *t, int isCurrent, int *np); 209 210 /* 211 ** (Get|Set)ExecutionEnvironent 212 ** 213 ** Used by Java to associate it's execution environment so garbage collector 214 ** can find it. If return is NULL, then it's probably not a collectable thread. 215 ** 216 ** There's no locking required around these calls. 217 */ 218 NSPR_API(void*) GetExecutionEnvironment(PRThread *thread); 219 NSPR_API(void) SetExecutionEnvironment(PRThread* thread, void *environment); 220 221 /* 222 ** Enumeration function that applies "func(thread,i,arg)" to each active 223 ** thread in the process. The enumerator returns PR_SUCCESS if the enumeration 224 ** should continue, any other value is considered failure, and enumeration 225 ** stops, returning the failure value from PR_EnumerateThreads. 226 ** Needed by the garbage collector. 227 */ 228 typedef PRStatus (PR_CALLBACK *PREnumerator)(PRThread *t, int i, void *arg); 229 NSPR_API(PRStatus) PR_EnumerateThreads(PREnumerator func, void *arg); 230 231 /* 232 ** Signature of a thread stack scanning function. It is applied to every 233 ** contiguous group of potential pointers within a thread. Count denotes the 234 ** number of pointers. 235 */ 236 typedef PRStatus 237 (PR_CALLBACK *PRScanStackFun)(PRThread* t, 238 void** baseAddr, PRUword count, void* closure); 239 240 /* 241 ** Applies scanFun to all contiguous groups of potential pointers 242 ** within a thread. This includes the stack, registers, and thread-local 243 ** data. If scanFun returns a status value other than PR_SUCCESS the scan 244 ** is aborted, and the status value is returned. 245 */ 246 NSPR_API(PRStatus) 247 PR_ThreadScanStackPointers(PRThread* t, 248 PRScanStackFun scanFun, void* scanClosure); 249 250 /* 251 ** Calls PR_ThreadScanStackPointers for every thread. 252 */ 253 NSPR_API(PRStatus) 254 PR_ScanStackPointers(PRScanStackFun scanFun, void* scanClosure); 255 256 /* 257 ** Returns a conservative estimate on the amount of stack space left 258 ** on a thread in bytes, sufficient for making decisions about whether 259 ** to continue recursing or not. 260 */ 261 NSPR_API(PRUword) 262 PR_GetStackSpaceLeft(PRThread* t); 263 264 /*--------------------------------------------------------------------------- 265 ** THREAD CPU PRIVATE FUNCTIONS 266 ---------------------------------------------------------------------------*/ 267 268 /* 269 ** Get a pointer to the primordial CPU. 270 */ 271 NSPR_API(struct _PRCPU *) _PR_GetPrimordialCPU(void); 272 273 /*--------------------------------------------------------------------------- 274 ** THREAD SYNCHRONIZATION PRIVATE FUNCTIONS 275 ---------------------------------------------------------------------------*/ 276 277 /* 278 ** Create a new named monitor (named for debugging purposes). 279 ** Monitors are re-entrant locks with a built-in condition variable. 280 ** 281 ** This may fail if memory is tight or if some operating system resource 282 ** is low. 283 */ 284 NSPR_API(PRMonitor*) PR_NewNamedMonitor(const char* name); 285 286 /* 287 ** Test and then lock the lock if it's not already locked by some other 288 ** thread. Return PR_FALSE if some other thread owned the lock at the 289 ** time of the call. 290 */ 291 NSPR_API(PRBool) PR_TestAndLock(PRLock *lock); 292 293 /* 294 ** Test and then enter the mutex associated with the monitor if it's not 295 ** already entered by some other thread. Return PR_FALSE if some other 296 ** thread owned the mutex at the time of the call. 297 */ 298 NSPR_API(PRBool) PR_TestAndEnterMonitor(PRMonitor *mon); 299 300 /* 301 ** Return the number of times that the current thread has entered the 302 ** mutex. Returns zero if the current thread has not entered the mutex. 303 */ 304 NSPR_API(PRIntn) PR_GetMonitorEntryCount(PRMonitor *mon); 305 306 /* 307 ** Just like PR_CEnterMonitor except that if the monitor is owned by 308 ** another thread NULL is returned. 309 */ 310 NSPR_API(PRMonitor*) PR_CTestAndEnterMonitor(void *address); 311 312 /*--------------------------------------------------------------------------- 313 ** PLATFORM-SPECIFIC THREAD SYNCHRONIZATION FUNCTIONS 314 ---------------------------------------------------------------------------*/ 315 #if defined(XP_MAC) 316 317 NSPR_API(void) PR_Mac_WaitForAsyncNotify(PRIntervalTime timeout); 318 NSPR_API(void) PR_Mac_PostAsyncNotify(PRThread *thread); 319 320 #endif /* XP_MAC */ 321 322 /*--------------------------------------------------------------------------- 323 ** PLATFORM-SPECIFIC INITIALIZATION FUNCTIONS 324 ---------------------------------------------------------------------------*/ 325 #if defined(IRIX) 326 /* 327 ** Irix specific initialization funtion to be called before PR_Init 328 ** is called by the application. Sets the CONF_INITUSERS and CONF_INITSIZE 329 ** attributes of the shared arena set up by nspr. 330 ** 331 ** The environment variables _NSPR_IRIX_INITUSERS and _NSPR_IRIX_INITSIZE 332 ** can also be used to set these arena attributes. If _NSPR_IRIX_INITUSERS 333 ** is set, but not _NSPR_IRIX_INITSIZE, the value of the CONF_INITSIZE 334 ** attribute of the nspr arena is scaled as a function of the 335 ** _NSPR_IRIX_INITUSERS value. 336 ** 337 ** If the _PR_Irix_Set_Arena_Params() is called in addition to setting the 338 ** environment variables, the values of the environment variables are used. 339 ** 340 */ 341 NSPR_API(void) _PR_Irix_Set_Arena_Params(PRInt32 initusers, PRInt32 initsize); 342 343 #endif /* IRIX */ 344 345 #if defined(XP_OS2) 346 /* 347 ** These functions need to be called at the start and end of a thread. 348 ** An EXCEPTIONREGISTRATIONRECORD must be declared on the stack and its 349 ** address passed to the two functions. 350 */ 351 NSPR_API(void) PR_OS2_SetFloatExcpHandler(EXCEPTIONREGISTRATIONRECORD* e); 352 NSPR_API(void) PR_OS2_UnsetFloatExcpHandler(EXCEPTIONREGISTRATIONRECORD* e); 353 #endif /* XP_OS2 */ 354 355 /* I think PR_GetMonitorEntryCount is useless. All you really want is this... */ 356 #define PR_InMonitor(m) (PR_GetMonitorEntryCount(m) > 0) 357 358 /*--------------------------------------------------------------------------- 359 ** Special X-Lock hack for client 360 ---------------------------------------------------------------------------*/ 361 362 #ifdef XP_UNIX 363 extern void PR_XLock(void); 364 extern void PR_XUnlock(void); 365 extern PRBool PR_XIsLocked(void); 366 #endif /* XP_UNIX */ 367 368 PR_END_EXTERN_C 369 370 #endif /* pprthred_h___ */ 371
