# Boost.Threads - Header <boost/thread/tss.hpp>

###

# Boost.Threads

## Header <boost/thread/tss.hpp>

## Contents

Introduction
Classes

Class `thread_specific_ptr`

Class `thread_specific_ptr` synopsis
Class `thread_specific_ptr` constructors and destructor
Class `thread_specific_ptr` modifier functions
Class `thread_specific_ptr` observer functions

Example(s)

## Introduction

The header <boost/thread/tss.hpp> defines the class thread_specific_ptr which is used to manage data associated with specific thread instances.

## Classes

### Class `thread_specific_ptr`

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 originally written assuming a single thread of control and is being ported to a multithreaded 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.

#### Class `thread_specific_ptr` 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);
        };
    };

#### Class `thread_specific_ptr` constructors and destructor

    thread_specific_ptr();

Requires: The expression `delete get()` is well formed.
Postconditions: A thread specific storage has been reserved for use by `*this` in all threads, with each thread initially storing a null pointer.
Throws: `boost::thread_resource_error` if the necessary resources can not be obtained.
Note: There is an implementation specific limit to the number of thread specific storage objects that can be created, and this limit may be small.

    ~thread_specific_ptr();

Note: 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.

#### Class `thread_specific_ptr` modifier functions

    T* release();

Postconditions: `*this` holds the null pointer for the current thread.
Returns: `this->get()` prior to the call.

    void reset(T* p=0);

Effects: If `this->get()!= p` then `delete this->get()`.
Postconditions: `*this` holds the pointer `p` for the current thread.
Note: The pointer will be deleted when the thread terminates.

#### Class `thread_specific_ptr` observer functions

    T* get() const;

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

    T* operator->() const;

Returns: `this-<get()`.

    T& operator*() const;

Requires: `this-<get() != 0`
Returns: `this-<get()`.

## Example(s)

    #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-2002. All Rights Reserved.

Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. William E. Kempf makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.