/** Copyright 2007-2014 Haiku, Inc. All rights reserved.* Distributed under the terms of the MIT License.** Authors:* Niels Sascha Reedijk, niels.reedijk@gmail.com* John Scipione, jscipione@gmail.com** Corresponds to:* headers/os/support/TLS.h rev 19972*//*!\file TLS.h\ingroup support\ingroup libbe\brief Functions to use Thread Local Storage.The Thread Local Storage API provides convenient methods to transform globalvariables in to thread-context sensitive variables. Some applications rely onglobal variables as a way of intercommunicating between functions andobjects, but one of your demands might be that the contents of that variablediffers between threads.The following example demonstrates how an imaginary thread manager thatstores per thread data would function. The constructor of this\c ThreadManager allocates the TLS variables using tls_allocate(). This onlyhas to be done once, and not in every spawned thread! Then, every spawnedthread that interacts with this thread manager, should call the\c InitThread() function. This one associates the supplied thread data withthe TLS index using tls_set(). Each thread can get their associated data with\c GetCurrentThreadData(), which uses tls_get() to retrieve the associatedthread data at the provided index.\codeint32 gThreadName;int32 gThreadData;class ThreadManager{public:// General initialisationThreadManager() {gThreadName = tls_allocate();gThreadStatus = tls_allocate();};// Called from the thread entry functionvoid InitThread(const char *name, void *data) {tls_set(gThreadName, (void *)name);tls_set(gThreadData, data);};// Can be called from any of the threads. The returned data will be that// which the thread explicitly set in the InitThread() functionvoid *GetCurrentThreadData() {printf("Thread %s asked for its data.\n",(const char*)tls_get(gThreadName));return tls_get(gThreadData);};};\endcode\note-# It is impossible to get data other than from your thread.-# There is a limit to the number of TLS variables you can allocate. Thislimit is define by #TLS_MAX_KEYS, but do realize that you share thislimit with all the libraries your application is linked to.-# The actual global variables, in the example \c gThreadName and\c gThreadData, are only indexes. You cannot use these variables toaccess data without the TLS API.\since BeOS R5*//*!\def TLS_MAX_KEYS\brief The maximum number of thread local storage variables. This number isprocess wide.\since BeOS R5*//*!\fn int32 tls_allocate(void)\brief Allocate a unique index to use for storing variables.You should only have to do this once to allocate the global index, whichyou can reuse in every thread.\return A unique index to which you can associate per thread data. If weoverrun the maximum number of keys, as defined by #TLS_MAX_KEYS,the function will return \c B_NO_MEMORY.\sa tls_get()\sa tls_set()\sa tls_address()\since BeOS R5*//*!\fn void* tls_get(int32 index)\brief Retrieve the data stored for this thread at the provided \a index.\param index The \a index that you retrieved with tls_allocate().\return The data you set using tls_set() for this thread, or \c NULL if thereis no data set, or the \a index is invalid.\sa tls_allocate()\sa tls_set()\since BeOS R5*//*!\fn void** tls_address(int32 index)\brief Retrieve the pointer that refers to the data of this thread at theprovided \a index.You can use this pointer to directly manipulate your thread data.\param index The \a index that you retrieved with tls_allocate().\return The pointer to where your thread's data is, or \c NULL if the indexis invalid.\sa tls_allocate()\sa tls_set()\sa tls_get()\since BeOS R5*//*!\fn void tls_set(int32 index, void *value)\brief Set the data of this thread at the provided \a index.It is up to you to make sure the \a index is valid. Any invalid indices canlead to unpredictable results.\param index The \a index that you retrieved with tls_allocate().\param value The data that should be associated with the index for thisthread.\sa tls_allocate()\sa tls_get()\since BeOS R5*/