1 / 47

NSPR API Overview

NSPR API Overview . Srinivas Lingutla Wan-Teh Chang Lawrence Hardiman. NSPR 2.0. 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

pierce
Download Presentation

NSPR API Overview

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. NSPR API Overview Srinivas Lingutla Wan-Teh Chang Lawrence Hardiman

  2. NSPR 2.0 • 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

  3. Basic services • 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

  4. Miscellaneous libraries • Libplc • String functions • Command line options processing • Libplds • Arenas • Hash tables • Events • Libnsps • Reader/Writer locks

  5. Agenda • Srinivas • Overview • Threads • Synchronization • Atomic operations • Wan-Teh • File and Network I/O • Process Creation • Larry • Time management • Library management • Data types • Instrumentation

  6. Overview • 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.

  7. NSPR Threads • 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

  8. Thread Models • GLOBAL threads only • - NSPR threads map to pthreads on • AIX 4.2 , Digital Unix 4.0 , HP-UX 11.0 • Solaris 2.5.1, Irix 6.2, Linux 2.1 • - NSPR threads map to Win32 threads on • WIN95 • GLOBAL and LOCAL threads • Irix 6.2 • Global threads map to sprocs • Local threads scheduled by NSPR • WinNT 4.0 • Global threads map to Win32 threads • Local threads are NT Fibers scheduled by NSPR

  9. NSPR Thread APIs • 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

  10. NSPR Thread APIs • Thread Info • PR_GetCurrentThread • PR_GetThreadScope • PR_GetThreadType • PR_GetThreadState • Thread local storage • PR_NewThreadPrivateIndex • PR_SetThreadPrivate • PR_GetThreadPrivate

  11. Locks • 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 *)

  12. Condition variables • 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

  13. Condition variables - usage • Waiting • Correct method Incorrect • PR_Lock(..) PR_Lock(…) • while (!condition) if (!condition) • PR_WaitCondVar(..) PR_WaitCondVar(..) • …process data …process data • PR_Unlock(…) PR_Unlock(…) • Notification • PR_Lock(..) • ….process data • PR_NotifyCondVar(..) • PR_Unlock(…)

  14. Monitors PRMonitor Reentrant lock Implicit association of a condition variable Cached Monitors Lazy association of Monitors with objects

  15. Atomic operations • Lock-free operations implemented using atomic instructions (Compare-and-Swap, Load-Linked/Store-Conditional, etc) found on some platforms • Counters • PR_AtomicIncrement/Decrement • PR_AtomicAdd • Stack/LIFO-list • PR_CreateStack/DestroyStack • PR_StackPush/StackPop

  16. Reader Writer Locks • Libnsps • Implemented using PRLock and PRCondVar • Resource management • PSRWLock *PS_NewRWLock ( • PRUint32 lock_rank, • const char *lock_name) • PS_DestroyRWLock • Usage • PS_RWLock_Rlock • PS_RWLock_Wlock • PS_RWLock_Unlock

  17. NSPR I/O Functions Wan-Teh Chang

  18. 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. Introduction

  19. Blocking (synchronous): I/O function does not return until I/O is completed. Nonblocking: I/O function fails with EWOULDBLOCKif 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. I/O Models

  20. 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. Overview

  21. 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. File Descriptors

  22. 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 /. File I/O

  23. Create, remove directories. Directory listing: hidden files are supported. Not supported: current directory, change directory. Directory I/O

  24. 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. Network I/O: Sockets

  25. 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. Nonblocking Sockets

  26. 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 Network Address

  27. I/O Layering Buffering Compression (gzip) Encryption (SSL) Raw transport (NSPR) File descriptors may be layered. - Layer ID - Methods

  28. 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. I/O Layering

  29. 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. Multiwait Receive time Activity Idle Activity Idle

  30. 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. Multiwait Receive time Activity Idle Activity Idle

  31. 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. Summary

  32. PR_CreateProcess: fork+exec PR_WaitProcess Specify attributes of the new process: Current working directory Standard I/O redirection To do: file descriptor inheritance. Process Creation

  33. NSPR Types, Time, Insturmentation Lawrence Hardiman

  34. Prtypes.h PR_EXTERN(type) -- External function declaration PR_IMPLEMENT(type) -- External Function Implementation PR_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 NSPR Types

  35. 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_FALSE PRPackedBool -- PRInt8 PRStatus -- PR_SUCCESS, PR_FAILUREMany NSPR functions return PRStatus. PRPtrdiff -- Pointer difference PR_BIT -- A structure for bit maps PRCList -- A structure for linked lists.See: prclist.h NSPR Types

  36. Prinrval.h PRIntervalTimeMonotonically increasing integerWraps in about 6 (min) hoursprecision is platform dependent PR_INTERVAL_NO_WAITPR_INTERVAL_NO_TIMEOUTNames for timeout values. Used in NSPR functions taking a timeout argument NSPR Interval Time

  37. PR_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 NSPR Interval Time

  38. Prtime.h PRTime -- Clock time typeNumber of usec since 00:00 GMT, 1-Jan-1970 PRTimeParameters -- 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, ... NSPR Clock Time

  39. PR_ExplodeTime(), PR_ImplodeTime()Convert between PRTime and PRExplodedTime. (*PRTimeParamFn()) -- Adjusts a PRExplodedTime to GMT or local time. PR_GMTParameters() -- adjusts to GMT PR_LocalTimeParameters()A thin wrapper to ‘localtime()’. Want precision? … Roll your own. NSPR Clock Time

  40. Prlink.h PRLibrary -- Opaque structure PR_LoadLibrary(), PR_UnloadLibrary()load and unload a shared library PR_FindSymbol() …other functions NSPR Library Management

  41. Prlog.h PRLogModuleInfo -- Logging structure PR_NewLogModule() -- Create a log PR_LOG() -- conditionally write to log Environment variable control NSPR_LOG_MODULESmodulename:level, ... NSPR_LOG_FILEfilespec or “WinDebug” NSPR Logging

  42. Prcountr.h Compile time conditionedDEBUG, FORCE_NSPR_COUNTERS API to create by nameTwo level name lookup“handle” reference is fast API increment, decrement, … API to find all counters by nameExtract values NSPR Counters

  43. Prtrace.h Compile time conditionedDEBUG, NSPR_FORCE_TRACE API to create by nameTwo level name space API to cause a trace entry API to control trace operationsenable, disable, suspend, resume API to cause write to external file NSPR In-memory trace

  44. Status • 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

  45. Status - Mozilla.org • 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)

  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 homepage • http://warp/projects/hardcore/prj-nspr20 • Documentation • http://www.mozilla.org/docs/refList/refNSPR/ • Source code • ns/nspr20 • Test programs • ns/nspr20/pr/tests • NSPR20 team mail alias • nsprgroup • NSPR20 clients mailing list • nspr20clients • NSPR newsgroup at Mozilla.org • news://news.mozilla.org/netscape.public.mozilla.nspr

More Related