1PR_AttachThread
2===============
3
4.. container:: blockIndicator obsolete obsoleteHeader
5
6   | **Obsolete**
7   | This feature is obsolete. Although it may still work in some
8     browsers, its use is discouraged since it could be removed at any
9     time. Try to avoid using it.
10
11Associates a :ref:`PRThread` object with an existing native thread.
12
13
14Syntax
15------
16
17.. code:: eval
18
19   #include <pprthread.h>
20
21   PRThread* PR_AttachThread(
22      PRThreadType type,
23      PRThreadPriority priority,
24      PRThreadStack *stack);
25
26
27Parameters
28~~~~~~~~~~
29
30:ref:`PR_AttachThread` has the following parameters:
31
32``type``
33   Specifies that the thread is either a user thread
34   (``PR_USER_THREAD``) or a system thread (``PR_SYSTEM_THREAD``).
35``priority``
36   The priority to assign to the thread being attached.
37``stack``
38   The stack for the thread being attached.
39
40
41Returns
42~~~~~~~
43
44The function returns one of these values:
45
46-  If successful, a pointer to a :ref:`PRThread` object.
47-  If unsuccessful, for example if system resources are not available,
48   ``NULL``.
49
50
51Description
52-----------
53
54You use :ref:`PR_AttachThread` when you want to use NSS functions on the
55native thread that was not created with NSPR. :ref:`PR_AttachThread`
56informs NSPR about the new thread by associating a :ref:`PRThread` object
57with the native thread.
58
59The thread object is automatically destroyed when it is no longer
60needed.
61
62You don't need to call :ref:`PR_AttachThread` unless you create your own
63native thread. :ref:`PR_Init` calls :ref:`PR_AttachThread` automatically for
64the primordial thread.
65
66.. note::
67
68   **Note**: As of NSPR release v3.0, :ref:`PR_AttachThread` and
69   :ref:`PR_DetachThread` are obsolete. A native thread not created by NSPR
70   is automatically attached the first time it calls an NSPR function,
71   and automatically detached when it exits.
72
73In NSPR release 19980529B and earlier, it is necessary for a native
74thread not created by NSPR to call :ref:`PR_AttachThread` before it calls
75any NSPR functions, and call :ref:`PR_DetachThread` when it is done calling
76NSPR functions.
77