Class thread_specific

Class thread_specific_ptr

boost::thread_specific_ptr — The thread_specific_ptr class defines an interface for using thread specific storage.

Synopsis

class thread_specific_ptr : private boost::noncopyable   // Exposition only
{
public:
  // construct/copy/destruct
  thread_specific_ptr();
  thread_specific_ptr(void (*cleanup)(void*));
  ~thread_specific_ptr();

  // modifier functions
  T* release();
  void reset(T* = 0);

  // observer functions
  T* get() const;
  T* operator->() const;
  T& operator*()() const;
};

Description

Thread specific storage is data associated with individual threads and is often used to make operations that rely on global data thread-safe.

Template thread_specific_ptr stores a pointer to an object obtained on a thread-by-thread basis and calls a specified cleanup handler on the contained pointer when the thread terminates. The cleanup handlers are called in the reverse order of construction of the thread_specific_ptrs, and for the initial thread are called by the destructor, providing the same ordering guarantees as for normal declarations. Each thread initially stores the null pointer in each thread_specific_ptr instance.

The template thread_specific_ptr is useful in the following cases:

An interface was originally written assuming a single thread of control and it is being ported to a multithreaded environment.
Each thread of control invokes sequences of methods that share data that are physically unique for each thread, but must be logically accessed through a globally visible access point instead of being explicitly passed.

`thread_specific_ptr` construct/copy/destruct

thread_specific_ptr();

Requires:	The expression `delete get()` is well formed.
Effects:	A thread-specific data key is allocated and visible to all threads in the process. Upon creation, the value `NULL` will be associated with the new key in all active threads. A cleanup method is registered with the key that will call `delete` on the value associated with the key for a thread when it exits. When a thread exits, if a key has a registered cleanup method and the thread has a non-`NULL` value associated with that key, the value of the key is set to `NULL` and then the cleanup method is called with the previously associated value as its sole argument. The order in which registered cleanup methods are called when a thread exits is undefined. If after all the cleanup methods have been called for all non-`NULL` values, there are still some non-`NULL` values with associated cleanup handlers the result is undefined behavior.
Throws:	boost::thread_resource_error if the necessary resources can not be obtained.
Notes:	There may be an implementation specific limit to the number of thread specific storage objects that can be created, and this limit may be small.
Rationale:	The most common need for cleanup will be to call `delete` on the associated value. If other forms of cleanup are required the overloaded constructor should be called instead.

thread_specific_ptr(void (*cleanup)(void*) cleanup);

Effects:	A thread-specific data key is allocated and visible to all threads in the process. Upon creation, the value `NULL` will be associated with the new key in all active threads. The `cleanup` method is registered with the key and will be called for a thread with the value associated with the key for that thread when it exits. When a thread exits, if a key has a registered cleanup method and the thread has a non-`NULL` value associated with that key, the value of the key is set to `NULL` and then the cleanup method is called with the previously associated value as its sole argument. The order in which registered cleanup methods are called when a thread exits is undefined. If after all the cleanup methods have been called for all non-`NULL` values, there are still some non-`NULL` values with associated cleanup handlers the result is undefined behavior.
Throws:	boost::thread_resource_error if the necessary resources can not be obtained.
Notes:	There may be an implementation specific limit to the number of thread specific storage objects that can be created, and this limit may be small.
Rationale:	There is the occasional need to register specialized cleanup methods, or to register no cleanup method at all (done by passing `NULL` to this constructor.

~thread_specific_ptr();

Effects:	Deletes the thread-specific data key allocated by the constructor. The thread-specific data values associated with the key need not be `NULL`. It is the responsibility of the application to perform any cleanup actions for data associated with the key.
Notes:	Does not destroy any data that may be stored in any thread's thread specific storage. For this reason you should not destroy a thread_specific_ptr object until you are certain there are no threads running that have made use of its thread specific storage.
Rationale:	Associated data is not cleaned up because registered cleanup methods need to be run in the thread that allocated the associated data to be guarranteed to work correctly. There's no safe way to inject the call into another thread's execution path, making it impossible to call the cleanup methods safely.

`thread_specific_ptr` modifier functions

T* release();

Postconditions:	`*this` holds the null pointer for the current thread.
Returns:	`this->get()` prior to the call.
Rationale:	This method provides a mechanism for the user to relinquish control of the data associated with the thread-specific key.

```
void reset(T* p = 0);
```
Effects: If this->get() != p && this->get() != NULL then call the associated cleanup function.

Postconditions: *this holds the pointer p for the current thread.

`thread_specific_ptr` observer functions

```
T* get() const;
```
Returns: The object stored in thread specific storage for the current thread for *this.

Notes: Each thread initially returns 0.
```
T* operator->() const;
```
Returns: this->get().
```
T& operator*()() const;
```
Requires: this->get() != 0

Returns: this->get().

Effects:	If `this->get() != p && this->get() != NULL` then call the associated cleanup function.
Postconditions:	`*this` holds the pointer `p` for the current thread.

Returns:	The object stored in thread specific storage for the current thread for `*this`.
Notes:	Each thread initially returns 0.