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)

libs/thread/example/tss.cpp

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.