docs/user/support/TLS.dox

   1 /*
   2  * Copyright 2007-2014 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Authors:
   6  *              Niels Sascha Reedijk, niels.reedijk@gmail.com
   7  *              John Scipione, jscipione@gmail.com
   8  *
   9  * Corresponds to:
  10  *              headers/os/support/TLS.h        rev 19972
  11  */
  12
  13
  14 /*!
  15         \file TLS.h
  16         \ingroup support
  17         \ingroup libbe
  18         \brief Functions to use Thread Local Storage.
  19
  20         The Thread Local Storage API provides convenient methods to transform global
  21         variables in to thread-context sensitive variables. Some applications rely on
  22         global variables as a way of intercommunicating between functions and
  23         objects, but one of your demands might be that the contents of that variable
  24         differs between threads.
  25
  26         The following example demonstrates how an imaginary thread manager that
  27         stores per thread data would function. The constructor of this
  28         \c ThreadManager allocates the TLS variables using tls_allocate(). This only
  29         has to be done once, and not in every spawned thread! Then, every spawned
  30         thread that interacts with this thread manager, should call the
  31         \c InitThread() function. This one associates the supplied thread data with
  32         the TLS index using tls_set(). Each thread can get their associated data with
  33         \c GetCurrentThreadData(), which uses tls_get() to retrieve the associated
  34         thread data at the provided index.
  35
  36 \code
  37 int32 gThreadName;
  38 int32 gThreadData;
  39
  40 class ThreadManager
  41 {
  42 public:
  43     // General initialisation
  44     ThreadManager() {
  45         gThreadName = tls_allocate();
  46         gThreadStatus = tls_allocate();
  47     };
  48
  49     // Called from the thread entry function
  50     void InitThread(const char *name, void *data) {
  51         tls_set(gThreadName, (void *)name);
  52         tls_set(gThreadData, data);
  53     };
  54
  55     // Can be called from any of the threads. The returned data will be that
  56     // which the thread explicitly set in the InitThread() function
  57     void *GetCurrentThreadData() {
  58         printf("Thread %s asked for its data.\n",
  59             (const char*)tls_get(gThreadName));
  60         return tls_get(gThreadData);
  61     };
  62 };
  63 \endcode
  64
  65         \note
  66         -# It is impossible to get data other than from your thread.
  67         -# There is a limit to the number of TLS variables you can allocate. This
  68            limit is define by #TLS_MAX_KEYS, but do realize that you share this
  69            limit with all the libraries your application is linked to.
  70         -# The actual global variables, in the example \c gThreadName and
  71            \c gThreadData, are only indexes. You cannot use these variables to
  72            access data without the TLS API.
  73
  74         \since BeOS R5
  75 */
  76
  77
  78 /*!
  79         \def TLS_MAX_KEYS
  80         \brief The maximum number of thread local storage variables. This number is
  81                process wide.
  82
  83         \since BeOS R5
  84 */
  85
  86
  87 /*!
  88         \fn int32 tls_allocate(void)
  89         \brief Allocate a unique index to use for storing variables.
  90
  91         You should only have to do this once to allocate the global index, which
  92         you can reuse in every thread.
  93
  94         \return A unique index to which you can associate per thread data. If we
  95                 overrun the maximum number of keys, as defined by #TLS_MAX_KEYS,
  96                 the function will return \c B_NO_MEMORY.
  97
  98         \sa tls_get()
  99         \sa tls_set()
 100         \sa tls_address()
 101
 102         \since BeOS R5
 103 */
 104
 105
 106 /*!
 107         \fn void* tls_get(int32 index)
 108         \brief Retrieve the data stored for this thread at the provided \a index.
 109
 110         \param index The \a index that you retrieved with tls_allocate().
 111
 112         \return The data you set using tls_set() for this thread, or \c NULL if there
 113                 is no data set, or the \a index is invalid.
 114
 115         \sa tls_allocate()
 116         \sa tls_set()
 117
 118         \since BeOS R5
 119 */
 120
 121
 122 /*!
 123         \fn void** tls_address(int32 index)
 124         \brief Retrieve the pointer that refers to the data of this thread at the
 125     provided \a index.
 126
 127         You can use this pointer to directly manipulate your thread data.
 128
 129         \param index The \a index that you retrieved with tls_allocate().
 130
 131         \return The pointer to where your thread's data is, or \c NULL if the index
 132                 is invalid.
 133
 134         \sa tls_allocate()
 135         \sa tls_set()
 136         \sa tls_get()
 137
 138         \since BeOS R5
 139 */
 140
 141
 142 /*!
 143         \fn void tls_set(int32 index, void *value)
 144         \brief Set the data of this thread at the provided \a index.
 145
 146         It is up to you to make sure the \a index is valid. Any invalid indices can
 147         lead to unpredictable results.
 148
 149         \param index The \a index that you retrieved with tls_allocate().
 150         \param value The data that should be associated with the index for this
 151                thread.
 152
 153         \sa tls_allocate()
 154         \sa tls_get()
 155
 156         \since BeOS R5
 157 */