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 Mozilla Public
4 * License Version 1.1 (the "License"); you may not use this file
5 * except in compliance with the License. You may obtain a copy of
6 * the License at http://www.mozilla.org/MPL/
7 *
8 * Software distributed under the License is distributed on an "AS
9 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
10 * implied. See the License for the specific language governing
11 * rights and limitations under the License.
12 *
13 * The Original Code is the Netscape Portable Runtime (NSPR).
14 *
15 * The Initial Developer of the Original Code is Netscape
16 * Communications Corporation.  Portions created by Netscape are
17 * Copyright (C) 1998-2000 Netscape Communications Corporation.  All
18 * Rights Reserved.
19 *
20 * Contributor(s):
21 *
22 * Alternatively, the contents of this file may be used under the
23 * terms of the GNU General Public License Version 2 or later (the
24 * "GPL"), in which case the provisions of the GPL are applicable
25 * instead of those above.  If you wish to allow use of your
26 * version of this file only under the terms of the GPL and not to
27 * allow others to use your version of this file under the MPL,
28 * indicate your decision by deleting the provisions above and
29 * replace them with the notice and other provisions required by
30 * the GPL.  If you do not delete the provisions above, a recipient
31 * may use your version of this file under either the MPL or the
32 * GPL.
33 */
34
35#ifndef prinit_h___
36#define prinit_h___
37
38#include "prthread.h"
39#include "prtypes.h"
40#include "prwin16.h"
41#include <stdio.h>
42
43PR_BEGIN_EXTERN_C
44
45/************************************************************************/
46/**************************IDENTITY AND VERSIONING***********************/
47/************************************************************************/
48
49/*
50** NSPR's name, this should persist until at least the turn of the
51** century.
52*/
53#define PR_NAME     "NSPR"
54
55/*
56** NSPR's version is used to determine the likelihood that the version you
57** used to build your component is anywhere close to being compatible with
58** what is in the underlying library.
59**
60** The format of the version string is
61**     "<major version>.<minor version>[.<patch level>] [<Beta>]"
62*/
63#define PR_VERSION  "4.5 Beta"
64#define PR_VMAJOR   4
65#define PR_VMINOR   5
66#define PR_VPATCH   0
67#define PR_BETA     PR_TRUE
68
69/*
70** PRVersionCheck
71**
72** The basic signature of the function that is called to provide version
73** checking. The result will be a boolean that indicates the likelihood
74** that the underling library will perform as the caller expects.
75**
76** The only argument is a string, which should be the verson identifier
77** of the library in question. That string will be compared against an
78** equivalent string that represents the actual build version of the
79** exporting library.
80**
81** The result will be the logical union of the directly called library
82** and all dependent libraries.
83*/
84
85typedef PRBool (*PRVersionCheck)(const char*);
86
87/*
88** PR_VersionCheck
89**
90** NSPR's existance proof of the version check function.
91**
92** Note that NSPR has no cooperating dependencies.
93*/
94
95NSPR_API(PRBool) PR_VersionCheck(const char *importedVersion);
96
97
98/************************************************************************/
99/*******************************INITIALIZATION***************************/
100/************************************************************************/
101
102/*
103** Initialize the runtime. Attach a thread object to the currently
104** executing native thread of type "type".
105**
106** The specificaiton of 'maxPTDs' is ignored.
107*/
108NSPR_API(void) PR_Init(
109    PRThreadType type, PRThreadPriority priority, PRUintn maxPTDs);
110
111/*
112** And alternate form of initialization, one that may become the default if
113** not the only mechanism, provides a method to get the NSPR runtime init-
114** ialized and place NSPR between the caller and the runtime library. This
115** allows main() to be treated as any other thread root function, signalling
116** its compeletion by returning and allowing the runtime to coordinate the
117** completion of the other threads of the runtime.
118**
119** The priority of the main (or primordial) thread will be PR_PRIORITY_NORMAL.
120** The thread may adjust its own priority by using PR_SetPriority(), though
121** at this time the support for priorities is somewhat weak.
122**
123** The specificaiton of 'maxPTDs' is ignored.
124**
125** The value returned by PR_Initialize is the value returned from the root
126** function, 'prmain'.
127*/
128
129typedef PRIntn (PR_CALLBACK *PRPrimordialFn)(PRIntn argc, char **argv);
130
131NSPR_API(PRIntn) PR_Initialize(
132    PRPrimordialFn prmain, PRIntn argc, char **argv, PRUintn maxPTDs);
133
134/*
135** Return PR_TRUE if PR_Init has already been called.
136*/
137NSPR_API(PRBool) PR_Initialized(void);
138
139/*
140 * Perform a graceful shutdown of NSPR.  PR_Cleanup() may be called by
141 * the primordial thread near the end of the main() function.
142 *
143 * PR_Cleanup() attempts to synchronize the natural termination of
144 * process.  It does that by blocking the caller, if and only if it is
145 * the primordial thread, until the number of user threads has dropped
146 * to zero.  When the primordial thread returns from main(), the process
147 * will immediately and silently exit.  That is, it will (if necessary)
148 * forcibly terminate any existing threads and exit without significant
149 * blocking and there will be no error messages or core files.
150 *
151 * PR_Cleanup() returns PR_SUCCESS if NSPR is successfully shutdown,
152 * or PR_FAILURE if the calling thread of this function is not the
153 * primordial thread.
154 */
155NSPR_API(PRStatus) PR_Cleanup(void);
156
157/*
158** Disable Interrupts
159**		Disables timer signals used for pre-emptive scheduling.
160*/
161NSPR_API(void) PR_DisableClockInterrupts(void);
162
163/*
164** Enables Interrupts
165**		Enables timer signals used for pre-emptive scheduling.
166*/
167NSPR_API(void) PR_EnableClockInterrupts(void);
168
169/*
170** Block Interrupts
171**		Blocks the timer signal used for pre-emptive scheduling
172*/
173NSPR_API(void) PR_BlockClockInterrupts(void);
174
175/*
176** Unblock Interrupts
177**		Unblocks the timer signal used for pre-emptive scheduling
178*/
179NSPR_API(void) PR_UnblockClockInterrupts(void);
180
181/*
182** Create extra virtual processor threads. Generally used with MP systems.
183*/
184NSPR_API(void) PR_SetConcurrency(PRUintn numCPUs);
185
186/*
187** Control the method and size of the file descriptor (PRFileDesc*)
188** cache used by the runtime. Setting 'high' to zero is for performance,
189** any other value probably for debugging (see memo on FD caching).
190*/
191NSPR_API(PRStatus) PR_SetFDCacheSize(PRIntn low, PRIntn high);
192
193/*
194 * Cause an immediate, nongraceful, forced termination of the process.
195 * It takes a PRIntn argument, which is the exit status code of the
196 * process.
197 */
198NSPR_API(void) PR_ProcessExit(PRIntn status);
199
200/*
201** Abort the process in a non-graceful manner. This will cause a core file,
202** call to the debugger or other moral equivalent as well as causing the
203** entire process to stop.
204*/
205NSPR_API(void) PR_Abort(void);
206
207/*
208 ****************************************************************
209 *
210 * Module initialization:
211 *
212 ****************************************************************
213 */
214
215typedef struct PRCallOnceType {
216    PRIntn initialized;
217    PRInt32 inProgress;
218    PRStatus status;
219} PRCallOnceType;
220
221typedef PRStatus (PR_CALLBACK *PRCallOnceFN)(void);
222
223typedef PRStatus (PR_CALLBACK *PRCallOnceWithArgFN)(void *arg);
224
225NSPR_API(PRStatus) PR_CallOnce(
226    PRCallOnceType *once,
227    PRCallOnceFN    func
228);
229
230NSPR_API(PRStatus) PR_CallOnceWithArg(
231    PRCallOnceType      *once,
232    PRCallOnceWithArgFN  func,
233    void                *arg
234);
235
236
237PR_END_EXTERN_C
238
239#endif /* prinit_h___ */
240