NSPR Reference: Chapter 4 Process Initialization
Description: The Sun-Netscape Alliance, a strategic alliance formed by America Online and Sun Microsystems, Inc., is delivering iPlanet e-commerce software and enterprise solutions that enable companies to compete successfully in the Net Economy
Keywords: electronic commerce, ecommerce, ebusiness, e-business, e-commerce, enterprise software, net economy, Netscape, Sun Microsystems, Sun-Netscape Alliance, iPlanet, internet software

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

`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