The Mozilla
Organization
At A Glance
Feedback
Get Involved
Newsgroups
License Terms
Newsbot
Developer Docs
Roadmap
Projects
Ports
Module Owners
Hacking
Get the Source
Build It
Testing
Download
Bugzilla
Bug Writing
Tools
View Source
Tree Status
New Checkins
Submit A Bug
FAQ
Search
 [Contents] [Previous] [Next] [Last]

Chapter 4
Process Initialization

This chapter describes the NSPR API for versioning, process initialization, and shutdown of NSPR.

Identity and Versioning
Initialization and Cleanup
Module Initialization

Identity and Versioning

Name and Version Constants
Syntax
 
#include <prinit.h>
 
#define PR_NAME "NSPR"
 
#define PR_VERSION "2.1 yyyymmdd"
 
typedef PRBool (*PRVersionCheck)(const char*);
Description
 The format of the version string is MajorVersion.MinorVersion BuildDate.

PR_VersionCheck

Compares the version of NSPR assumed by the caller (the imported version) with the version being offered by the runtime (the exported version).

Syntax
#include <prinit.h>
 
PRBool PR_VersionCheck(const char *importedVersion);
Parameter
 PR_VersionCheck has one parameter:

importedVersion
 The version of the shared library being imported.

Returns
The function returns one of the following values:

Description
 PR_VersionCheck tests whether the version of the library being imported (importedVersion) is compatible with the running version of the shared library. This is a string comparison of sorts, though the details of the comparison will vary over time.

Initialization and Cleanup

NSPR detects whether the library has been initialized and performs implicit initialization if it hasn't. Implicit initialization should suffice unless a program has specific sequencing requirements or needs to characterize the primordial thread. Explicit initialization is rarely necessary.

Implicit initialization assumes that the initiator is the primordial thread and that the thread is a user thread of normal priority.

PR_Init
PR_Initialize
PR_Initialized
PR_Cleanup
PR_DisableClockInterrupts
PR_BlockClockInterrupts
PR_UnblockClockInterrupts
PR_SetConcurrency
PR_ProcessExit
PR_Abort

PR_Init

Initializes the runtime.

Syntax
#include <prinit.h>
 
void PR_Init(
    PRThreadType type, 
    PRThreadPriority priority, 
    PRUintn maxPTDs);
Parameters
 PR_Init has these parameters:

type
 This parameter is ignored.

priority
 Assigns a priority to the primordial thread.

maxPTDs
 This parameter is ignored.

Description
PR_Init is necessary only if a program has specific initialization-sequencing requirements.

PR_Initialize

Provides an alternate form of explicit initialization. In addition to establishing the sequence of operations, PR_Initialize implicitly calls PR_Cleanup on exiting the primordial function.

Syntax
#include <prinit.h>
 
PRIntn PR_Initialize(
    PRPrimordialFn prmain, 
    PRIntn argc, 
    char **argv, 
    PRUintn maxPTDs);
Parameters
 PR_Initialize has these parameters:

prmain
 The function that becomes the primordial thread's root function. Returning from prmain leads to termination of the process. 

argc
 The length of the argument vector, whether passed in from the host's program-launching facility or fabricated by the actual main program. This approach conforms to standard C programming practice. 

argv
 The base address of an array of strings that compromise the program's argument vector. This approach conforms to standard C programming practice.

maxPTDs
 This parameter is ignored.

Returns
The value returned from the root function, prmain.

Description
PR_Initialize initializes the NSPR runtime and places NSPR between the caller and the runtime library. This allows main to be treated like any other function, signaling its completion by returning and allowing the runtime to coordinate the completion of the other threads of the runtime.

PR_Initialize does not return to its caller until all user threads have terminated.

The type for the root function is specified as follows:

typedef PRIntn (PR_CALLBACK *PRPrimordialFn)(PRIntn argc, char **argv);
The priority of the main (or primordial) thread is PR_PRIORITY_NORMAL. The thread may adjust its own priority by using PR_SetThreadPriority.

PR_Initialized

Checks whether the runtime has been initialized.

Syntax
#include <prinit.h>
 
PRBool PR_Initialized(void);
Returns
 The function returns one of the following values:

PR_Cleanup

 Coordinates a graceful shutdown of NSPR.

Syntax
#include <prinit.h>
 
PRStatus PR_Cleanup(void);
Returns
 The function returns one of the following values:

Description
 PR_Cleanup must be called by the primordial thread near the end of the main function.

PR_Cleanup attempts to synchronize the natural termination of the process. It does so by blocking the caller, if and only if it is the primordial thread, until all user threads have terminated. When the primordial thread returns from main, the process immediately and silently exits. That is, the process (if necessary) forcibly terminates any existing threads and exits without significant blocking and without error messages or core files.

PR_DisableClockInterrupts

Disables timer signals used for preemptive scheduling.

Syntax
#include <prinit.h>
 
void PR_DisableClockInterrupts(void);

PR_BlockClockInterrupts

 Blocks the timer signal used for preemptive scheduling.

Syntax
#include <prinit.h>
 
void PR_BlockClockInterrupts(void);

PR_UnblockClockInterrupts

 Unblocks the timer signal used for preemptive scheduling.

Syntax
#include <prinit.h>
 
void PR_UnblockClockInterrupts(void);

PR_SetConcurrency

 Creates extra virtual processor threads. Generally used with MP systems.

Syntax
#include <prinit.h>
 
void PR_SetConcurrency(PRUintn numCPUs);
Parameter
 PR_SetConcurrency has one parameter:

numCPUs
 The number of extra virtual processor threads to be created.

Description
Setting concurrency controls the number of virtual processors that NSPR uses to implement its M x N threading model. The M x N model is not available on all host systems. On those where it is not available, PR_SetConcurrency is ignored.

Virtual processors are actually global threads, each of which is designed to support an arbitrary number of local threads. Since global threads are scheduled by the host operating system, this model is particularly applicable to multiprocessor architectures, where true parallelism is possible. However, it may also prove advantageous on uniprocessor systems to reduce the impact of having a locally scheduled thread calling incidental blocking functions. In such cases, all the threads being supported by the virtual processor will block, but those assigned to another virtual processor will be unaffected.

PR_ProcessExit

Causes an immediate, nongraceful, forced termination of the process.

Syntax
#include <prinit.h>
 
void PR_ProcessExit(PRIntn status);
Parameter
 PR_ProcessExit has one parameter:

status
 The exit status code of the process.

PR_Abort

Aborts the process in a nongraceful manner.

Syntax
#include <prinit.h>
 
void PR_Abort(void);
Description
 PR_Abort results in a core file and a call to the debugger or equivalent, in addition to causing the entire process to stop.

Module Initialization

Initialization can be tricky in a threaded environment, especially initialization that must happen exactly once. PR_CallOnce ensures that such initialization code is called only once. This facility is recommended in situations where complicated global initialization is required.

PRCallOnce
PRCallOnceFN
PR_CallOnce

PRCallOnce

Structure for tracking initialization.

Syntax
#include <prinit.h>
 
typedef struct PRCallOnceType {
    PRIntn initialized;
    PRInt32 inProgress;
    PRStatus status;
} PRCallOnceType;
Fields
 The structure has these fields:

initialized
 If not zero, the initialization process has been completed.

inProgress
 If not zero, the initialization process is currently being executed. Calling threads that observe this status block until inProgress is zero.

status
 An indication of the outcome of the initialization process.

Description
The client is responsible for initializing the PRCallOnceType structure to all zeros. This initialization must be accomplished before any threading issues exist.

PRCallOnceFN

Defines the signature of the function a client must implement.

Syntax
#include <prinit.h>
 
typedef PRStatus (PR_CALLBACK *PRCallOnceFN)(void);
Description
 The function is called to perform the initialization desired. The function is expected to return a PRStatus indicating the outcome of the process.

PR_CallOnce

Ensures that subsystem initialization occurs only once.

Syntax
PRStatus PR_CallOnce(
    PRCallOnceType *once, 
    PRCallOnceFN func);
Parameters
 PR_CallOnce has these parameters:

once
 A pointer to an object of type PRCallOnceType. Initially (before any threading issues exist), the object must be initialized to all zeros. From that time on, the client should consider the object read-only (or even opaque) and allow the runtime to manipulate its content appropriately. 

func
 A pointer to the function the calling client has designed to perform the subsystem initialization. The function will be called once, at most, for each subsystem to be initialized. It should return a PRStatus indicating the result of the initialization process.

[Contents] [Previous] [Next] [Last]

Last Updated: Mon Jul 13 17:28:35 PDT 1998

Copyright © 1998 Netscape Communications Corporation

Copyright © 1998-1999 The Mozilla Organization.
Last modified July 17, 1998.