libraries/source/spidermonkey/include-win32-release/nspr/private/pprthred.h

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