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