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