Threads

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.

• Threading Types and Constants
• Threading Functions

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.

For API reference information related to thread synchronization, see Locks and Condition Variables.

Threading Types and Constants

• PRThread
• PRThreadType
• PRThreadScope
• PRThreadState
• PRThreadPriority
• PRThreadPrivateDTOR

Threading Functions

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_CreateThread creates a new thread.
• PR_JoinThread blocks the calling thread until a specified thread terminates.
• PR_GetCurrentThread returns the current thread object for the currently running code.
• PR_AttachThread associates a PRThread object with an existing native thread.
• PR_DetachThread disassociates a PRThread object 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:

• PR_GetThreadPriority
• PR_SetThreadPriority

Controlling Per-Thread Private Data

You can use these functions to associate private data with each of the threads in a process:

• PR_NewThreadPrivateIndex allocates 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_SetThreadPrivate associates private thread data with an index.
• PR_GetThreadPrivate retrieves data associated with an index.

Interrupting and Yielding

• PR_Interrupt requests 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_ClearInterrupt clears a previous interrupt request.
• PR_Sleep causes a thread to yield to other threads for a specified number of ticks.

Setting Global Thread Concurrency

• PR_SetConcurrency sets the number of global threads used by NSPR to create local threads.

Getting a Thread's Scope

• PR_GetThreadScope gets the scoping of the current thread.