docs/nspr/about_nspr.rst

   1 About NSPR
   2 ==========
   3
   4 NetScape Portable Runtime (NSPR) provides platform independence for
   5 non-GUI operating system facilities. These facilities include threads,
   6 thread synchronization, normal file and network I/O, interval timing and
   7 calendar time, basic memory management (malloc and free) and shared
   8 library linking.
   9
  10 History
  11 ~~~~~~~
  12
  13 A good portion of the library's purpose, and perhaps the primary purpose
  14 in the Gromit environment, was to provide the underpinnings of the Java
  15 VM, more or less mapping the *sys layer* that Sun defined for the
  16 porting of the Java VM to various platforms. NSPR went beyond that
  17 requirement in some areas and since it was also the platform independent
  18 layer for most of the servers produced by Netscape. It was expected and
  19 preferred that existing code be restructured and perhaps even rewritten
  20 in order to use the NSPR API. It is not a goal to provide a platform for
  21 the porting into Netscape of externally developed code.
  22
  23 At the time of writing the current generation of NSPR was known as
  24 NSPR20. The first generation of NSPR was originally conceived just to
  25 satisfy the requirements of porting Java to various host environments.
  26 NSPR20, an effort started in 1996, built on that original idea, though
  27 very little is left of the original code. (The "20" in "NSPR20" does not
  28 mean "version 2.0" but rather "second generation".) Many of the concepts
  29 have been reformed, expanded, and matured. Today NSPR may still be
  30 appropriate as the platform dependent layer under Java, but its primary
  31 application is supporting clients written entirely in C or C++.
  32
  33 .. _How_It_Works:
  34
  35 How It Works
  36 ~~~~~~~~~~~~
  37
  38 NSPR's goal is to provide uniform service over a wide range of operating
  39 system environments. It strives to not export the *lowest common
  40 denominator*, but to exploit the best features of each operating system
  41 on which it runs, and still provide a uniform service across a wide
  42 range of host offerings.
  43
  44 Threads
  45 ^^^^^^^
  46
  47 Threads are the major feature of NSPR. The industry's offering of
  48 threads is quite sundry. NSPR, while far from perfect, does provide a
  49 single API to which clients may program and expect reasonably consistent
  50 behavior. The operating systems provide everything from no concept of
  51 threading at all up to and including sophisticated, scalable and
  52 efficient implementations. NSPR makes as much use of what the systems
  53 offer as it can. It is a goal of NSPR that NSPR impose as little
  54 overhead as possible in accessing those appropriate system features.
  55
  56 .. _Thread_synchronization:
  57
  58 Thread synchronization
  59 ^^^^^^^^^^^^^^^^^^^^^^
  60
  61 Thread synchronization is loosely based on Monitors as described by
  62 C.A.R. Hoare in *Monitors: An operating system structuring concept* ,
  63 Communications of the ACM, 17(10), October 1974 and then formalized by
  64 Xerox' Mesa programming language ("Mesa Language Manual", J.G. Mitchell
  65 et al, Xerox PARC, CSL-79-3 (Apr 1979)). This mechanism provides the
  66 basic mutual exclusion (mutex) and thread notification facilities
  67 (condition variables) implemented by NSPR. Additionally, NSPR provides
  68 synchronization methods more suited for use by Java. The Java-like
  69 facilities include monitor *reentrancy*, implicit and tightly bound
  70 notification capabilities with the ability to associate the
  71 synchronization objects dynamically.
  72
  73 .. _I.2FO:
  74
  75 I/O
  76 ^^^
  77
  78 NSPR's I/O is a slightly augmented BSD sockets model that allows
  79 arbitrary layering. It was originally intended to export synchronous I/O
  80 methods only, relying on threads to provide the concurrency needed for
  81 complex applications. That method of operation is preferred though it is
  82 possible to configure the network I/O channels as *non-blocking* in the
  83 traditional sense.
  84
  85 .. _Network_addresses:
  86
  87 Network addresses
  88 ^^^^^^^^^^^^^^^^^
  89
  90 Part of NSPR deals with manipulation of network addresses. NSPR defines
  91 a network address object that is Internet Protocol (IP) centric. While
  92 the object is not declared as opaque, the API provides methods that
  93 allow and encourage clients to treat the addresses as polymorphic items.
  94 The goal in this area is to provide a migration path between IPv4 and
  95 IPv6. To that end it is possible to perform translations of ASCII
  96 strings (DNS names) into NSPR's network address structures, with no
  97 regard to whether the addressing technology is IPv4 or IPv6.
  98
  99 Time
 100 ^^^^
 101
 102 Timing facilities are available in two forms: interval timing and
 103 calendar functions.
 104
 105 Interval timers are based on a free running, 32-bit, platform dependent
 106 resolution timer. Such timers are normally used to specify timeouts on
 107 I/O, waiting on condition variables and other rudimentary thread
 108 scheduling. Since these timers have finite namespace and are free
 109 running, they can wrap at any time. NSPR does not provide an *epoch* ,
 110 but expects clients to deal with that issue. The *granularity* of the
 111 timers is guaranteed to be between 10 microseconds and 1 millisecond.
 112 This allows a minimal timer *period* in of approximately 12 hours. But
 113 in order to deal with the wrap-around issue, only half that namespace
 114 may be utilized. Therefore, the minimal usable interval available from
 115 the timers is slightly less than six hours.
 116
 117 Calendar times are 64-bit signed numbers with units of microseconds. The
 118 *epoch* for calendar times is midnight, January 1, 1970, Greenwich Mean
 119 Time. Negative times extend to times before 1970, and positive numbers
 120 forward. Use of 64 bits allows a representation of times approximately
 121 in the range of -30000 to the year 30000. There is a structural
 122 representation (*i.e., exploded* view), routines to acquire the current
 123 time from the host system, and convert them to and from the 64-bit and
 124 structural representation. Additionally there are routines to convert to
 125 and from most well-known forms of ASCII into the 64-bit NSPR
 126 representation.
 127
 128 .. _Memory_management:
 129
 130 Memory management
 131 ^^^^^^^^^^^^^^^^^
 132
 133 NSPR provides API to perform the basic malloc, calloc, realloc and free
 134 functions. Depending on the platform, the functions may be implemented
 135 almost entirely in the NSPR runtime or simply shims that call
 136 immediately into the host operating system's offerings.
 137
 138 Linking
 139 ^^^^^^^
 140
 141 Support for linking (shared library loading and unloading) is part of
 142 NSPR's feature set. In most cases this is simply a smoothing over of the
 143 facilities offered by the various platform providers.
 144
 145 Where It's Headed
 146 ~~~~~~~~~~~~~~~~~
 147
 148 NSPR is applicable as a platform on which to write threaded applications
 149 that need to be ported to multiple platforms.
 150
 151 NSPR is functionally complete and has entered a mode of sustaining
 152 engineering. As operating system vendors issue new releases of their
 153 operating systems, NSPR will be moved forward to these new releases by
 154 interested players.