1

NSPR API Overview

Srinivas LingutlaWan-Teh ChangLawrence Hardiman

2

Netscape Portable Runtime

• Provides OS/system-level services with a platform- independent API.

• General purpose platform for use by clients and servers• Supported on a large number of platforms including

- AIX, Digital Unix, HP-UX, Irix, Solaris, Win95, Windows NT, Linux- Mac, Win 16, SunOS 4.x, NCR, SCO Unix, Netware, etc,.

• Used in most products at Netscape

NSPR 2.0

3

Libnspr

• Threads and Synchronization• File and Network I/O• Memory Management• Time Management• Library Management• Support for 64-bit platforms• Atomic Operations• Environment Variables• Instrumentation• Process creation• List management• Debug aids

Basic services

4

Libplc• String functions• Command line options processing

Libplds• Arenas• Hash tables• Events

Libnsps• Reader/Writer locks

Miscellaneous libraries

5

Srinivas• Overview• Threads• Synchronization• Atomic operations

Wan-Teh• File and Network I/O• Process Creation

Larry• Time management• Library management• Data types• Instrumentation

Agenda

6

• C level API• All services exported through functions (a few are

macros)• All exported symbols have the

• PR prefix for libnspr• PL prefix for the auxiliary libraries• PS prefix for libnsps

• All functions that allocate memory for the caller have a corresponding “free” function

Example: PR_smprintf/PR_smprintf_free• Call PR_GetError to get the NSPR error code when a

function fails• Call PR_GetOSError to get the OS error code of the last

failed system call in NSPR• All timeout values specified in PRIntervalTime units.

Overview

7

Scheduling scope classification

• LOCAL• Scheduled by NSPR• Implemented for use by the Client• User-level implementation, faster performance

• GLOBAL• Scheduled by the system• Available on all platforms where native threads are present• Each NSPR thread maps to a native thread• User or kernel-level implementation

NSPR Threads

8

• GLOBAL threads only- NSPR threads map to pthreads on

AIX 4.2 , Digital Unix 4.0 , HP-UX 11.0Solaris 2.5.1, Irix 6.2, Linux 2.1

- NSPR threads map to Win32 threads onWIN95

• GLOBAL and LOCAL threadsIrix 6.2

Global threads map to sprocsLocal threads scheduled by NSPR

WinNT 4.0Global threads map to Win32 threads

Local threads are NT Fibers scheduled by NSPR

Thread Models

9

Manipulating threads PR_CreateThread( PRThreadType type,

void (*start)(void *), void *arg, PR_ThreadPriority priority, PR_ThreadScope scope, PR_ThreadState, PRUint32 stackSize)

PR_JoinThread PR_GetThreadPriority PR_SetThreadPriority PR_Interrupt PR_ClearInterrupt PR_Sleep

NSPR Thread APIs

10

Thread Info

PR_GetCurrentThread PR_GetThreadScope PR_GetThreadType PR_GetThreadState

Thread local storage

PR_NewThreadPrivateIndex PR_SetThreadPrivate PR_GetThreadPrivate

NSPR Thread APIs

11

PRLock Classic mutual exclusion locking

• Non-reentrant • Not interruptible• Protect data, not code• Use locks for protection, not scheduling• Only hold locks for short periods

Lock management • PRLock *PR_NewLock(void)• PR_DestroyLock(PRLock *)

Lock usage • PR_Lock/PR_Unlock(PRLock *)

Locks

12

PRCondVar

Synchronization between threads - one or more threads can wait for a condition to occur and another thread can notify them when the condition occurs • PRCondVar * PR_NewCondVar(PRLock *)• PR_DestroyCondVar(PRCondVar *)

• PR_WaitCondVar(PRCondVar *, PRIntervalTime)PRLock is unlocked before blocking and reacquired before resuming

• PR_NotifyCondVar/PR_NotifyAllCondVar(PRCondVar *)Notification(s) lost when no thread is waiting

Condition variables

13

WaitingCorrect method Incorrect

PR_Lock(..) PR_Lock(…)while (!condition) if (!condition)

PR_WaitCondVar(..) PR_WaitCondVar(..)…process data …process dataPR_Unlock(…) PR_Unlock(…)

Notification

PR_Lock(..)….process dataPR_NotifyCondVar(..)PR_Unlock(…)

Condition variables - usage

14

PRMonitor Reentrant lock Implicit association of a condition variable

Cached Monitors Lazy association of Monitors with objects

Monitors

15

Lock-free operations implemented using atomic instructions (Compare-and-Swap, Load-Linked/Store-Conditional, etc) found on some platforms

• CountersPR_AtomicIncrement/DecrementPR_AtomicAdd

• Stack/LIFO-listPR_CreateStack/DestroyStackPR_StackPush/StackPop

Atomic operations

16

Libnsps

• Implemented using PRLock and PRCondVar• Resource management

PSRWLock *PS_NewRWLock (PRUint32 lock_rank,const char *lock_name)

PS_DestroyRWLock

• UsagePS_RWLock_RlockPS_RWLock_WlockPS_RWLock_Unlock

Reader Writer Locks

17

NSPR I/O Functions

Wan-Teh Chang

18

Introduction

•NSPR provides thread-aware file and network I/O functions.•Files, sockets, I/O layering, and multiwait receive.•Assume familiarity with Unix or Win32 file I/O and Berkeley socket interface.

19

I/O Models

• Blocking (synchronous): I/O function does not return until I/O is completed.

• Nonblocking: I/O function fails with EWOULDBLOCK if I/O can’t be completed immediately.

• Asynchronous: I/O function submits job to OS and returns immediately. Client polls or gets notified of I/O completion.

20

Overview

•NSPR promotes the multithreaded, blocking I/O programming model. Nonblocking I/O is also available for sockets.•Multiwait receive cuts down the number of threads while retaining the simplicity of blocking I/O.•Compose I/O functionality by layering.

21

File Descriptors

•Open files and sockets are represented by pointers to PRFileDesc structures. PRFileDesc *fd = PR_NewTCPSocket();•I/O methods tables for file, TCP, UDP, and your own I/O abstraction. PR_Read(fd, buf, 1024) ==> fd->methods->read(fd, buf, 1024)•Fields for layering, private data, destructor.

22

File I/O

•Normal (disk) files•Blocking mode only: disk I/O is instantaneous.•64-bit file size and offset are supported.•File pathnames are char * with Unix-style directory

separator /.

23

Directory I/O

•Create, remove directories.•Directory listing: hidden files are supported.•Not supported: current directory, change directory.

24

Network I/O: Sockets

•Berkeley sockets style API•Blocking and nonblocking modes•Blocking functions (PR_Connect, PR_Accept, PR_Send, PR_Recv, PR_SendTo,

PR_RecvFrom) can time out or get interrupted.•Exploit new system calls: PR_AcceptRead,

PR_TransmitFile.

25

Nonblocking Sockets

•Use PR_SetSocketOption to set a socket nonblocking.•Functions on nonblocking sockets may fail with PR_WOULD_BLOCK_ERROR. Output functions may only transmit part of the send buffer.•Call PR_Poll on an array of descriptors to wait until I/O is available.

•Three events: readable, writable, exception.

26

Network Address

•PRNetAddr is a union of IPv4, IPv6 (if enabled), and Unix-domain (on Unix) socket addresses.•Hostname/address lookup: PR_GetXXXByYYY•String-IP address conversion•IPv4/IPv6 transparency

27

I/O Layering

File descriptors may be layered.

Compression (gzip)

Encryption (SSL)

Raw transport (NSPR)

Buffering- Layer ID- Methods

28

I/O Layering

•Push & pop layers to/from a stack.•Layers must be popped in the reverse order in which they are pushed.•Works best with blocking I/O.•Tricky and potentially inefficient with nonblocking I/O and PR_Poll.

29

Multiwait Receive

•One thread per connection is simple but can consume lots of resources.•Client connections are idle most of the time.•Periods of activity start with receiving a client request.

Activity Idle Activity Idle time

30

Multiwait Receive

•A smaller number of threads block on a group of connections, waiting to receive a client request.•Once a request is received, a thread handles it and replies using blocking I/O.

Activity Idle Activity Idle time

31

Summary

•Basic I/O API is similar to Unix/Win32 system calls.•I/O functionality can be composed by layering.•NSPR promotes multithreaded, blocking I/O programming model for its simplicity and easy of I/O layering.•Use of thread resources can be reduced by multiwait receive functions.

32

Process Creation

•PR_CreateProcess: fork+exec•PR_WaitProcess•Specify attributes of the new process:

•Current working directory•Standard I/O redirection

•To do: file descriptor inheritance.

33

NSPR Types, Time, Insturmentation

Lawrence Hardiman

34

NSPR TypesPrtypes.hPR_EXTERN(type) -- External function declarationPR_IMPLEMENT(type) -- External Function ImplementationPR_CALLBACK used for function pointers. Macros wrap platform specific modififers

PRIntn -- Native int for platform. Typedef’d to int.PRInt8, PRInt16, PRInt32 -- Signed <n> bit integer.PRUint8, PRUint16, PRUint32 -- Unsigned <n> bit integer.PRSize -- Use it where you want size_t

35

NSPR Types

PRInt64, PRUint64 -- 64 bit signed and unsigned integers.Use the macro operator interfaces to manipulate PRInt64 types even if the platform’s compiler supports 64bit integers.

PRBool -- PR_TRUE, PR_FALSEPRPackedBool -- PRInt8PRStatus -- PR_SUCCESS, PR_FAILUREMany NSPR functions return PRStatus.PRPtrdiff -- Pointer differencePR_BIT -- A structure for bit mapsPRCList -- A structure for linked lists.See: prclist.h

36

NSPR Interval TimePrinrval.hPRIntervalTimeMonotonically increasing integerWraps in about 6 (min) hoursprecision is platform dependentPR_INTERVAL_NO_WAITPR_INTERVAL_NO_TIMEOUTNames for timeout values. Used in NSPR functions taking a timeout argument

37

NSPR Interval TimePR_IntervalNow() -- Value of NSPR’s runtime clock.PR_SecondsToInterval(), PR_MillisecondsToInterval(), …Converts common time units to NSPR interval time units.PR_IntervalToSeconds(), PR_IntervalToMilliseconds(), …Converts NSPR interval time units to common time units.PR_TicksPerSecond() -- Suitable for arithmetic

38

NSPR Clock TimePrtime.hPRTime -- Clock time typeNumber of usec since 00:00 GMT, 1-Jan-1970PRTimeParameters -- Defines variants from GMT. … offsets from GMT to standard and daylight time.PRExplodedTime -- Similar to ‘struct tm’has discrete values for tm_usec, tm_sec, ...

39

NSPR Clock Time

PR_ExplodeTime(), PR_ImplodeTime()Convert between PRTime and PRExplodedTime.(*PRTimeParamFn()) -- Adjusts a PRExplodedTime to GMT or local time.

PR_GMTParameters() -- adjusts to GMTPR_LocalTimeParameters()A thin wrapper to ‘localtime()’.

Want precision? … Roll your own.

40

NSPR Library Management

Prlink.hPRLibrary -- Opaque structurePR_LoadLibrary(), PR_UnloadLibrary()load and unload a shared libraryPR_FindSymbol() …other functions

41

NSPR LoggingPrlog.hPRLogModuleInfo -- Logging structurePR_NewLogModule() -- Create a logPR_LOG() -- conditionally write to logEnvironment variable controlNSPR_LOG_MODULESmodulename:level, ...NSPR_LOG_FILEfilespec or “WinDebug”

42

NSPR Counters

Prcountr.hCompile time conditionedDEBUG, FORCE_NSPR_COUNTERSAPI to create by nameTwo level name lookup“handle” reference is fastAPI increment, decrement, …API to find all counters by nameExtract values

43

NSPR In-memory tracePrtrace.hCompile time conditionedDEBUG, NSPR_FORCE_TRACEAPI to create by nameTwo level name spaceAPI to cause a trace entryAPI to control trace operationsenable, disable, suspend, resumeAPI to cause write to external file

44

• NSPR binary releases will be available periodically• Current release, v3.0, released Oct-2-98• Next release scheduled for Feb’99• Use only the binary releases of NSPR• Release names of the form Major.Minor.Patch number

Newer minor releases are backward compatible• A function, libVersionPoint, exported to provide library version information, PRVersionDescription• Requirements/suggestions collected from Netscape developers • Use Bugsplat (Scopus database) to file bug reports

Status

45

• NSPR2.0 is part of open source available at Mozilla.org• Replaces NSPR 1.0 in Netscape Client 5.0• Built and used as a stand-alone runtime• Being tested for inclusion in other open-source projects

such as Apache and Japhar (JVM) on the Net• NSPR is subject to NPL (Netscape Public License)• NSPS is a Netscape-internal library (non-NPL)• Contributions received from the Net developers (patches

and ports to new platforms)

Status - Mozilla.org

46

Future

Implement additional services• Process-level facilities• IPC• Metering information• Debug aids

Performance improvements• I/O thruput• Threads and synchronization

Stability• Code coverage, more extensive QA testing• Engage the net

47

Reference

• Internal homepagehttp://warp/projects/hardcore/prj-nspr20

• Documentationhttp://www.mozilla.org/docs/refList/refNSPR/

• Source codens/nspr20

• Test programsns/nspr20/pr/tests

• NSPR20 team mail aliasnsprgroup

• NSPR20 clients mailing listnspr20clients

• NSPR newsgroup at Mozilla.orgnews://news.mozilla.org/netscape.public.mozilla.nspr