From 36d22d82aa202bb199967e9512281e9a53db42c9 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 21:33:14 +0200 Subject: Adding upstream version 115.7.0esr. Signed-off-by: Daniel Baumann --- docs/nspr/about_nspr.rst | 154 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 docs/nspr/about_nspr.rst (limited to 'docs/nspr/about_nspr.rst') diff --git a/docs/nspr/about_nspr.rst b/docs/nspr/about_nspr.rst new file mode 100644 index 0000000000..622bdeac52 --- /dev/null +++ b/docs/nspr/about_nspr.rst @@ -0,0 +1,154 @@ +About NSPR +========== + +NetScape Portable Runtime (NSPR) provides platform independence for +non-GUI operating system facilities. These facilities include threads, +thread synchronization, normal file and network I/O, interval timing and +calendar time, basic memory management (malloc and free) and shared +library linking. + +History +~~~~~~~ + +A good portion of the library's purpose, and perhaps the primary purpose +in the Gromit environment, was to provide the underpinnings of the Java +VM, more or less mapping the *sys layer* that Sun defined for the +porting of the Java VM to various platforms. NSPR went beyond that +requirement in some areas and since it was also the platform independent +layer for most of the servers produced by Netscape. It was expected and +preferred that existing code be restructured and perhaps even rewritten +in order to use the NSPR API. It is not a goal to provide a platform for +the porting into Netscape of externally developed code. + +At the time of writing the current generation of NSPR was known as +NSPR20. The first generation of NSPR was originally conceived just to +satisfy the requirements of porting Java to various host environments. +NSPR20, an effort started in 1996, built on that original idea, though +very little is left of the original code. (The "20" in "NSPR20" does not +mean "version 2.0" but rather "second generation".) Many of the concepts +have been reformed, expanded, and matured. Today NSPR may still be +appropriate as the platform dependent layer under Java, but its primary +application is supporting clients written entirely in C or C++. + +.. _How_It_Works: + +How It Works +~~~~~~~~~~~~ + +NSPR's goal is to provide uniform service over a wide range of operating +system environments. It strives to not export the *lowest common +denominator*, but to exploit the best features of each operating system +on which it runs, and still provide a uniform service across a wide +range of host offerings. + +Threads +^^^^^^^ + +Threads are the major feature of NSPR. The industry's offering of +threads is quite sundry. NSPR, while far from perfect, does provide a +single API to which clients may program and expect reasonably consistent +behavior. The operating systems provide everything from no concept of +threading at all up to and including sophisticated, scalable and +efficient implementations. NSPR makes as much use of what the systems +offer as it can. It is a goal of NSPR that NSPR impose as little +overhead as possible in accessing those appropriate system features. + +.. _Thread_synchronization: + +Thread synchronization +^^^^^^^^^^^^^^^^^^^^^^ + +Thread synchronization is loosely based on Monitors as described by +C.A.R. Hoare in *Monitors: An operating system structuring concept* , +Communications of the ACM, 17(10), October 1974 and then formalized by +Xerox' Mesa programming language ("Mesa Language Manual", J.G. Mitchell +et al, Xerox PARC, CSL-79-3 (Apr 1979)). This mechanism provides the +basic mutual exclusion (mutex) and thread notification facilities +(condition variables) implemented by NSPR. Additionally, NSPR provides +synchronization methods more suited for use by Java. The Java-like +facilities include monitor *reentrancy*, implicit and tightly bound +notification capabilities with the ability to associate the +synchronization objects dynamically. + +.. _I.2FO: + +I/O +^^^ + +NSPR's I/O is a slightly augmented BSD sockets model that allows +arbitrary layering. It was originally intended to export synchronous I/O +methods only, relying on threads to provide the concurrency needed for +complex applications. That method of operation is preferred though it is +possible to configure the network I/O channels as *non-blocking* in the +traditional sense. + +.. _Network_addresses: + +Network addresses +^^^^^^^^^^^^^^^^^ + +Part of NSPR deals with manipulation of network addresses. NSPR defines +a network address object that is Internet Protocol (IP) centric. While +the object is not declared as opaque, the API provides methods that +allow and encourage clients to treat the addresses as polymorphic items. +The goal in this area is to provide a migration path between IPv4 and +IPv6. To that end it is possible to perform translations of ASCII +strings (DNS names) into NSPR's network address structures, with no +regard to whether the addressing technology is IPv4 or IPv6. + +Time +^^^^ + +Timing facilities are available in two forms: interval timing and +calendar functions. + +Interval timers are based on a free running, 32-bit, platform dependent +resolution timer. Such timers are normally used to specify timeouts on +I/O, waiting on condition variables and other rudimentary thread +scheduling. Since these timers have finite namespace and are free +running, they can wrap at any time. NSPR does not provide an *epoch* , +but expects clients to deal with that issue. The *granularity* of the +timers is guaranteed to be between 10 microseconds and 1 millisecond. +This allows a minimal timer *period* in of approximately 12 hours. But +in order to deal with the wrap-around issue, only half that namespace +may be utilized. Therefore, the minimal usable interval available from +the timers is slightly less than six hours. + +Calendar times are 64-bit signed numbers with units of microseconds. The +*epoch* for calendar times is midnight, January 1, 1970, Greenwich Mean +Time. Negative times extend to times before 1970, and positive numbers +forward. Use of 64 bits allows a representation of times approximately +in the range of -30000 to the year 30000. There is a structural +representation (*i.e., exploded* view), routines to acquire the current +time from the host system, and convert them to and from the 64-bit and +structural representation. Additionally there are routines to convert to +and from most well-known forms of ASCII into the 64-bit NSPR +representation. + +.. _Memory_management: + +Memory management +^^^^^^^^^^^^^^^^^ + +NSPR provides API to perform the basic malloc, calloc, realloc and free +functions. Depending on the platform, the functions may be implemented +almost entirely in the NSPR runtime or simply shims that call +immediately into the host operating system's offerings. + +Linking +^^^^^^^ + +Support for linking (shared library loading and unloading) is part of +NSPR's feature set. In most cases this is simply a smoothing over of the +facilities offered by the various platform providers. + +Where It's Headed +~~~~~~~~~~~~~~~~~ + +NSPR is applicable as a platform on which to write threaded applications +that need to be ported to multiple platforms. + +NSPR is functionally complete and has entered a mode of sustaining +engineering. As operating system vendors issue new releases of their +operating systems, NSPR will be moved forward to these new releases by +interested players. -- cgit v1.2.3