1[/ 2 (C) Copyright 2007-8 Anthony Williams. 3 Distributed under the Boost Software License, Version 1.0. 4 (See accompanying file LICENSE_1_0.txt or copy at 5 http://www.boost.org/LICENSE_1_0.txt). 6] 7 8[section Thread Local Storage] 9 10[heading Synopsis] 11 12Thread local storage allows multi-threaded applications to have a separate instance of a given data item for each thread. Where a 13single-threaded application would use static or global data, this could lead to contention, deadlock or data corruption in a 14multi-threaded application. One example is the C `errno` variable, used for storing the error code related to functions from the 15Standard C library. It is common practice (and required by POSIX) for compilers that support multi-threaded applications to provide 16a separate instance of `errno` for each thread, in order to avoid different threads competing to read or update the value. 17 18Though compilers often provide this facility in the form of extensions to the declaration syntax (such as `__declspec(thread)` or 19`__thread` annotations on `static` or namespace-scope variable declarations), such support is non-portable, and is often limited in 20some way, such as only supporting POD types. 21 22[heading Portable thread-local storage with `boost::thread_specific_ptr`] 23 24`boost::thread_specific_ptr` provides a portable mechanism for thread-local storage that works on all compilers supported by 25__boost_thread__. Each instance of `boost::thread_specific_ptr` represents a pointer to an object (such as `errno`) where each 26thread must have a distinct value. The value for the current thread can be obtained using the `get()` member function, or by using 27the `*` and `->` pointer deference operators. Initially the pointer has a value of `NULL` in each thread, but the value for the 28current thread can be set using the `reset()` member function. 29 30If the value of the pointer for the current thread is changed using `reset()`, then the previous value is destroyed by calling the 31cleanup routine. Alternatively, the stored value can be reset to `NULL` and the prior value returned by calling the `release()` 32member function, allowing the application to take back responsibility for destroying the object. 33 34[heading Cleanup at thread exit] 35 36When a thread exits, the objects associated with each `boost::thread_specific_ptr` instance are destroyed. By default, the object 37pointed to by a pointer `p` is destroyed by invoking `delete p`, but this can be overridden for a specific instance of 38`boost::thread_specific_ptr` by providing a cleanup routine to the constructor. In this case, the object is destroyed by invoking 39`func(p)` where `func` is the cleanup routine supplied to the constructor. The cleanup functions are called in an unspecified 40order. If a cleanup routine sets the value of associated with an instance of `boost::thread_specific_ptr` that has already been 41cleaned up, that value is added to the cleanup list. Cleanup finishes when there are no outstanding instances of 42`boost::thread_specific_ptr` with values. 43 44Note: on some platforms, cleanup of thread-specific data is not 45performed for threads created with the platform's native API. On those 46platforms such cleanup is only done for threads that are started with 47`boost::thread` unless `boost::on_thread_exit()` is called manually 48from that thread. 49 50[heading Rationale about the nature of the key] 51 52Boost.Thread uses the address of the `thread_specific_ptr` instance as key of the thread specific pointers. This avoids to create/destroy a key which will need a lock to protect from race conditions. This has a little performance liability, as the access must be done using an associative container. 53 54[section:thread_specific_ptr Class `thread_specific_ptr`] 55 56 // #include <boost/thread/tss.hpp> 57 58 namespace boost 59 { 60 template <typename T> 61 class thread_specific_ptr 62 { 63 public: 64 thread_specific_ptr(); 65 explicit thread_specific_ptr(void (*cleanup_function)(T*)); 66 ~thread_specific_ptr(); 67 68 T* get() const; 69 T* operator->() const; 70 T& operator*() const; 71 72 T* release(); 73 void reset(T* new_value=0); 74 }; 75 } 76 77[section:default_constructor `thread_specific_ptr();`] 78 79[variablelist 80 81[[Requires:] [`delete this->get()` is well-formed.]] 82 83[[Effects:] [Construct a `thread_specific_ptr` object for storing a pointer to an object of type `T` specific to each thread. The 84default `delete`-based cleanup function will be used to destroy any thread-local objects when `reset()` is called, or the thread 85exits.]] 86 87[[Throws:] [`boost::thread_resource_error` if an error occurs.]] 88 89] 90 91[endsect] 92 93[section:constructor_with_custom_cleanup `explicit thread_specific_ptr(void (*cleanup_function)(T*));`] 94 95[variablelist 96 97[[Requires:] [`cleanup_function(this->get())` does not throw any exceptions.]] 98 99[[Effects:] [Construct a `thread_specific_ptr` object for storing a pointer to an object of type `T` specific to each thread. The 100supplied `cleanup_function` will be used to destroy any thread-local objects when `reset()` is called, or the thread exits.]] 101 102[[Throws:] [`boost::thread_resource_error` if an error occurs.]] 103 104] 105 106[endsect] 107 108[section:destructor `~thread_specific_ptr();`] 109 110[variablelist 111 112[[Requires:] [All the thread specific instances associated to this thread_specific_ptr (except maybe the one associated to this thread) must be null.]] 113 114[[Effects:] [Calls `this->reset()` to clean up the associated value for the current thread, and destroys `*this`.]] 115 116[[Throws:] [Nothing.]] 117 118[[Remarks:] [The requirement is due to the fact that in order to delete all these instances, the implementation should be forced to maintain a list of all the threads having an associated specific ptr, which is against the goal of thread specific data.]] 119 120] 121 122[note Care needs to be taken to ensure that any threads still running after an instance of `boost::thread_specific_ptr` has been 123destroyed do not call any member functions on that instance.] 124 125[endsect] 126 127[section:get `T* get() const;`] 128 129[variablelist 130 131[[Returns:] [The pointer associated with the current thread.]] 132 133[[Throws:] [Nothing.]] 134 135] 136 137[note The initial value associated with an instance of `boost::thread_specific_ptr` is `NULL` for each thread.] 138 139[endsect] 140 141[section:operator_arrow `T* operator->() const;`] 142 143[variablelist 144 145[[Returns:] [`this->get()`]] 146 147[[Throws:] [Nothing.]] 148 149] 150 151[endsect] 152 153[section:operator_star `T& operator*() const;`] 154 155[variablelist 156 157[[Requires:] [`this->get` is not `NULL`.]] 158 159[[Returns:] [`*(this->get())`]] 160 161[[Throws:] [Nothing.]] 162 163] 164 165[endsect] 166 167[section:reset `void reset(T* new_value=0);`] 168 169[variablelist 170 171[[Effects:] [If `this->get()!=new_value` and `this->get()` is non-`NULL`, invoke `delete this->get()` or 172`cleanup_function(this->get())` as appropriate. Store `new_value` as the pointer associated with the current thread.]] 173 174[[Postcondition:] [`this->get()==new_value`]] 175 176[[Throws:] [`boost::thread_resource_error` if an error occurs.]] 177 178] 179 180[endsect] 181 182[section:release `T* release();`] 183 184[variablelist 185 186[[Effects:] [Return `this->get()` and store `NULL` as the pointer associated with the current thread without invoking the cleanup 187function.]] 188 189[[Postcondition:] [`this->get()==0`]] 190 191[[Throws:] [Nothing.]] 192 193] 194 195[endsect] 196 197 198[endsect] 199 200[endsect] 201