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