src/third_party/npapi/npspy/extern/nspr/private/pprthred.h

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