[Contents] [Previous] [Next] [Last]
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 Chapter 1, "Introduction to NSPR."
For API reference information related to thread synchronization, see Chapter 5, "Locks," and Chapter 6, "Condition Variables."
Threading Types and Constants
PRThread
PRThreadType
PRThreadScope
PRThreadState
PRThreadPriority
PRThreadPrivateDTOR
PRThread
An NSPR thread.
Syntax
#include <prthread.h>
typedef struct PRThread PRThread;
Description
In NSPR, a thread is represented by a pointer to an opaque structure of type PRThread. This pointer is a required parameter for most of the functions that operate on threads.
A PRThread* is the successful result of creating a new thread. The identifier remains valid until it returns from its root function and, if the thread was created joinable, is joined.
PRThreadType
The type of an NSPR thread, specified as a parameter to PR_CreateThread.
Syntax
#include <prthread.h>
typedef enum PRThreadType {
PR_USER_THREAD,
PR_SYSTEM_THREAD
} PRThreadType;
Enumerators
Description
Threads can be either user threads or system threads. NSPR allows the client to synchronize the termination of all user threads and ignores those created as system threads. This arrangement implies that a system thread should not have volatile data that needs to be safely stored away. The applicability of system threads is somewhat dubious; therefore, they should be used with caution.
PRThreadScope
The scope of an NSPR thread, specified as a parameter to PR_CreateThread or returned by PR_GetThreadScope.
Syntax
#include <prthread.h>
typedef enum PRThreadScope {
PR_LOCAL_THREAD,
PR_GLOBAL_THREAD,
PR_GLOBAL_BOUND_THREAD
} PRThreadScope;
Enumerators
Description
An enumerator of type PRThreadScope specifies how a thread is scheduled: either locally by NSPR within the process (a local thread) or globally by the host (a global thread).
Global threads are scheduled by the host OS and compete with all other threads on the host OS for resources. They are subject to fairly sophisticated scheduling techniques.
Local threads are scheduled by NSPR within the process. The process is assumed to be globally scheduled, but NSPR can manipulate local threads without system intervention. In most cases, this leads to a significant performance benefit.
However, on systems that require NSPR to make a distinction between global and local threads, global threads are invariably required to do any form of I/O. If a thread is likely to do a lot of I/O, making it a global thread early is probably warranted.
On systems that don't make a distinction between local and global threads, NSPR silently ignores the scheduling request. To find the scope of the thread, call PR_GetThreadScope.
PRThreadState
A thread's thread state is either joinable or unjoinable.
Syntax
#include <prthread.h>
typedef enum PRThreadState {
PR_JOINABLE_THREAD,
PR_UNJOINABLE_THREAD
} PRThreadState;
Enumerators
Description
A thread is a critical resource and must be managed.
The lifetime of a thread extends from the time it is created to the time it returns from its root function. What happens when it returns from its root function depends on the thread state passed to PR_CreateThread when the thread was created.
If a thread is created as a joinable thread, it continues to exist after returning from its root function until another thread joins it. The join process permits strict synchronization of thread termination and therefore promotes effective resource management.
If a thread is created as an unjoinable (also called detached) thread, it terminates and cleans up after itself after returning from its root function. This results in some ambiguity after the thread's root function has returned and before the thread has finished terminating itself.
PRThreadPriority
A thread's priority setting.
Syntax
#include <prthread.h>
typedef enum PRThreadPriority
{
PR_PRIORITY_FIRST = 0,
PR_PRIORITY_LOW = 0,
PR_PRIORITY_NORMAL = 1,
PR_PRIORITY_HIGH = 2,
PR_PRIORITY_URGENT = 3,
PR_PRIORITY_LAST = 3
} PRThreadPriority;
Enumerators
Description
In general, an NSPR thread of higher priority has a statistically better chance of running relative to threads of lower priority. However, because of the multiple strategies NSPR uses to implement threading on various host platforms, NSPR priorities are not precisely defined. At best they are intended to specify a preference in the amount of CPU time that a higher-priority thread might expect relative to a lower-priority thread. This preference is still subject to resource availability and must not be used in place of proper synchronization.
See Also
Setting Thread Priorities.
PRThreadPrivateDTOR
The destructor function passed to PR_NewThreadPrivateIndex that is associated with the resulting thread private index.
Syntax
#include <prthread.h>
typedef void (PR_CALLBACK *PRThreadPrivateDTOR)(void *priv);
Description
Until the data associated with an index is actually set with a call to PR_SetThreadPrivate, the value of the data is NULL. If the data associated with the index is not NULL, NSPR passes a reference to the data to the destructor function when the thread terminates.
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.
Syntax
#include <prthread.h>
PRThread* PR_CreateThread(
PRThreadType type,
void (*start)(void *arg),
void *arg,
PRThreadPriority priority,
PRThreadScope scope
PRThreadState state,
PRUint32 stackSize);
Parameters
PR_CreateThread has the following parameters:
Returns
The function returns one of the following values:
Description
If you want the thread to start up waiting for the creator to do something, enter a lock
before creating the thread and then have the thread's roof function enter and exit the
same lock. When you are ready for the thread to run, exit the lock. For more information
on locks and thread synchronization, see Chapter 1, "Introduction to NSPR."
If you want to detect the completion of the created thread, make it joinable. You can then use PR_JoinThread to synchronize the termination of another thread.
PR_JoinThread
Blocks the calling thread until a specified thread terminates.
Syntax
#include <prthread.h>
PRStatus PR_JoinThread(PRThread *thread);
Parameter
PR_JoinThread has the following parameter:
Returns
The function returns one of the following values:
Description
PR_JoinThread is used to synchronize the termination of a thread. The function is
synchronous in that it blocks the calling thread until the target thread is in a joinable
state. PR_JoinThread returns to the caller only after the target thread returns from its
root function.
Several threads cannot wait for the same thread to complete. One of the calling threads operates successfully, and the others terminate with the error PR_FAILURE.
The calling thread is not blocked if the target thread has already terminated.
PR_JoinThread is interruptible.
PR_GetCurrentThread
Returns the current thread object for the currently running code.
Syntax
#include <prthread.h>
PRThread* PR_GetCurrentThread(void);
Returns
Always returns a valid reference to the calling thread--a self-identity.
Description
The currently running thread may discover its own identity by calling PR_GetCurrentThread.
NOTE:
This is the only safe way to establish the identity of a thread. Creation and enumeration
are both subject to race conditions.
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
PR_GetThreadPriority
Returns the priority of a specified thread.
Syntax
#include <prthread.h>
PRThreadPriority PR_GetThreadPriority(PRThread *thread);
Parameter
PR_GetThreadPriority has the following parameter:
PR_SetThreadPriority
Sets the priority of a specified thread.
Syntax
#include <prthread.h>
void PR_SetThreadPriority(
PRThread *thread,
PRThreadPriority priority);
Parameters
PR_SetThreadPriority has the following parameters:
Description
Modifying the priority of a thread other than the calling thread is risky. It is difficult to ensure that the state of the target thread permits a priority adjustment without ill effects. It is preferable for a thread to specify itself in the thread parameter when it calls 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
Returns a new index for a per-thread private data table and optionally associates a destructor with the data that will be assigned to the index.
Syntax
#include <prthread.h>
PRStatus PR_NewThreadPrivateIndex(
PRUintn *newIndex,
PRThreadPrivateDTOR destructor);
Parameters
PR_NewThreadPrivateIndex has the following parameters:
Returns
The function returns one of the following values:
Description
If PR_NewThreadPrivateIndex is successful, every thread in the same process is capable of associating private data with the new index. Until the data for an index is actually set, the value of the private data at that index is NULL. You pass this index to PR_SetThreadPrivate and PR_GetThreadPrivate to set and retrieve data associated with the index.
When you allocate the index, you may also register a destructor function of type PRThreadPrivateDTOR. If a destructor function is registered with a new index, it will be called at one of two times, as long as the private data is not NULL:
The index maintains independent data values for each binding thread. A thread can get access only to its own thread-specific data. There is no way to deallocate a private data index once it is allocated.
PR_SetThreadPrivate
Sets per-thread private data.
Syntax
#include <prthread.h>
PRStatus PR_SetThreadPrivate(PRUintn index, void *priv);
Parameters
PR_SetThreadPrivate has the following parameters:
Returns
The function returns one of the following values:
Description
If the thread already has non-NULL private data associated with it, and if the destructor function for the index is known (not NULL), NSPR calls the destructor function associated with the index before setting the new data value. The pointer at the index is swapped with NULL. If the swapped out value is not NULL, the destructor function is called. On return, the private data associated with the index is reassigned the new private data's value, even if it is NULL. The runtime provides no protection for the private data. The destructor is called with the runtime holding no locks. Synchronization is the client's responsibility.
The only way to eliminate thread private data at an index prior to the thread's termination is to call PR_SetThreadPrivate with a NULL argument. This causes the index's destructor function to be called, and afterwards assigns a NULL in the table. A client must not delete the referant object of a non-NULL private data without first eliminating it from the table.
PR_GetThreadPrivate
Recovers the per-thread private data for the current thread.
Syntax
#include <prthread.h>
void* PR_GetThreadPrivate(PRUintn index);
Parameter
PR_GetThreadPrivate has the following parameters:
Returns
NULL if the data has not been set.
Description
PR_GetThreadPrivate may be called at any time during a thread's execution. A thread can get access only to its own per-thread private data. Do not delete the object that the private data refers to without first clearing the thread's value.
Interrupting and Yielding
PR_Interrupt
Sets the interrupt request for a target thread.
Syntax
#include <prthread.h>
PRStatus PR_Interrupt(PRThread *thread);
Parameter
PR_Interrupt has the following parameter:
Returns
The function returns one of the following values:
Description
The purpose of PR_Interrupt is to request that a thread performing some task stop what it is doing and return to some control point. It is assumed that a control point has been mutually arranged between the thread doing the interrupting and the thread being interrupted. When the interrupted thread reaches the prearranged point, it can communicate with its peer to discover the real reason behind the change in plans.
The interrupt request remains in the thread's state until it is delivered exactly once or explicitly canceled. The interrupted thread returns PR_FAILURE (-1) with an error code (see PR_GetError) for blocking operations that return a PRStatus (such as I/O operations, monitor waits, or waiting on a condition). To check whether the thread was interrupted, compare the result of PR_GetError with PR_PENDING_INTERRUPT_ERROR.
PR_Interrupt may itself fail if the target thread is invalid.
Bugs
PR_Interrupt has the following limitations
and known bugs:
- There can be a delay for a thread to be interrupted from
a blocking I/O function. In all NSPR implementations, the
maximum delay is at most five seconds. In the pthreads-based
implementation on Unix, the maximum delay is 0.1 seconds.
- File I/O is considered instantaneous, so file I/O
functions cannot be interrupted. Unfortunately the
standard input, output, and error streams are treated
as files by NSPR, so a
PR_Read call on
PR_STDIN cannot be interrupted even though
it may block indefinitely.
- In the NT implementation,
PR_Connect
cannot be interrupted.
- In the NT implementation, a file descriptor is
not usable and must be closed after an I/O function
on the file descriptor is interrupted. See the memo
"Using IO Timeout
and Interrupt on NT" for details.
PR_ClearInterrupt
Clears the interrupt request for the calling thread.
Syntax
#include <prthread.h>
void PR_ClearInterrupt(void);
Description
Interrupting is a cooperative process, so it's possible that the thread passed to PR_Interrupt may never respond to the interrupt request. For example, the target thread may reach the agreed-on control point without providing an opportunity for the runtime to notify the thread of the interrupt request. In this case, the request for interrupt is still pending with the thread and must be explicitly canceled. Therefore it is sometimes necessary to call PR_ClearInterrupt to clear a previous interrupt request.
If no interrupt request is pending, PR_ClearInterrupt is a no-op.
PR_Sleep
Causes the current thread to yield for a specified amount of time.
Syntax
#include <prthread.h>
PRStatus PR_Sleep(PRIntervalTime ticks);
Parameter
PR_Sleep has the following parameter:
Returns
Calling PR_Sleep with a parameter equivalent to PR_INTERVAL_NO_TIMEOUT is an error and results in a PR_FAILURE error.
Description
PR_Sleep simply waits on a condition for the amount of time specified. If you set ticks to PR_INTERVAL_NO_WAIT, the thread yields.
If ticks is not PR_INTERVAL_NO_WAIT, PR_Sleep uses an existing lock, but has to create a new condition for this purpose. If you have already created such structures, it is more efficient to use them directly.
Calling PR_Sleep with the value of ticks set to PR_INTERVAL_NO_WAIT simply surrenders the processor to ready threads of the same priority. All other values of ticks cause PR_Sleep to block the calling thread for the specified interval.
Threads blocked in PR_Sleep are interruptible.
Setting Global Thread Concurrency
PR_SetConcurrency
Sets the number of global threads used by NSPR to create local threads.
Syntax
#include <prthread.h>
void PR_SetConcurrency(PRUintn numCPUs);
Parameter
PR_SetConcurrency has the following parameter:
Description
NSPR attempts to match the complexion of the thread set to the needs of the application and the capabilities of the host OS and hardware. Global threads are more expensive than local threads, but the latter are unable to take advantage of the scheduling being offered by the host OS. NSPR creates just enough global threads to match the capabilities of the host, for example to match the number of processors available plus one or two. This allows true concurrency in that there are truly multiple execution streams operating simultaneously.
You can use PR_SetConcurrency to exercise similar fine-grained control over the number of global threads that NSPR utilizes. The default value of concurrency is 1. There's no harm in setting the number larger than the number of physical processors available.
Getting a Thread's Scope
PR_GetThreadScope
Gets the scoping of the current thread.
Syntax
#include <prthread.h>
PRThreadScope PR_GetThreadScope(void);
Returns
A value of type PRThreadScope indicating whether the thread is local or global.
[Contents] [Previous] [Next] [Last]
Last Updated: Mon Jul 13 17:27:15 PDT 1998
Copyright © 1998
Netscape Communications Corporation
|
