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.



 
 

NSPR 3.0 Release

Oct-6-98
 

Table of Contents

  1. Introduction
  2. What's New
  3. Library Version Specification
  4. Platforms
  5. Compatibility
  6. Release Components
  7. Test Data
  8. Reporting bugs
  9. Building from source
  10. Contact Info

1. Introduction

The release 3.0 of nspr is now available at /m/dist/nspr20/v3.0. This release is binary compatible with the 0529B release of nspr.

2. What's New

Several new cross-platform and platform-specific features are available in this release, in addition to bug fixes.

1.1 New functions and features

1. Automatic attachment of native threads
With this feature, native threads created directly by the application can call nspr functions without the need for calling PR_AttachThread/PR_DetachThread.
2.  HP-UX 64-bit version
For the HP-UX 11.0, a second version of nspr with 64-bit support is available.
3. Digitial Unix 64-bit version
The nspr library is no longer compiled/linked with the -taso option, which limited the address space to 32 bits.
4. Multiwait enhancements on NT
On NT, the multiwait functions now call NT asynchronous I/O functions instead of PR_Poll.
5. Instrumentation (counters and tracing)
A new set of interfaces for defining and managing counters and another set for event tracing are available.
6. Version specification
A library version specification scheme is implemented in nspr. A function interface and a data structure to obtain the library's version information are exported.
7. Reader/writer locks
Reader/writer locks are now available, in addition to the existing mutually-exclusive locks in libnspr, in a new library, libnsps. This library is not subject to NPL/MPL requirements and should not be used in the open source projects on mozilla.org.
8. Atomic stacks
A new set of functions is available for creation and use of thread-safe stacks. These functions are, typically, useful for managing lists of free resources and are optimized to use atomic processor instructions, where available, in place of general purpose locks..
9. FD caching
The file descriptor caching is now done using atomic stacks, for faster performance.

1.2 Bug fixes

Several bugs are fixed in this release.

1.3 New library component

There is a new component library,  libnsps, in this release. This component will contain services that are supported only on server platforms,  is built on top of nspr and is not subject to the requirements of the Netscape Public License (NPL) or the Mozilla Public License (MPL). Currently, only the reader/writer lock functions are defined in this library.

1.4 Obsolete Features

1. The PRSegment functions have been deleted because they have no users and they are of limited use.

2. The library exporting the garbage-collector functions, libmsgc, is no longer shipped.

3. Library Version Specification

The current scheme of naming nspr20 releases after the date of the release is dropped. A new version specification scheme is used to label the nspr20 release with a 3 digit number, of the form X.Y.Z. The first digit refers to the major release, the second one to the minor release and the third one to the patch number. An increase in the minor release implies addition of bug fixes and features, while binary compatibility is maintained. An increase in the major number implies a, potentially, incompatible release. For a given major and minor release number, an increase in the patch number implies addition of bug fixes, but no major new features, while retaining binary compatibility.

The nspr library exports a function, libVersionPoint, that can be called to retrieve the version of the library. At runtime clients of nspr can call this function to check for version compatibility.  The function and data prototypes are available for other libraries to provide similar version information. The version information for the library is also available as a global symbol, prVersionDescription_libnsrp21.

4. Platforms

The set of supported platforms is listed in the following table. For most platforms, a single release of the nspr library is used to support all the current releases of the OS.
 

Platform

Release Build/Name

Certified OS releases

Compiler/options

Solaris 2.5.1 
SunOS5.5.1_sparc_PTH_OPT.OBJ 
2.5.1 
2.6
Sun WorkShop 4.2
Irix (pthreads) 
(default)
6.2 
IRIX6.2_n32_PTH_OPT.OBJ 
 
6.2 
6.3 
6.4
MIPS Pro 7.2.1/-n32
Irix (sprocs) 6.2 
IRIX6.2_o32_MxN_OPT.OBJ 
 
6.2 
6.3 
6.4
MIPS Pro 7.2.1
AIX 4.2 
AIX4.2_PTH_OPT.OBJ
4.2 
4.3
xlC_r 3.1.4
Digital Unix 4.0D 
OSF1V4.0D_PTH_OPT.OBJ
4.0D cc
HP-UX 10.10 
HP-UXB.10.10_PTH_OPT.OBJ
10.10 
10.20
cc
HP-UX (pthreads) 
(default)
11.0 
HP-UXB.11.00_32_PTH_OPT.OBJ
11.0 cc
HP-UX (64-bit) 11.0 
HP-UXB.11.00_64_PTH_OPT.OBJ
11.0 cc
Linux (Redhat) 5.1 
Linux2.0.32_x86_PTH_OPT.OBJ
5.1 gcc 2.7.2.3
Windows NT 4.0 
WINNT4.0_OPT.OBJ
4.0 (SP3) VC++ 4.2
Windows 95 Win 95 
WIN954.0_OPT.OBJ
Win 95 
Win 98 
Win NT 3.51 
Win NT 4.0
VC++ 4.2
 
Important changes to note are:

1. Irix

The pthreads-based (n32) version of nspr is now the default. The sproc-based version (o32) will also be available in this release, but will not be supported in future releases.
2. Solaris
The pthreads-based version is the default and the only version available. Pthreads and Solaris threads are compatible on Solaris. To use purify on Solaris, libpthread should be explicitly specified in the list of libraries passed to the linker, ahead of other system libraries such as -lposix4, -lsocket, -ldl, etc,.
3. HP-UX
A 64-bit version of nspr is also available for HP-UX 11.0.
4. Digital Unix
The nspr library is now built/linked without the -taso option; this means addresses beyond the 32-bit limit may be used.

5. Compatibility

The beta release 3.0 of nspr is both source code and binary compatible with the 19980529B release of nspr.

For the nspr library, binary compatibility does not preclude the addition of new error codes to the set of nspr error codes already defined. An application should allow for nspr functions returning error codes not documented for the particular release with which it is linked. This helps to retain backward compatibility as new error codes are added upon discovery of new information about platform-specific error codes.

6. Release Components

The main components of this release are a set of shared libraries and header files for each platform. A debug build and a release (optimized) build of the libraries are made available for each platform.

6.1 Platform Directory

The platform-dependent name of the directory where the components are placed is of the form

  <os-name><os-version>[_<compiler>][cpu-arch][_<implementation strategy>]_<DBG/OPT>.OBJ

  For example,
      IRIX6.2_DBG.OBJ (debug build)
      SunOS5.5.1_PTH_OPT.OBJ (optimized build)
      IRIX6.2_n32_PTH_DBG.OBJ (built using the -n32 compiler option,
              pthreads implementation strategy)

6.2 Implementation Strategy

For the implementation of nspr, different strategies are used on  different platforms. On some platforms the nspr threads map directly to the native threads on the platform, while on others nspr supports both threads that are scheduled by nspr and the native threads.
 
 The default implementation strategies in this release are:
  - pthreads: all Unix platforms
  - classic: Win NT (combined MxN model, with Windows threads and fibers)
  - native threads: Win95

6.3 Components

Under each <platform> directory, there are:

1. include directory, containing the  header files
2. lib directory, containing the libraries. Three libraries are built on all platforms: nspr, plc, plds. Three other
    libraries are built on server platforms only: ares, prstrms and nsps.  Static, shared (dynamic link), and purified
    (for a subset of platforms) versions of the libraries are built.

The nspr library exports the core nspr20 functions.

The plc (Portable Library C) library is a separate library from  the core nspr20.  You do
not need to use plc if you just want to use the core nspr20 functions.  The plc library currently
contains thread-safe  string functions and command-line option functions.

The plds (Portable Library Data Structures) library supports data structures such as arenas, hash tables, and event queues.  It is important to note that services of  plds are not thread-safe. To use these services in a multi-threaded environment, clients have to implement their own thread-safe access, by acquiring locks/monitors, for example.

The nsps library (libnsps) exports services that are supported only for the server platforms. These services are built on top of nspr and are not subject to the Netscape Public License(NPL)/Mozilla Public License(MPL) requirements.

For Solaris platforms with UltraSparc processors only, a platform-specific library, libultrasparc, is also supplied. This library implements optimized versions of atomic operations by using the features present in the UltraSparc (V9) processors, but not in the Sparc (V8) processors.  This library is linked into libnspr, with the name libatomic, by use of the auxiliary filter mechanism of the Solaris linker. To use this library at runtime, on UltraSparc systems,  libultrasparc21.so should be copied into a file named libatomic.so and the new file should be present in the path searched by the linker.

3. mdheader.jar, jar file for the header files.
4. mdbinary.jar,  jar for the libraries.

7. Test Data

All the major functional areas of nspr were tested using the programs in the nspr test suite. Both functional and stress tests in the pr/tests directory were successfully run on multi-processor systems for all platforms, except for Win95.

7.1 Runtime Error Detection

A subset of the test programs were run successfully on Solaris and Windows NT (both Win95 and Win NT versions) with the purify program.

7.2 Code Coverage

The purecoverage (v4.2) tool was used to measure code coverage during functional testing on Solaris 2.5.1. The coverage data is summarized in the following table.
 
Library Functions unused used used % Lines unused used used %
libnspr21.so 271 408 60% 4274 4798 52%
 
The same set of tests were run on all the platforms.

 8. Reporting bugs

Bugs discovered should be reported by filing a report in Bugsplat. The following information is required
  • platform (Solaris 2.5.1, HP-UX 11.0, etc.)
  • number of cpus in the system
  • a trace stack, in the event of a crash
  • reproducibility of the problem
  • location of core dump, if available, along with those for the libraries and executables

 9. Building from source

This release is built from the source, at the CVS repository rooted at /m/src, with the CVS tag
NSPR20_RELEASE_3_0.  You can check out the source from CVS by
    cvs co -r NSPR20_RELEASE_3_0 ns/nspr20

To build, do
    cd ns/nspr20
    gmake export

10. Contact Info

http://warp/projects/hardcore/prj-nspr20  - nspr20 home page
nsprgroup   - the nspr team
nspr20eng  - mailing list for nspr20 developers
nspr20clients - mailing list for nspr20 clients
netscape.public.mozilla.nspr  - nspr newsgroup at mozilla.org