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 37int32 gThreadName; 38int32 gThreadData; 39 40class ThreadManager 41{ 42public: 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*/ 158