# Boost.Threads, thread_specific_ptr
Keywords: threads, Boost.Threads, thread library, C++

###

# Boost.Threads

## thread_specific_ptr

Introduction
Header
Synopsis
Members
Example

## Introduction

The `thread_specific_ptr` class defines an interface for using thread specific storage. Thread specific storage is data associated with individual threads and is often used to make operations thread-safe that rely on global data.

Template `thread_specific_ptr` stores a pointer to an object obtained via `new` on a thread-by-thread basis and calls delete on the contained pointer when the thread terminates. 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 original written assuming a single thread of control and is being ported to a multi-threaded environment.
- Each thread of control invokes sequences of methods that share data that must be logically accessed through a globally visible access point, but are physically unique for each thread, instead of being explicitly passed.

## Header

    #include <boost/thread/tss.hpp>

## Synopsis

    namespace boost {

    template <typename T>
    class thread_specific_ptr : private boost::noncopyable // Exposition only.
        // Class thread_specific_ptr meets the NonCopyable requirement.
    {
    public:
        thread_specific_ptr();
        ~thread_specific_ptr();

        T* get() const;
        T* operator->() const;
        T& operator*() const;
        T* release();
        void reset(T* p=0);
    };

    } // namespace boost

## Members

### Constructor

       thread_specific_ptr();

Postconditions: A thread specific storage has been reserved for use by *this in all threads, with each thread initially storing a null pointer.

Requires: The expression `delete get()` is well formed.

Throws: `boost::thread_resource_error` if the necessary resources can not be obtained.

Notes: There is an implementation specific limit to the number of thread specific storage objects that can be created, and this limit may be small.

### Destructor

       ~thread_specific_ptr();

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.

### get

       T* get() const;

Returns: The object stored in thread specific storage for the current thread for *this.

Notes: Each thread initially returns 0.

### Smart Pointer Operations

       T* operator->() const;

Returns: `get()`

       T& operator*() const;

Returns: `get()`

Requires: `get() != 0`

### Release

       T* release();

Returns: `get()`

Postcondition: *this holds the null pointer for the current thread.

### Reset

       void reset(T* p=0);

Effects: If `get()!= p` then `delete get()`.

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

Notes: The pointer will be deleted when the thread terminates.

## Example Usage

    #include <boost/thread/thread.hpp>
    #include <boost/thread/tss.hpp>
    #include <cassert>

    boost::thread_specific_ptr<int> value;

    void increment()
    {
       int* p = value.get();
       ++*p;
    }

    void thread_proc()
    {
       value.reset(new int(0)); // initialize the thread's storage
       for (int i=0; i<10; ++i)
       {
           increment();
           int* p = value.get();
           assert(*p == i+1);
       }
    }

    int main(int argc, char* argv[])
    {
       boost::thread_group threads;
       for (int i=0; i<5; ++i)
          threads.create_thread(&thread_proc);
       threads.join_all();
    }

Revised 05 November, 2001

© Copyright William E. Kempf 2001 all rights reserved.