Back to index

lightning-sunbird  0.9+nobinonly
prthread.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 prthread_h___
00039 #define prthread_h___
00040 
00041 /*
00042 ** API for NSPR threads. On some architectures (MAC and WIN16
00043 ** notably) pre-emptibility is not guaranteed. Hard priority scheduling
00044 ** is not guaranteed, so programming using priority based synchronization
00045 ** is a no-no.
00046 **
00047 ** NSPR threads are scheduled based loosely on their client set priority.
00048 ** In general, a thread of a higher priority has a statistically better
00049 ** chance of running relative to threads of lower priority. However,
00050 ** NSPR uses multiple strategies to provide execution vehicles for thread
00051 ** abstraction of various host platforms. As it turns out, there is little
00052 ** NSPR can do to affect the scheduling attributes of "GLOBAL" threads.
00053 ** However, a semblance of GLOBAL threads is used to implement "LOCAL"
00054 ** threads. An arbitrary number of such LOCAL threads can be assigned to
00055 ** a single GLOBAL thread.
00056 **
00057 ** For scheduling, NSPR will attempt to run the highest priority LOCAL
00058 ** thread associated with a given GLOBAL thread. It is further assumed
00059 ** that the host OS will apply some form of "fair" scheduling on the
00060 ** GLOBAL threads.
00061 **
00062 ** Threads have a "system flag" which when set indicates the thread
00063 ** doesn't count for determining when the process should exit (the
00064 ** process exits when the last user thread exits).
00065 **
00066 ** Threads also have a "scope flag" which controls whether the threads
00067 ** are scheduled in the local scope or scheduled by the OS globally. This 
00068 ** indicates whether a thread is permanently bound to a native OS thread. 
00069 ** An unbound thread competes for scheduling resources in the same process.
00070 **
00071 ** Another flag is "state flag" which control whether the thread is joinable.
00072 ** It allows other threads to wait for the created thread to reach completion.
00073 **
00074 ** Threads can have "per-thread-data" attached to them. Each thread has a
00075 ** per-thread error number and error string which are updated when NSPR
00076 ** operations fail.
00077 */
00078 #include "prtypes.h"
00079 #include "prinrval.h"
00080 
00081 PR_BEGIN_EXTERN_C
00082 
00083 typedef struct PRThread PRThread;
00084 typedef struct PRThreadStack PRThreadStack;
00085 
00086 typedef enum PRThreadType {
00087     PR_USER_THREAD,
00088     PR_SYSTEM_THREAD
00089 } PRThreadType;
00090 
00091 typedef enum PRThreadScope {
00092     PR_LOCAL_THREAD,
00093     PR_GLOBAL_THREAD,
00094     PR_GLOBAL_BOUND_THREAD
00095 } PRThreadScope;
00096 
00097 typedef enum PRThreadState {
00098     PR_JOINABLE_THREAD,
00099     PR_UNJOINABLE_THREAD
00100 } PRThreadState;
00101 
00102 typedef enum PRThreadPriority
00103 {
00104     PR_PRIORITY_FIRST = 0,      /* just a placeholder */
00105     PR_PRIORITY_LOW = 0,        /* the lowest possible priority */
00106     PR_PRIORITY_NORMAL = 1,     /* most common expected priority */
00107     PR_PRIORITY_HIGH = 2,       /* slightly more aggressive scheduling */
00108     PR_PRIORITY_URGENT = 3,     /* it does little good to have more than one */
00109     PR_PRIORITY_LAST = 3        /* this is just a placeholder */
00110 } PRThreadPriority;
00111 
00112 /*
00113 ** Create a new thread:
00114 **     "type" is the type of thread to create
00115 **     "start(arg)" will be invoked as the threads "main"
00116 **     "priority" will be created thread's priority
00117 **     "scope" will specify whether the thread is local or global
00118 **     "state" will specify whether the thread is joinable or not
00119 **     "stackSize" the size of the stack, in bytes. The value can be zero
00120 **        and then a machine specific stack size will be chosen.
00121 **
00122 ** This can return NULL if some kind of error occurs, such as if memory is
00123 ** tight.
00124 **
00125 ** If you want the thread to start up waiting for the creator to do
00126 ** something, enter a lock before creating the thread and then have the
00127 ** threads start routine enter and exit the same lock. When you are ready
00128 ** for the thread to run, exit the lock.
00129 **
00130 ** If you want to detect the completion of the created thread, the thread
00131 ** should be created joinable.  Then, use PR_JoinThread to synchrnoize the
00132 ** termination of another thread.
00133 **
00134 ** When the start function returns the thread exits. If it is the last
00135 ** PR_USER_THREAD to exit then the process exits.
00136 */
00137 NSPR_API(PRThread*) PR_CreateThread(PRThreadType type,
00138                      void (PR_CALLBACK *start)(void *arg),
00139                      void *arg,
00140                      PRThreadPriority priority,
00141                      PRThreadScope scope,
00142                      PRThreadState state,
00143                      PRUint32 stackSize);
00144 
00145 /*
00146 ** Wait for thread termination:
00147 **     "thread" is the target thread 
00148 **
00149 ** This can return PR_FAILURE if no joinable thread could be found 
00150 ** corresponding to the specified target thread.
00151 **
00152 ** The calling thread is blocked until the target thread completes.
00153 ** Several threads cannot wait for the same thread to complete; one thread
00154 ** will operate successfully and others will terminate with an error PR_FAILURE.
00155 ** The calling thread will not be blocked if the target thread has already
00156 ** terminated.
00157 */
00158 NSPR_API(PRStatus) PR_JoinThread(PRThread *thread);
00159 
00160 /*
00161 ** Return the current thread object for the currently running code.
00162 ** Never returns NULL.
00163 */
00164 NSPR_API(PRThread*) PR_GetCurrentThread(void);
00165 #ifndef NO_NSPR_10_SUPPORT
00166 #define PR_CurrentThread() PR_GetCurrentThread() /* for nspr1.0 compat. */
00167 #endif /* NO_NSPR_10_SUPPORT */
00168 
00169 /*
00170 ** Get the priority of "thread".
00171 */
00172 NSPR_API(PRThreadPriority) PR_GetThreadPriority(const PRThread *thread);
00173 
00174 /*
00175 ** Change the priority of the "thread" to "priority".
00176 */
00177 NSPR_API(void) PR_SetThreadPriority(PRThread *thread, PRThreadPriority priority);
00178 
00179 /*
00180 ** This routine returns a new index for per-thread-private data table. 
00181 ** The index is visible to all threads within a process. This index can 
00182 ** be used with the PR_SetThreadPrivate() and PR_GetThreadPrivate() routines 
00183 ** to save and retrieve data associated with the index for a thread.
00184 **
00185 ** Each index is associationed with a destructor function ('dtor'). The function
00186 ** may be specified as NULL when the index is created. If it is not NULL, the
00187 ** function will be called when:
00188 **      - the thread exits and the private data for the associated index
00189 **        is not NULL,
00190 **      - new thread private data is set and the current private data is
00191 **        not NULL.
00192 **
00193 ** The index independently maintains specific values for each binding thread. 
00194 ** A thread can only get access to its own thread-specific-data.
00195 **
00196 ** Upon a new index return the value associated with the index for all threads
00197 ** is NULL, and upon thread creation the value associated with all indices for 
00198 ** that thread is NULL. 
00199 **
00200 ** Returns PR_FAILURE if the total number of indices will exceed the maximun 
00201 ** allowed.
00202 */
00203 typedef void (PR_CALLBACK *PRThreadPrivateDTOR)(void *priv);
00204 
00205 NSPR_API(PRStatus) PR_NewThreadPrivateIndex(
00206     PRUintn *newIndex, PRThreadPrivateDTOR destructor);
00207 
00208 /*
00209 ** Define some per-thread-private data.
00210 **     "tpdIndex" is an index into the per-thread private data table
00211 **     "priv" is the per-thread-private data 
00212 **
00213 ** If the per-thread private data table has a previously registered
00214 ** destructor function and a non-NULL per-thread-private data value,
00215 ** the destructor function is invoked.
00216 **
00217 ** This can return PR_FAILURE if the index is invalid.
00218 */
00219 NSPR_API(PRStatus) PR_SetThreadPrivate(PRUintn tpdIndex, void *priv);
00220 
00221 /*
00222 ** Recover the per-thread-private data for the current thread. "tpdIndex" is
00223 ** the index into the per-thread private data table. 
00224 **
00225 ** The returned value may be NULL which is indistinguishable from an error 
00226 ** condition.
00227 **
00228 ** A thread can only get access to its own thread-specific-data.
00229 */
00230 NSPR_API(void*) PR_GetThreadPrivate(PRUintn tpdIndex);
00231 
00232 /*
00233 ** This routine sets the interrupt request for a target thread. The interrupt
00234 ** request remains in the thread's state until it is delivered exactly once
00235 ** or explicitly canceled.
00236 **
00237 ** A thread that has been interrupted will fail all NSPR blocking operations
00238 ** that return a PRStatus (I/O, waiting on a condition, etc).
00239 **
00240 ** PR_Interrupt may itself fail if the target thread is invalid.
00241 */
00242 NSPR_API(PRStatus) PR_Interrupt(PRThread *thread);
00243 
00244 /*
00245 ** Clear the interrupt request for the calling thread. If no such request
00246 ** is pending, this operation is a noop.
00247 */
00248 NSPR_API(void) PR_ClearInterrupt(void);
00249 
00250 /*
00251 ** Block the interrupt for the calling thread.
00252 */
00253 NSPR_API(void) PR_BlockInterrupt(void);
00254 
00255 /*
00256 ** Unblock the interrupt for the calling thread.
00257 */
00258 NSPR_API(void) PR_UnblockInterrupt(void);
00259 
00260 /*
00261 ** Make the current thread sleep until "ticks" time amount of time
00262 ** has expired. If "ticks" is PR_INTERVAL_NO_WAIT then the call is
00263 ** equivalent to calling PR_Yield. Calling PR_Sleep with an argument
00264 ** equivalent to PR_INTERVAL_NO_TIMEOUT is an error and will result
00265 ** in a PR_FAILURE error return.
00266 */
00267 NSPR_API(PRStatus) PR_Sleep(PRIntervalTime ticks);
00268 
00269 /*
00270 ** Get the scoping of this thread.
00271 */
00272 NSPR_API(PRThreadScope) PR_GetThreadScope(const PRThread *thread);
00273 
00274 /*
00275 ** Get the type of this thread.
00276 */
00277 NSPR_API(PRThreadType) PR_GetThreadType(const PRThread *thread);
00278 
00279 /*
00280 ** Get the join state of this thread.
00281 */
00282 NSPR_API(PRThreadState) PR_GetThreadState(const PRThread *thread);
00283 
00284 PR_END_EXTERN_C
00285 
00286 #endif /* prthread_h___ */