threads.rst (4834B)
1 NSPR provides an execution environment that promotes the use of 2 lightweight threads. Each thread is an execution entity that is 3 scheduled independently from other threads in the same process. This 4 chapter describes the basic NSPR threading API. 5 6 - `Threading Types and Constants <#Threading_Types_and_Constants>`__ 7 - `Threading Functions <#Threading_Functions>`__ 8 9 A thread has a limited number of resources that it truly owns. These 10 resources include a stack and the CPU registers (including PC). To an 11 NSPR client, a thread is represented by a pointer to an opaque structure 12 of type :ref:`PRThread`. A thread is created by an explicit client request 13 and remains a valid, independent execution entity until it returns from 14 its root function or the process abnormally terminates. Threads are 15 critical resources and therefore require some management. To synchronize 16 the termination of a thread, you can **join** it with another thread 17 (see :ref:`PR_JoinThread`). Joining a thread provides definitive proof that 18 the target thread has terminated and has finished with both the 19 resources to which the thread has access and the resources of the thread 20 itself. 21 22 For an overview of the NSPR threading model and sample code that 23 illustrates its use, see `Introduction to 24 NSPR <Introduction_to_NSPR>`__. 25 26 For API reference information related to thread synchronization, see 27 `Locks <Locks>`__ and `Condition Variables <Condition_Variables>`__. 28 29 .. _Threading_Types_and_Constants: 30 31 Threading Types and Constants 32 ----------------------------- 33 34 - :ref:`PRThread` 35 - :ref:`PRThreadType` 36 - :ref:`PRThreadScope` 37 - :ref:`PRThreadState` 38 - :ref:`PRThreadPriority` 39 - :ref:`PRThreadPrivateDTOR` 40 41 .. _Threading_Functions: 42 43 Threading Functions 44 ------------------- 45 46 Most of the functions described here accept a pointer to the thread as 47 an argument. NSPR does not check for the validity of the thread. It is 48 the caller's responsibility to ensure that the thread is valid. The 49 effects of these functions on invalid threads are undefined. 50 51 - `Creating, Joining, and Identifying 52 Threads <#Creating,_Joining,_and_Identifying_Threads>`__ 53 - `Controlling Thread Priorities <#Controlling_Thread_Priorities>`__ 54 - `Interrupting and Yielding <#Interrupting_and_Yielding>`__ 55 - `Setting Global Thread 56 Concurrency <#Setting_Global_Thread_Concurrency>`__ 57 - `Getting a Thread's Scope <#Getting_a_Thread's_Scope>`__ 58 59 .. _Creating.2C_Joining.2C_and_Identifying_Threads: 60 61 Creating, Joining, and Identifying Threads 62 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 63 64 - :ref:`PR_CreateThread` creates a new thread. 65 - :ref:`PR_JoinThread` blocks the calling thread until a specified thread 66 terminates. 67 - :ref:`PR_GetCurrentThread` returns the current thread object for the 68 currently running code. 69 - :ref:`PR_AttachThread`` associates a :ref:`PRThread` object with an existing 70 native thread. 71 - :ref:`PR_DetachThread`` disassociates a :ref:`PRThread` object from a native 72 thread. 73 74 .. _Controlling_Thread_Priorities: 75 76 Controlling Thread Priorities 77 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 78 79 For an overview of the way NSPR controls thread priorities, see `Setting 80 Thread Priorities <Introduction_to_NSPR#Setting_Thread_Priorities.>`__. 81 82 You set a thread's NSPR priority when you create it with 83 :ref:`PR_CreateThread`. After a thread has been created, you can get and 84 set its priority with these functions: 85 86 - :ref:`PR_GetThreadPriority` 87 - :ref:`PR_SetThreadPriority` 88 89 .. _Controlling_Per-Thread_Private_Data: 90 91 Controlling Per-Thread Private Data 92 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 93 94 You can use these functions to associate private data with each of the 95 threads in a process: 96 97 - :ref:`PR_NewThreadPrivateIndex` allocates a unique index. If the call is 98 successful, every thread in the same process is capable of 99 associating private data with the new index. 100 - :ref:`PR_SetThreadPrivate` associates private thread data with an index. 101 - :ref:`PR_GetThreadPrivate` retrieves data associated with an index. 102 103 .. _Interrupting_and_Yielding: 104 105 Interrupting and Yielding 106 ~~~~~~~~~~~~~~~~~~~~~~~~~ 107 108 - :ref:`PR_Interrupt` requests an interrupt of another thread. Once the 109 target thread has been notified of the request, the request stays 110 with the thread until the notification either has been delivered 111 exactly once or is cleared. 112 - :ref:`PR_ClearInterrupt` clears a previous interrupt request. 113 - :ref:`PR_Sleep` causes a thread to yield to other threads for a 114 specified number of ticks. 115 116 .. _Setting_Global_Thread_Concurrency: 117 118 Setting Global Thread Concurrency 119 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 120 121 - :ref:`PR_SetConcurrency` sets the number of global threads used by NSPR 122 to create local threads. 123 124 .. _Getting_a_Thread.27s_Scope: 125 126 Getting a Thread's Scope 127 ~~~~~~~~~~~~~~~~~~~~~~~~ 128 129 - :ref:`PR_GetThreadScope` gets the scoping of the current thread.