Back to index

lightning-sunbird  0.9+nobinonly
prinit.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 prinit_h___
00039 #define prinit_h___
00040 
00041 #include "prthread.h"
00042 #include "prtypes.h"
00043 #include "prwin16.h"
00044 #include <stdio.h>
00045 
00046 PR_BEGIN_EXTERN_C
00047 
00048 /************************************************************************/
00049 /**************************IDENTITY AND VERSIONING***********************/
00050 /************************************************************************/
00051 
00052 /*
00053 ** NSPR's name, this should persist until at least the turn of the
00054 ** century.
00055 */
00056 #define PR_NAME     "NSPR"
00057 
00058 /*
00059 ** NSPR's version is used to determine the likelihood that the version you
00060 ** used to build your component is anywhere close to being compatible with
00061 ** what is in the underlying library.
00062 **
00063 ** The format of the version string is
00064 **     "<major version>.<minor version>[.<patch level>] [<Beta>]"
00065 */
00066 #define PR_VERSION  "4.6.8"
00067 #define PR_VMAJOR   4
00068 #define PR_VMINOR   6
00069 #define PR_VPATCH   8
00070 #define PR_BETA     PR_FALSE
00071 
00072 /*
00073 ** PRVersionCheck
00074 **
00075 ** The basic signature of the function that is called to provide version
00076 ** checking. The result will be a boolean that indicates the likelihood
00077 ** that the underling library will perform as the caller expects.
00078 **
00079 ** The only argument is a string, which should be the verson identifier
00080 ** of the library in question. That string will be compared against an
00081 ** equivalent string that represents the actual build version of the
00082 ** exporting library.
00083 **
00084 ** The result will be the logical union of the directly called library
00085 ** and all dependent libraries.
00086 */
00087 
00088 typedef PRBool (*PRVersionCheck)(const char*);
00089 
00090 /*
00091 ** PR_VersionCheck
00092 **
00093 ** NSPR's existance proof of the version check function.
00094 **
00095 ** Note that NSPR has no cooperating dependencies.
00096 */
00097 
00098 NSPR_API(PRBool) PR_VersionCheck(const char *importedVersion);
00099 
00100 
00101 /************************************************************************/
00102 /*******************************INITIALIZATION***************************/
00103 /************************************************************************/
00104 
00105 /*
00106 ** Initialize the runtime. Attach a thread object to the currently
00107 ** executing native thread of type "type".
00108 **
00109 ** The specificaiton of 'maxPTDs' is ignored.
00110 */
00111 NSPR_API(void) PR_Init(
00112     PRThreadType type, PRThreadPriority priority, PRUintn maxPTDs);
00113 
00114 /*
00115 ** And alternate form of initialization, one that may become the default if
00116 ** not the only mechanism, provides a method to get the NSPR runtime init-
00117 ** ialized and place NSPR between the caller and the runtime library. This
00118 ** allows main() to be treated as any other thread root function, signalling
00119 ** its compeletion by returning and allowing the runtime to coordinate the
00120 ** completion of the other threads of the runtime.
00121 **
00122 ** The priority of the main (or primordial) thread will be PR_PRIORITY_NORMAL.
00123 ** The thread may adjust its own priority by using PR_SetPriority(), though
00124 ** at this time the support for priorities is somewhat weak.
00125 **
00126 ** The specificaiton of 'maxPTDs' is ignored.
00127 **
00128 ** The value returned by PR_Initialize is the value returned from the root
00129 ** function, 'prmain'.
00130 */
00131 
00132 typedef PRIntn (PR_CALLBACK *PRPrimordialFn)(PRIntn argc, char **argv);
00133 
00134 NSPR_API(PRIntn) PR_Initialize(
00135     PRPrimordialFn prmain, PRIntn argc, char **argv, PRUintn maxPTDs);
00136 
00137 /*
00138 ** Return PR_TRUE if PR_Init has already been called.
00139 */
00140 NSPR_API(PRBool) PR_Initialized(void);
00141 
00142 /*
00143  * Perform a graceful shutdown of NSPR.  PR_Cleanup() may be called by
00144  * the primordial thread near the end of the main() function.
00145  *
00146  * PR_Cleanup() attempts to synchronize the natural termination of
00147  * process.  It does that by blocking the caller, if and only if it is
00148  * the primordial thread, until the number of user threads has dropped
00149  * to zero.  When the primordial thread returns from main(), the process
00150  * will immediately and silently exit.  That is, it will (if necessary)
00151  * forcibly terminate any existing threads and exit without significant
00152  * blocking and there will be no error messages or core files.
00153  *
00154  * PR_Cleanup() returns PR_SUCCESS if NSPR is successfully shutdown,
00155  * or PR_FAILURE if the calling thread of this function is not the
00156  * primordial thread.
00157  */
00158 NSPR_API(PRStatus) PR_Cleanup(void);
00159 
00160 /*
00161 ** Disable Interrupts
00162 **            Disables timer signals used for pre-emptive scheduling.
00163 */
00164 NSPR_API(void) PR_DisableClockInterrupts(void);
00165 
00166 /*
00167 ** Enables Interrupts
00168 **            Enables timer signals used for pre-emptive scheduling.
00169 */
00170 NSPR_API(void) PR_EnableClockInterrupts(void);
00171 
00172 /*
00173 ** Block Interrupts
00174 **            Blocks the timer signal used for pre-emptive scheduling
00175 */
00176 NSPR_API(void) PR_BlockClockInterrupts(void);
00177 
00178 /*
00179 ** Unblock Interrupts
00180 **            Unblocks the timer signal used for pre-emptive scheduling
00181 */
00182 NSPR_API(void) PR_UnblockClockInterrupts(void);
00183 
00184 /*
00185 ** Create extra virtual processor threads. Generally used with MP systems.
00186 */
00187 NSPR_API(void) PR_SetConcurrency(PRUintn numCPUs);
00188 
00189 /*
00190 ** Control the method and size of the file descriptor (PRFileDesc*)
00191 ** cache used by the runtime. Setting 'high' to zero is for performance,
00192 ** any other value probably for debugging (see memo on FD caching).
00193 */
00194 NSPR_API(PRStatus) PR_SetFDCacheSize(PRIntn low, PRIntn high);
00195 
00196 /*
00197  * Cause an immediate, nongraceful, forced termination of the process.
00198  * It takes a PRIntn argument, which is the exit status code of the
00199  * process.
00200  */
00201 NSPR_API(void) PR_ProcessExit(PRIntn status);
00202 
00203 /*
00204 ** Abort the process in a non-graceful manner. This will cause a core file,
00205 ** call to the debugger or other moral equivalent as well as causing the
00206 ** entire process to stop.
00207 */
00208 NSPR_API(void) PR_Abort(void);
00209 
00210 /*
00211  ****************************************************************
00212  *
00213  * Module initialization:
00214  *
00215  ****************************************************************
00216  */
00217 
00218 typedef struct PRCallOnceType {
00219     PRIntn initialized;
00220     PRInt32 inProgress;
00221     PRStatus status;
00222 } PRCallOnceType;
00223 
00224 typedef PRStatus (PR_CALLBACK *PRCallOnceFN)(void);
00225 
00226 typedef PRStatus (PR_CALLBACK *PRCallOnceWithArgFN)(void *arg);
00227 
00228 NSPR_API(PRStatus) PR_CallOnce(
00229     PRCallOnceType *once,
00230     PRCallOnceFN    func
00231 );
00232 
00233 NSPR_API(PRStatus) PR_CallOnceWithArg(
00234     PRCallOnceType      *once,
00235     PRCallOnceWithArgFN  func,
00236     void                *arg
00237 );
00238 
00239 
00240 PR_END_EXTERN_C
00241 
00242 #endif /* prinit_h___ */