You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

NSPR Reference
Previous     Contents     Next     

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:

  • If the version of the shared library is compatible with that expected by the caller, PR_TRUE.

  • If the versions are not compatible, PR_FALSE.


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
NSPR is now implicitly initialized, usually by the first NSPR function called by a program. 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:

  • If PR_Init has already been called, PR_TRUE

  • If PR_Init has not already been called, PR_FALSE.

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:

  • If NSPR has been shut down successfully, PR_SUCCESS.

  • If the calling thread of this function is not the primordial thread, PR_FAILURE.


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.

Previous     Contents     Next     

Last Updated May 18, 2001