Back to index

lightning-sunbird  0.9+nobinonly
pprthred.h
Go to the documentation of this file.
00001 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is the Netscape Portable Runtime (NSPR).
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1998-2000
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either the GNU General Public License Version 2 or later (the "GPL"), or
00026  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 #ifndef pprthred_h___
00039 #define pprthred_h___
00040 
00041 /*
00042 ** API for PR private functions.  These calls are to be used by internal
00043 ** developers only.
00044 */
00045 #include "nspr.h"
00046 
00047 #if defined(XP_OS2)
00048 #define INCL_DOS
00049 #define INCL_DOSERRORS
00050 #define INCL_WIN
00051 #include <os2.h>
00052 #endif
00053 
00054 PR_BEGIN_EXTERN_C
00055 
00056 /*---------------------------------------------------------------------------
00057 ** THREAD PRIVATE FUNCTIONS
00058 ---------------------------------------------------------------------------*/
00059 
00060 /*
00061 ** Associate a thread object with an existing native thread.
00062 **     "type" is the type of thread object to attach
00063 **     "priority" is the priority to assign to the thread
00064 **     "stack" defines the shape of the threads stack
00065 **
00066 ** This can return NULL if some kind of error occurs, or if memory is
00067 ** tight. This call invokes "start(obj,arg)" and returns when the
00068 ** function returns. The thread object is automatically destroyed.
00069 **
00070 ** This call is not normally needed unless you create your own native
00071 ** thread. PR_Init does this automatically for the primordial thread.
00072 */
00073 NSPR_API(PRThread*) PR_AttachThread(PRThreadType type,
00074                                      PRThreadPriority priority,
00075                                  PRThreadStack *stack);
00076 
00077 /*
00078 ** Detach the nspr thread from the currently executing native thread.
00079 ** The thread object will be destroyed and all related data attached
00080 ** to it. The exit procs will be invoked.
00081 **
00082 ** This call is not normally needed unless you create your own native
00083 ** thread. PR_Exit will automatially detach the nspr thread object
00084 ** created by PR_Init for the primordial thread.
00085 **
00086 ** This call returns after the nspr thread object is destroyed.
00087 */
00088 NSPR_API(void) PR_DetachThread(void);
00089 
00090 /*
00091 ** Get the id of the named thread. Each thread is assigned a unique id
00092 ** when it is created or attached.
00093 */
00094 NSPR_API(PRUint32) PR_GetThreadID(PRThread *thread);
00095 
00096 /*
00097 ** Set the procedure that is called when a thread is dumped. The procedure
00098 ** will be applied to the argument, arg, when called. Setting the procedure
00099 ** to NULL effectively removes it.
00100 */
00101 typedef void (*PRThreadDumpProc)(PRFileDesc *fd, PRThread *t, void *arg);
00102 NSPR_API(void) PR_SetThreadDumpProc(
00103     PRThread* thread, PRThreadDumpProc dump, void *arg);
00104 
00105 /*
00106 ** Get this thread's affinity mask.  The affinity mask is a 32 bit quantity
00107 ** marking a bit for each processor this process is allowed to run on.
00108 ** The processor mask is returned in the mask argument.
00109 ** The least-significant-bit represents processor 0.
00110 **
00111 ** Returns 0 on success, -1 on failure.
00112 */
00113 NSPR_API(PRInt32) PR_GetThreadAffinityMask(PRThread *thread, PRUint32 *mask);
00114 
00115 /*
00116 ** Set this thread's affinity mask.  
00117 **
00118 ** Returns 0 on success, -1 on failure.
00119 */
00120 NSPR_API(PRInt32) PR_SetThreadAffinityMask(PRThread *thread, PRUint32 mask );
00121 
00122 /*
00123 ** Set the default CPU Affinity mask.
00124 **
00125 */
00126 NSPR_API(PRInt32) PR_SetCPUAffinityMask(PRUint32 mask);
00127 
00128 /*
00129 ** Show status of all threads to standard error output.
00130 */
00131 NSPR_API(void) PR_ShowStatus(void);
00132 
00133 /*
00134 ** Set thread recycle mode to on (1) or off (0)
00135 */
00136 NSPR_API(void) PR_SetThreadRecycleMode(PRUint32 flag);
00137 
00138 
00139 /*---------------------------------------------------------------------------
00140 ** THREAD PRIVATE FUNCTIONS FOR GARBAGE COLLECTIBLE THREADS           
00141 ---------------------------------------------------------------------------*/
00142 
00143 /* 
00144 ** Only Garbage collectible threads participate in resume all, suspend all and 
00145 ** enumeration operations.  They are also different during creation when
00146 ** platform specific action may be needed (For example, all Solaris GC able
00147 ** threads are bound threads).
00148 */
00149 
00150 /*
00151 ** Same as PR_CreateThread except that the thread is marked as garbage
00152 ** collectible.
00153 */
00154 NSPR_API(PRThread*) PR_CreateThreadGCAble(PRThreadType type,
00155                                  void (*start)(void *arg),
00156                                  void *arg,
00157                                  PRThreadPriority priority,
00158                                  PRThreadScope scope,
00159                                  PRThreadState state,
00160                                  PRUint32 stackSize);
00161 
00162 /*
00163 ** Same as PR_AttachThread except that the thread being attached is marked as 
00164 ** garbage collectible.
00165 */
00166 NSPR_API(PRThread*) PR_AttachThreadGCAble(PRThreadType type,
00167                                    PRThreadPriority priority,
00168                                    PRThreadStack *stack);
00169 
00170 /*
00171 ** Mark the thread as garbage collectible.
00172 */
00173 NSPR_API(void) PR_SetThreadGCAble(void);
00174 
00175 /*
00176 ** Unmark the thread as garbage collectible.
00177 */
00178 NSPR_API(void) PR_ClearThreadGCAble(void);
00179 
00180 /*
00181 ** This routine prevents all other GC able threads from running. This call is needed by 
00182 ** the garbage collector.
00183 */
00184 NSPR_API(void) PR_SuspendAll(void);
00185 
00186 /*
00187 ** This routine unblocks all other GC able threads that were suspended from running by 
00188 ** PR_SuspendAll(). This call is needed by the garbage collector.
00189 */
00190 NSPR_API(void) PR_ResumeAll(void);
00191 
00192 /*
00193 ** Return the thread stack pointer of the given thread. 
00194 ** Needed by the garbage collector.
00195 */
00196 NSPR_API(void *) PR_GetSP(PRThread *thread);
00197 
00198 /*
00199 ** Save the registers that the GC would find interesting into the thread
00200 ** "t". isCurrent will be non-zero if the thread state that is being
00201 ** saved is the currently executing thread. Return the address of the
00202 ** first register to be scanned as well as the number of registers to
00203 ** scan in "np".
00204 **
00205 ** If "isCurrent" is non-zero then it is allowed for the thread context
00206 ** area to be used as scratch storage to hold just the registers
00207 ** necessary for scanning.
00208 **
00209 ** This function simply calls the internal function _MD_HomeGCRegisters().
00210 */
00211 NSPR_API(PRWord *) PR_GetGCRegisters(PRThread *t, int isCurrent, int *np);
00212 
00213 /*
00214 ** (Get|Set)ExecutionEnvironent
00215 **
00216 ** Used by Java to associate it's execution environment so garbage collector
00217 ** can find it. If return is NULL, then it's probably not a collectable thread.
00218 **
00219 ** There's no locking required around these calls.
00220 */
00221 NSPR_API(void*) GetExecutionEnvironment(PRThread *thread);
00222 NSPR_API(void) SetExecutionEnvironment(PRThread* thread, void *environment);
00223 
00224 /*
00225 ** Enumeration function that applies "func(thread,i,arg)" to each active
00226 ** thread in the process. The enumerator returns PR_SUCCESS if the enumeration
00227 ** should continue, any other value is considered failure, and enumeration
00228 ** stops, returning the failure value from PR_EnumerateThreads.
00229 ** Needed by the garbage collector.
00230 */
00231 typedef PRStatus (PR_CALLBACK *PREnumerator)(PRThread *t, int i, void *arg);
00232 NSPR_API(PRStatus) PR_EnumerateThreads(PREnumerator func, void *arg);
00233 
00234 /* 
00235 ** Signature of a thread stack scanning function. It is applied to every
00236 ** contiguous group of potential pointers within a thread. Count denotes the
00237 ** number of pointers. 
00238 */
00239 typedef PRStatus 
00240 (PR_CALLBACK *PRScanStackFun)(PRThread* t,
00241                            void** baseAddr, PRUword count, void* closure);
00242 
00243 /*
00244 ** Applies scanFun to all contiguous groups of potential pointers 
00245 ** within a thread. This includes the stack, registers, and thread-local
00246 ** data. If scanFun returns a status value other than PR_SUCCESS the scan
00247 ** is aborted, and the status value is returned. 
00248 */
00249 NSPR_API(PRStatus)
00250 PR_ThreadScanStackPointers(PRThread* t,
00251                            PRScanStackFun scanFun, void* scanClosure);
00252 
00253 /* 
00254 ** Calls PR_ThreadScanStackPointers for every thread.
00255 */
00256 NSPR_API(PRStatus)
00257 PR_ScanStackPointers(PRScanStackFun scanFun, void* scanClosure);
00258 
00259 /*
00260 ** Returns a conservative estimate on the amount of stack space left
00261 ** on a thread in bytes, sufficient for making decisions about whether 
00262 ** to continue recursing or not.
00263 */
00264 NSPR_API(PRUword)
00265 PR_GetStackSpaceLeft(PRThread* t);
00266 
00267 /*---------------------------------------------------------------------------
00268 ** THREAD CPU PRIVATE FUNCTIONS             
00269 ---------------------------------------------------------------------------*/
00270 
00271 /*
00272 ** Get a pointer to the primordial CPU.
00273 */
00274 NSPR_API(struct _PRCPU *) _PR_GetPrimordialCPU(void);
00275 
00276 /*---------------------------------------------------------------------------
00277 ** THREAD SYNCHRONIZATION PRIVATE FUNCTIONS
00278 ---------------------------------------------------------------------------*/
00279 
00280 /*
00281 ** Create a new named monitor (named for debugging purposes).
00282 **  Monitors are re-entrant locks with a built-in condition variable.
00283 **
00284 ** This may fail if memory is tight or if some operating system resource
00285 ** is low.
00286 */
00287 NSPR_API(PRMonitor*) PR_NewNamedMonitor(const char* name);
00288 
00289 /*
00290 ** Test and then lock the lock if it's not already locked by some other
00291 ** thread. Return PR_FALSE if some other thread owned the lock at the
00292 ** time of the call.
00293 */
00294 NSPR_API(PRBool) PR_TestAndLock(PRLock *lock);
00295 
00296 /*
00297 ** Test and then enter the mutex associated with the monitor if it's not
00298 ** already entered by some other thread. Return PR_FALSE if some other
00299 ** thread owned the mutex at the time of the call.
00300 */
00301 NSPR_API(PRBool) PR_TestAndEnterMonitor(PRMonitor *mon);
00302 
00303 /*
00304 ** Return the number of times that the current thread has entered the
00305 ** mutex. Returns zero if the current thread has not entered the mutex.
00306 */
00307 NSPR_API(PRIntn) PR_GetMonitorEntryCount(PRMonitor *mon);
00308 
00309 /*
00310 ** Just like PR_CEnterMonitor except that if the monitor is owned by
00311 ** another thread NULL is returned.
00312 */
00313 NSPR_API(PRMonitor*) PR_CTestAndEnterMonitor(void *address);
00314 
00315 /*---------------------------------------------------------------------------
00316 ** PLATFORM-SPECIFIC THREAD SYNCHRONIZATION FUNCTIONS
00317 ---------------------------------------------------------------------------*/
00318 #if defined(XP_MAC)
00319 
00320 NSPR_API(void) PR_Mac_WaitForAsyncNotify(PRIntervalTime timeout);
00321 NSPR_API(void) PR_Mac_PostAsyncNotify(PRThread *thread);
00322 
00323 #endif /* XP_MAC */
00324 
00325 /*---------------------------------------------------------------------------
00326 ** PLATFORM-SPECIFIC INITIALIZATION FUNCTIONS
00327 ---------------------------------------------------------------------------*/
00328 #if defined(IRIX)
00329 /*
00330 ** Irix specific initialization funtion to be called before PR_Init
00331 ** is called by the application. Sets the CONF_INITUSERS and CONF_INITSIZE
00332 ** attributes of the shared arena set up by nspr.
00333 **
00334 ** The environment variables _NSPR_IRIX_INITUSERS and _NSPR_IRIX_INITSIZE
00335 ** can also be used to set these arena attributes. If _NSPR_IRIX_INITUSERS
00336 ** is set, but not _NSPR_IRIX_INITSIZE, the value of the CONF_INITSIZE
00337 ** attribute of the nspr arena is scaled as a function of the
00338 ** _NSPR_IRIX_INITUSERS value.
00339 ** 
00340 ** If the _PR_Irix_Set_Arena_Params() is called in addition to setting the
00341 ** environment variables, the values of the environment variables are used.
00342 ** 
00343 */
00344 NSPR_API(void) _PR_Irix_Set_Arena_Params(PRInt32 initusers, PRInt32 initsize);
00345 
00346 #endif /* IRIX */
00347 
00348 #if defined(XP_OS2)
00349 /*
00350 ** These functions need to be called at the start and end of a thread.
00351 ** An EXCEPTIONREGISTRATIONRECORD must be declared on the stack and its
00352 ** address passed to the two functions.
00353 */
00354 NSPR_API(void) PR_OS2_SetFloatExcpHandler(EXCEPTIONREGISTRATIONRECORD* e);
00355 NSPR_API(void) PR_OS2_UnsetFloatExcpHandler(EXCEPTIONREGISTRATIONRECORD* e);
00356 #endif /* XP_OS2 */
00357 
00358 /* I think PR_GetMonitorEntryCount is useless. All you really want is this... */
00359 #define PR_InMonitor(m)            (PR_GetMonitorEntryCount(m) > 0)
00360 
00361 /*---------------------------------------------------------------------------
00362 ** Special X-Lock hack for client
00363 ---------------------------------------------------------------------------*/
00364 
00365 #ifdef XP_UNIX
00366 extern void PR_XLock(void);
00367 extern void PR_XUnlock(void);
00368 extern PRBool PR_XIsLocked(void);
00369 #endif /* XP_UNIX */
00370 
00371 PR_END_EXTERN_C
00372 
00373 #endif /* pprthred_h___ */