From 26a029d407be480d791972afb5975cf62c9360a6 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 19 Apr 2024 02:47:55 +0200 Subject: Adding upstream version 124.0.1. Signed-off-by: Daniel Baumann --- docs/nspr/reference/threads.rst | 129 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 docs/nspr/reference/threads.rst (limited to 'docs/nspr/reference/threads.rst') diff --git a/docs/nspr/reference/threads.rst b/docs/nspr/reference/threads.rst new file mode 100644 index 0000000000..fdcdcc271e --- /dev/null +++ b/docs/nspr/reference/threads.rst @@ -0,0 +1,129 @@ +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_Types_and_Constants>`__ +- `Threading Functions <#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 :ref:`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 :ref:`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: + +Threading Types and Constants +----------------------------- + + - :ref:`PRThread` + - :ref:`PRThreadType` + - :ref:`PRThreadScope` + - :ref:`PRThreadState` + - :ref:`PRThreadPriority` + - :ref:`PRThreadPrivateDTOR` + +.. _Threading_Functions: + +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 <#Creating,_Joining,_and_Identifying_Threads>`__ +- `Controlling Thread Priorities <#Controlling_Thread_Priorities>`__ +- `Interrupting and Yielding <#Interrupting_and_Yielding>`__ +- `Setting Global Thread + Concurrency <#Setting_Global_Thread_Concurrency>`__ +- `Getting a Thread's Scope <#Getting_a_Thread's_Scope>`__ + +.. _Creating.2C_Joining.2C_and_Identifying_Threads: + +Creating, Joining, and Identifying Threads +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + - :ref:`PR_CreateThread` creates a new thread. + - :ref:`PR_JoinThread` blocks the calling thread until a specified thread + terminates. + - :ref:`PR_GetCurrentThread` returns the current thread object for the + currently running code. + - :ref:`PR_AttachThread`` associates a :ref:`PRThread` object with an existing + native thread. + - :ref:`PR_DetachThread`` disassociates a :ref:`PRThread` object from a native + thread. + +.. _Controlling_Thread_Priorities: + +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 +:ref:`PR_CreateThread`. After a thread has been created, you can get and +set its priority with these functions: + + - :ref:`PR_GetThreadPriority` + - :ref:`PR_SetThreadPriority` + +.. _Controlling_Per-Thread_Private_Data: + +Controlling Per-Thread Private Data +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can use these functions to associate private data with each of the +threads in a process: + + - :ref:`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. + - :ref:`PR_SetThreadPrivate` associates private thread data with an index. + - :ref:`PR_GetThreadPrivate` retrieves data associated with an index. + +.. _Interrupting_and_Yielding: + +Interrupting and Yielding +~~~~~~~~~~~~~~~~~~~~~~~~~ + + - :ref:`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. + - :ref:`PR_ClearInterrupt` clears a previous interrupt request. + - :ref:`PR_Sleep` causes a thread to yield to other threads for a + specified number of ticks. + +.. _Setting_Global_Thread_Concurrency: + +Setting Global Thread Concurrency +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + - :ref:`PR_SetConcurrency` sets the number of global threads used by NSPR + to create local threads. + +.. _Getting_a_Thread.27s_Scope: + +Getting a Thread's Scope +~~~~~~~~~~~~~~~~~~~~~~~~ + + - :ref:`PR_GetThreadScope` gets the scoping of the current thread. -- cgit v1.2.3