libs/thread/doc/tss.qbk

   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
  12 Thread local storage allows multi-threaded applications to have a separate instance of a given data item for each thread. Where a
  13 single-threaded application would use static or global data, this could lead to contention, deadlock or data corruption in a
  14 multi-threaded application. One example is the C `errno` variable, used for storing the error code related to functions from the
  15 Standard C library. It is common practice (and required by POSIX) for compilers that support multi-threaded applications to provide
  16 a separate instance of `errno` for each thread, in order to avoid different threads competing to read or update the value.
  17
  18 Though 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
  20 some 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
  26 thread must have a distinct value. The value for the current thread can be obtained using the `get()` member function, or by using
  27 the `*` and `->` pointer deference operators. Initially the pointer has a value of `NULL` in each thread, but the value for the
  28 current thread can be set using the `reset()` member function.
  29
  30 If the value of the pointer for the current thread is changed using `reset()`, then the previous value is destroyed by calling the
  31 cleanup routine. Alternatively, the stored value can be reset to `NULL` and the prior value returned by calling the `release()`
  32 member function, allowing the application to take back responsibility for destroying the object.
  33
  34 [heading Cleanup at thread exit]
  35
  36 When a thread exits, the objects associated with each `boost::thread_specific_ptr` instance are destroyed. By default, the object
  37 pointed 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
  40 order. If a cleanup routine sets the value of associated with an instance of `boost::thread_specific_ptr` that has already been
  41 cleaned 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
  44 Note: on some platforms, cleanup of thread-specific data is not
  45 performed for threads created with the platform's native API. On those
  46 platforms such cleanup is only done for threads that are started with
  47 `boost::thread` unless `boost::on_thread_exit()` is called manually
  48 from that thread.
  49
  50 [section:thread_specific_ptr Class `thread_specific_ptr`]
  51
  52     #include <boost/thread/tss.hpp>
  53
  54     template <typename T>
  55     class thread_specific_ptr
  56     {
  57     public:
  58         thread_specific_ptr();
  59         explicit thread_specific_ptr(void (*cleanup_function)(T*));
  60         ~thread_specific_ptr();
  61
  62         T* get() const;
  63         T* operator->() const;
  64         T& operator*() const;
  65
  66         T* release();
  67         void reset(T* new_value=0);
  68     };
  69
  70 [section:default_constructor `thread_specific_ptr();`]
  71
  72 [variablelist
  73
  74 [[Requires:] [`delete this->get()` is well-formed.]]
  75
  76 [[Effects:] [Construct a `thread_specific_ptr` object for storing a pointer to an object of type `T` specific to each thread. The
  77 default `delete`-based cleanup function will be used to destroy any thread-local objects when `reset()` is called, or the thread
  78 exits.]]
  79
  80 [[Throws:] [`boost::thread_resource_error` if an error occurs.]]
  81
  82 ]
  83
  84 [endsect]
  85
  86 [section:constructor_with_custom_cleanup `explicit thread_specific_ptr(void (*cleanup_function)(T*));`]
  87
  88 [variablelist
  89
  90 [[Requires:] [`cleanup_function(this->get())` does not throw any exceptions.]]
  91
  92 [[Effects:] [Construct a `thread_specific_ptr` object for storing a pointer to an object of type `T` specific to each thread. The
  93 supplied `cleanup_function` will be used to destroy any thread-local objects when `reset()` is called, or the thread exits.]]
  94
  95 [[Throws:] [`boost::thread_resource_error` if an error occurs.]]
  96
  97 ]
  98
  99 [endsect]
 100
 101 [section:destructor `~thread_specific_ptr();`]
 102
 103 [variablelist
 104
 105 [[Effects:] [Calls `this->reset()` to clean up the associated value for the current thread, and destroys `*this`.]]
 106
 107 [[Throws:] [Nothing.]]
 108
 109 ]
 110
 111 [note Care needs to be taken to ensure that any threads still running after an instance of `boost::thread_specific_ptr` has been
 112 destroyed do not call any member functions on that instance.]
 113
 114 [endsect]
 115
 116 [section:get `T* get() const;`]
 117
 118 [variablelist
 119
 120 [[Returns:] [The pointer associated with the current thread.]]
 121
 122 [[Throws:] [Nothing.]]
 123
 124 ]
 125
 126 [note The initial value associated with an instance of `boost::thread_specific_ptr` is `NULL` for each thread.]
 127
 128 [endsect]
 129
 130 [section:operator_arrow `T* operator->() const;`]
 131
 132 [variablelist
 133
 134 [[Returns:] [`this->get()`]]
 135
 136 [[Throws:] [Nothing.]]
 137
 138 ]
 139
 140 [endsect]
 141
 142 [section:operator_star `T& operator*() const;`]
 143
 144 [variablelist
 145
 146 [[Requires:] [`this->get` is not `NULL`.]]
 147
 148 [[Returns:] [`*(this->get())`]]
 149
 150 [[Throws:] [Nothing.]]
 151
 152 ]
 153
 154 [endsect]
 155
 156 [section:reset `void reset(T* new_value=0);`]
 157
 158 [variablelist
 159
 160 [[Effects:] [If `this->get()!=new_value` and `this->get()` is non-`NULL`, invoke `delete this->get()` or
 161 `cleanup_function(this->get())` as appropriate. Store `new_value` as the pointer associated with the current thread.]]
 162
 163 [[Postcondition:] [`this->get()==new_value`]]
 164
 165 [[Throws:] [`boost::thread_resource_error` if an error occurs.]]
 166
 167 ]
 168
 169 [endsect]
 170
 171 [section:release `T* release();`]
 172
 173 [variablelist
 174
 175 [[Effects:] [Return `this->get()` and store `NULL` as the pointer associated with the current thread without invoking the cleanup
 176 function.]]
 177
 178 [[Postcondition:] [`this->get()==0`]]
 179
 180 [[Throws:] [Nothing.]]
 181
 182 ]
 183
 184 [endsect]
 185
 186
 187 [endsect]
 188
 189 [endsect]