/gecko_api/include/private/pprthred.h

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