docs/nspr/reference/pr_setthreadprivate.rst

   1 PR_SetThreadPrivate
   2 ===================
   3
   4 Sets per-thread private data.
   5
   6
   7 Syntax
   8 ------
   9
  10 .. code::
  11
  12    #include <prthread.h>
  13
  14    PRStatus PR_SetThreadPrivate(PRUintn index, void *priv);
  15
  16
  17 Parameters
  18 ~~~~~~~~~~
  19
  20 :ref:`PR_SetThreadPrivate` has the following parameters:
  21
  22 ``index``
  23    An index into the per-thread private data table.
  24 ``priv``
  25    The per-thread private data, or more likely, a pointer to the data.
  26
  27
  28 Returns
  29 ~~~~~~~
  30
  31 The function returns one of the following values:
  32
  33 -  If successful, ``PR_SUCCESS``.
  34 -  If the index is invalid, ``PR_FAILURE``.
  35
  36
  37 Description
  38 -----------
  39
  40 If the thread already has non-``NULL`` private data associated with it,
  41 and if the destructor function for the index is known (not ``NULL``),
  42 NSPR calls the destructor function associated with the index before
  43 setting the new data value. The pointer at the index is swapped with
  44 ``NULL``. If the swapped out value is not ``NULL``, the destructor
  45 function is called. On return, the private data associated with the
  46 index is reassigned the new private data's value, even if it is
  47 ``NULL``. The runtime provides no protection for the private data. The
  48 destructor is called with the runtime holding no locks. Synchronization
  49 is the client's responsibility.
  50
  51 The only way to eliminate thread private data at an index prior to the
  52 thread's termination is to call :ref:`PR_SetThreadPrivate` with a ``NULL``
  53 argument. This causes the index's destructor function to be called, and
  54 afterwards assigns a ``NULL`` in the table. A client must not delete the
  55 referent object of a non-``NULL`` private data without first eliminating
  56 it from the table.