pr_newthreadprivateindex.rst (1909B)
1 PR_NewThreadPrivateIndex 2 ======================== 3 4 Returns a new index for a per-thread private data table and optionally 5 associates a destructor with the data that will be assigned to the 6 index. 7 8 9 Syntax 10 ------ 11 12 .. code:: 13 14 #include <prthread.h> 15 16 PRStatus PR_NewThreadPrivateIndex( 17 PRUintn *newIndex, 18 PRThreadPrivateDTOR destructor); 19 20 21 Parameters 22 ~~~~~~~~~~ 23 24 :ref:`PR_NewThreadPrivateIndex` has the following parameters: 25 26 ``newIndex`` 27 On output, an index that is valid for all threads in the process. You 28 use this index with :ref:`PR_SetThreadPrivate` and 29 :ref:`PR_GetThreadPrivate`. 30 ``destructor`` 31 Specifies a destructor function :ref:`PRThreadPrivateDTOR` for the 32 private data associated with the index. This function can be 33 specified as ``NULL``. 34 35 36 Returns 37 ~~~~~~~ 38 39 The function returns one of the following values: 40 41 - If successful, ``PR_SUCCESS``. 42 - If the total number of indices exceeds 128, ``PR_FAILURE``. 43 44 45 Description 46 ----------- 47 48 If :ref:`PR_NewThreadPrivateIndex` is successful, every thread in the same 49 process is capable of associating private data with the new index. Until 50 the data for an index is actually set, the value of the private data at 51 that index is ``NULL``. You pass this index to :ref:`PR_SetThreadPrivate` 52 and :ref:`PR_GetThreadPrivate` to set and retrieve data associated with the 53 index. 54 55 When you allocate the index, you may also register a destructor function 56 of type :ref:`PRThreadPrivateDTOR`. If a destructor function is registered 57 with a new index, it will be called at one of two times, as long as the 58 private data is not ``NULL``: 59 60 - when replacement private data is set with :ref:`PR_SetThreadPrivate` 61 - when a thread exits 62 63 The index maintains independent data values for each binding thread. A 64 thread can get access only to its own thread-specific data. There is no 65 way to deallocate a private data index once it is allocated.