NSPR provides an execution environment that promotes the use of lightweight threads. Each thread is an execution entity that is scheduled independently from other threads in the same process. This chapter describes the basic NSPR threading API.
A thread has a limited number of resources that it truly owns. These resources include a stack and the CPU registers (including PC). To an NSPR client, a thread is represented by a pointer to an opaque structure of type
PRThread. A thread is created by an explicit client request and remains a valid, independent execution entity until it returns from its root function or the process abnormally terminates. Threads are critical resources and therefore require some management. To synchronize the termination of a thread, you can join it with another thread (see
PR_JoinThread). Joining a thread provides definitive proof that the target thread has terminated and has finished with both the resources to which the thread has access and the resources of the thread itself.
For an overview of the NSPR threading model and sample code that illustrates its use, see Introduction to NSPR.
Threading Types and Constants
Most of the functions described here accept a pointer to the thread as an argument. NSPR does not check for the validity of the thread. It is the caller's responsibility to ensure that the thread is valid. The effects of these functions on invalid threads are undefined.
- Creating, Joining, and Identifying Threads
- Controlling Thread Priorities
- Interrupting and Yielding
- Setting Global Thread Concurrency
- Getting a Thread's Scope
Creating, Joining, and Identifying Threads
PR_CreateThreadcreates a new thread.
PR_JoinThreadblocks the calling thread until a specified thread terminates.
PR_GetCurrentThreadreturns the current thread object for the currently running code.
PRThreadobject with an existing native thread.
PRThreadobject from a native thread.
Controlling Thread Priorities
For an overview of the way NSPR controls thread priorities, see Setting Thread Priorities.
You set a thread's NSPR priority when you create it with
PR_CreateThread. After a thread has been created, you can get and set its priority with these functions:
Controlling Per-Thread Private Data
You can use these functions to associate private data with each of the threads in a process:
PR_NewThreadPrivateIndexallocates a unique index. If the call is successful, every thread in the same process is capable of associating private data with the new index.
PR_SetThreadPrivateassociates private thread data with an index.
PR_GetThreadPrivateretrieves data associated with an index.
Interrupting and Yielding
PR_Interruptrequests an interrupt of another thread. Once the target thread has been notified of the request, the request stays with the thread until the notification either has been delivered exactly once or is cleared.
PR_ClearInterruptclears a previous interrupt request.
PR_Sleepcauses a thread to yield to other threads for a specified number of ticks.
Setting Global Thread Concurrency
PR_SetConcurrencysets the number of global threads used by NSPR to create local threads.
Getting a Thread's Scope
PR_GetThreadScopegets the scoping of the current thread.