1 files changed, 154 insertions, 0 deletions
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.