1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/nsprpub/pr/include/private/pprthred.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,331 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#ifndef pprthred_h___
1.10 +#define pprthred_h___
1.11 +
1.12 +/*
1.13 +** API for PR private functions. These calls are to be used by internal
1.14 +** developers only.
1.15 +*/
1.16 +#include "nspr.h"
1.17 +
1.18 +#if defined(XP_OS2)
1.19 +#define INCL_DOS
1.20 +#define INCL_DOSERRORS
1.21 +#define INCL_WIN
1.22 +#include <os2.h>
1.23 +#endif
1.24 +
1.25 +PR_BEGIN_EXTERN_C
1.26 +
1.27 +/*---------------------------------------------------------------------------
1.28 +** THREAD PRIVATE FUNCTIONS
1.29 +---------------------------------------------------------------------------*/
1.30 +
1.31 +/*
1.32 +** Associate a thread object with an existing native thread.
1.33 +** "type" is the type of thread object to attach
1.34 +** "priority" is the priority to assign to the thread
1.35 +** "stack" defines the shape of the threads stack
1.36 +**
1.37 +** This can return NULL if some kind of error occurs, or if memory is
1.38 +** tight. This call invokes "start(obj,arg)" and returns when the
1.39 +** function returns. The thread object is automatically destroyed.
1.40 +**
1.41 +** This call is not normally needed unless you create your own native
1.42 +** thread. PR_Init does this automatically for the primordial thread.
1.43 +*/
1.44 +NSPR_API(PRThread*) PR_AttachThread(PRThreadType type,
1.45 + PRThreadPriority priority,
1.46 + PRThreadStack *stack);
1.47 +
1.48 +/*
1.49 +** Detach the nspr thread from the currently executing native thread.
1.50 +** The thread object will be destroyed and all related data attached
1.51 +** to it. The exit procs will be invoked.
1.52 +**
1.53 +** This call is not normally needed unless you create your own native
1.54 +** thread. PR_Exit will automatially detach the nspr thread object
1.55 +** created by PR_Init for the primordial thread.
1.56 +**
1.57 +** This call returns after the nspr thread object is destroyed.
1.58 +*/
1.59 +NSPR_API(void) PR_DetachThread(void);
1.60 +
1.61 +/*
1.62 +** Get the id of the named thread. Each thread is assigned a unique id
1.63 +** when it is created or attached.
1.64 +*/
1.65 +NSPR_API(PRUint32) PR_GetThreadID(PRThread *thread);
1.66 +
1.67 +/*
1.68 +** Set the procedure that is called when a thread is dumped. The procedure
1.69 +** will be applied to the argument, arg, when called. Setting the procedure
1.70 +** to NULL effectively removes it.
1.71 +*/
1.72 +typedef void (*PRThreadDumpProc)(PRFileDesc *fd, PRThread *t, void *arg);
1.73 +NSPR_API(void) PR_SetThreadDumpProc(
1.74 + PRThread* thread, PRThreadDumpProc dump, void *arg);
1.75 +
1.76 +/*
1.77 +** Get this thread's affinity mask. The affinity mask is a 32 bit quantity
1.78 +** marking a bit for each processor this process is allowed to run on.
1.79 +** The processor mask is returned in the mask argument.
1.80 +** The least-significant-bit represents processor 0.
1.81 +**
1.82 +** Returns 0 on success, -1 on failure.
1.83 +*/
1.84 +NSPR_API(PRInt32) PR_GetThreadAffinityMask(PRThread *thread, PRUint32 *mask);
1.85 +
1.86 +/*
1.87 +** Set this thread's affinity mask.
1.88 +**
1.89 +** Returns 0 on success, -1 on failure.
1.90 +*/
1.91 +NSPR_API(PRInt32) PR_SetThreadAffinityMask(PRThread *thread, PRUint32 mask );
1.92 +
1.93 +/*
1.94 +** Set the default CPU Affinity mask.
1.95 +**
1.96 +*/
1.97 +NSPR_API(PRInt32) PR_SetCPUAffinityMask(PRUint32 mask);
1.98 +
1.99 +/*
1.100 +** Show status of all threads to standard error output.
1.101 +*/
1.102 +NSPR_API(void) PR_ShowStatus(void);
1.103 +
1.104 +/*
1.105 +** Set thread recycle mode to on (1) or off (0)
1.106 +*/
1.107 +NSPR_API(void) PR_SetThreadRecycleMode(PRUint32 flag);
1.108 +
1.109 +
1.110 +/*---------------------------------------------------------------------------
1.111 +** THREAD PRIVATE FUNCTIONS FOR GARBAGE COLLECTIBLE THREADS
1.112 +---------------------------------------------------------------------------*/
1.113 +
1.114 +/*
1.115 +** Only Garbage collectible threads participate in resume all, suspend all and
1.116 +** enumeration operations. They are also different during creation when
1.117 +** platform specific action may be needed (For example, all Solaris GC able
1.118 +** threads are bound threads).
1.119 +*/
1.120 +
1.121 +/*
1.122 +** Same as PR_CreateThread except that the thread is marked as garbage
1.123 +** collectible.
1.124 +*/
1.125 +NSPR_API(PRThread*) PR_CreateThreadGCAble(PRThreadType type,
1.126 + void (*start)(void *arg),
1.127 + void *arg,
1.128 + PRThreadPriority priority,
1.129 + PRThreadScope scope,
1.130 + PRThreadState state,
1.131 + PRUint32 stackSize);
1.132 +
1.133 +/*
1.134 +** Same as PR_AttachThread except that the thread being attached is marked as
1.135 +** garbage collectible.
1.136 +*/
1.137 +NSPR_API(PRThread*) PR_AttachThreadGCAble(PRThreadType type,
1.138 + PRThreadPriority priority,
1.139 + PRThreadStack *stack);
1.140 +
1.141 +/*
1.142 +** Mark the thread as garbage collectible.
1.143 +*/
1.144 +NSPR_API(void) PR_SetThreadGCAble(void);
1.145 +
1.146 +/*
1.147 +** Unmark the thread as garbage collectible.
1.148 +*/
1.149 +NSPR_API(void) PR_ClearThreadGCAble(void);
1.150 +
1.151 +/*
1.152 +** This routine prevents all other GC able threads from running. This call is needed by
1.153 +** the garbage collector.
1.154 +*/
1.155 +NSPR_API(void) PR_SuspendAll(void);
1.156 +
1.157 +/*
1.158 +** This routine unblocks all other GC able threads that were suspended from running by
1.159 +** PR_SuspendAll(). This call is needed by the garbage collector.
1.160 +*/
1.161 +NSPR_API(void) PR_ResumeAll(void);
1.162 +
1.163 +/*
1.164 +** Return the thread stack pointer of the given thread.
1.165 +** Needed by the garbage collector.
1.166 +*/
1.167 +NSPR_API(void *) PR_GetSP(PRThread *thread);
1.168 +
1.169 +/*
1.170 +** Save the registers that the GC would find interesting into the thread
1.171 +** "t". isCurrent will be non-zero if the thread state that is being
1.172 +** saved is the currently executing thread. Return the address of the
1.173 +** first register to be scanned as well as the number of registers to
1.174 +** scan in "np".
1.175 +**
1.176 +** If "isCurrent" is non-zero then it is allowed for the thread context
1.177 +** area to be used as scratch storage to hold just the registers
1.178 +** necessary for scanning.
1.179 +**
1.180 +** This function simply calls the internal function _MD_HomeGCRegisters().
1.181 +*/
1.182 +NSPR_API(PRWord *) PR_GetGCRegisters(PRThread *t, int isCurrent, int *np);
1.183 +
1.184 +/*
1.185 +** (Get|Set)ExecutionEnvironent
1.186 +**
1.187 +** Used by Java to associate it's execution environment so garbage collector
1.188 +** can find it. If return is NULL, then it's probably not a collectable thread.
1.189 +**
1.190 +** There's no locking required around these calls.
1.191 +*/
1.192 +NSPR_API(void*) GetExecutionEnvironment(PRThread *thread);
1.193 +NSPR_API(void) SetExecutionEnvironment(PRThread* thread, void *environment);
1.194 +
1.195 +/*
1.196 +** Enumeration function that applies "func(thread,i,arg)" to each active
1.197 +** thread in the process. The enumerator returns PR_SUCCESS if the enumeration
1.198 +** should continue, any other value is considered failure, and enumeration
1.199 +** stops, returning the failure value from PR_EnumerateThreads.
1.200 +** Needed by the garbage collector.
1.201 +*/
1.202 +typedef PRStatus (PR_CALLBACK *PREnumerator)(PRThread *t, int i, void *arg);
1.203 +NSPR_API(PRStatus) PR_EnumerateThreads(PREnumerator func, void *arg);
1.204 +
1.205 +/*
1.206 +** Signature of a thread stack scanning function. It is applied to every
1.207 +** contiguous group of potential pointers within a thread. Count denotes the
1.208 +** number of pointers.
1.209 +*/
1.210 +typedef PRStatus
1.211 +(PR_CALLBACK *PRScanStackFun)(PRThread* t,
1.212 + void** baseAddr, PRUword count, void* closure);
1.213 +
1.214 +/*
1.215 +** Applies scanFun to all contiguous groups of potential pointers
1.216 +** within a thread. This includes the stack, registers, and thread-local
1.217 +** data. If scanFun returns a status value other than PR_SUCCESS the scan
1.218 +** is aborted, and the status value is returned.
1.219 +*/
1.220 +NSPR_API(PRStatus)
1.221 +PR_ThreadScanStackPointers(PRThread* t,
1.222 + PRScanStackFun scanFun, void* scanClosure);
1.223 +
1.224 +/*
1.225 +** Calls PR_ThreadScanStackPointers for every thread.
1.226 +*/
1.227 +NSPR_API(PRStatus)
1.228 +PR_ScanStackPointers(PRScanStackFun scanFun, void* scanClosure);
1.229 +
1.230 +/*
1.231 +** Returns a conservative estimate on the amount of stack space left
1.232 +** on a thread in bytes, sufficient for making decisions about whether
1.233 +** to continue recursing or not.
1.234 +*/
1.235 +NSPR_API(PRUword)
1.236 +PR_GetStackSpaceLeft(PRThread* t);
1.237 +
1.238 +/*---------------------------------------------------------------------------
1.239 +** THREAD CPU PRIVATE FUNCTIONS
1.240 +---------------------------------------------------------------------------*/
1.241 +
1.242 +/*
1.243 +** Get a pointer to the primordial CPU.
1.244 +*/
1.245 +NSPR_API(struct _PRCPU *) _PR_GetPrimordialCPU(void);
1.246 +
1.247 +/*---------------------------------------------------------------------------
1.248 +** THREAD SYNCHRONIZATION PRIVATE FUNCTIONS
1.249 +---------------------------------------------------------------------------*/
1.250 +
1.251 +/*
1.252 +** Create a new named monitor (named for debugging purposes).
1.253 +** Monitors are re-entrant locks with a built-in condition variable.
1.254 +**
1.255 +** This may fail if memory is tight or if some operating system resource
1.256 +** is low.
1.257 +*/
1.258 +NSPR_API(PRMonitor*) PR_NewNamedMonitor(const char* name);
1.259 +
1.260 +/*
1.261 +** Test and then lock the lock if it's not already locked by some other
1.262 +** thread. Return PR_FALSE if some other thread owned the lock at the
1.263 +** time of the call.
1.264 +*/
1.265 +NSPR_API(PRBool) PR_TestAndLock(PRLock *lock);
1.266 +
1.267 +/*
1.268 +** Test and then enter the mutex associated with the monitor if it's not
1.269 +** already entered by some other thread. Return PR_FALSE if some other
1.270 +** thread owned the mutex at the time of the call.
1.271 +*/
1.272 +NSPR_API(PRBool) PR_TestAndEnterMonitor(PRMonitor *mon);
1.273 +
1.274 +/*
1.275 +** Return the number of times that the current thread has entered the
1.276 +** mutex. Returns zero if the current thread has not entered the mutex.
1.277 +*/
1.278 +NSPR_API(PRIntn) PR_GetMonitorEntryCount(PRMonitor *mon);
1.279 +
1.280 +/*
1.281 +** Just like PR_CEnterMonitor except that if the monitor is owned by
1.282 +** another thread NULL is returned.
1.283 +*/
1.284 +NSPR_API(PRMonitor*) PR_CTestAndEnterMonitor(void *address);
1.285 +
1.286 +/*---------------------------------------------------------------------------
1.287 +** PLATFORM-SPECIFIC INITIALIZATION FUNCTIONS
1.288 +---------------------------------------------------------------------------*/
1.289 +#if defined(IRIX)
1.290 +/*
1.291 +** Irix specific initialization funtion to be called before PR_Init
1.292 +** is called by the application. Sets the CONF_INITUSERS and CONF_INITSIZE
1.293 +** attributes of the shared arena set up by nspr.
1.294 +**
1.295 +** The environment variables _NSPR_IRIX_INITUSERS and _NSPR_IRIX_INITSIZE
1.296 +** can also be used to set these arena attributes. If _NSPR_IRIX_INITUSERS
1.297 +** is set, but not _NSPR_IRIX_INITSIZE, the value of the CONF_INITSIZE
1.298 +** attribute of the nspr arena is scaled as a function of the
1.299 +** _NSPR_IRIX_INITUSERS value.
1.300 +**
1.301 +** If the _PR_Irix_Set_Arena_Params() is called in addition to setting the
1.302 +** environment variables, the values of the environment variables are used.
1.303 +**
1.304 +*/
1.305 +NSPR_API(void) _PR_Irix_Set_Arena_Params(PRInt32 initusers, PRInt32 initsize);
1.306 +
1.307 +#endif /* IRIX */
1.308 +
1.309 +#if defined(XP_OS2)
1.310 +/*
1.311 +** These functions need to be called at the start and end of a thread.
1.312 +** An EXCEPTIONREGISTRATIONRECORD must be declared on the stack and its
1.313 +** address passed to the two functions.
1.314 +*/
1.315 +NSPR_API(void) PR_OS2_SetFloatExcpHandler(EXCEPTIONREGISTRATIONRECORD* e);
1.316 +NSPR_API(void) PR_OS2_UnsetFloatExcpHandler(EXCEPTIONREGISTRATIONRECORD* e);
1.317 +#endif /* XP_OS2 */
1.318 +
1.319 +/* I think PR_GetMonitorEntryCount is useless. All you really want is this... */
1.320 +#define PR_InMonitor(m) (PR_GetMonitorEntryCount(m) > 0)
1.321 +
1.322 +/*---------------------------------------------------------------------------
1.323 +** Special X-Lock hack for client
1.324 +---------------------------------------------------------------------------*/
1.325 +
1.326 +#ifdef XP_UNIX
1.327 +extern void PR_XLock(void);
1.328 +extern void PR_XUnlock(void);
1.329 +extern PRBool PR_XIsLocked(void);
1.330 +#endif /* XP_UNIX */
1.331 +
1.332 +PR_END_EXTERN_C
1.333 +
1.334 +#endif /* pprthred_h___ */
