mirror of
https://github.com/boostorg/thread.git
synced 2026-01-23 18:12:12 +00:00
223 lines
11 KiB
HTML
223 lines
11 KiB
HTML
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link rel="stylesheet" type="text/css" href="../../../boost.css">
|
|
<title>Boost.Threads - Header <boost/thread/tss.hpp></title>
|
|
</head>
|
|
<body link="#0000ff" vlink="#800080">
|
|
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary=
|
|
"header">
|
|
<tr>
|
|
<td valign="top" width="300">
|
|
<h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../c++boost.gif" border="0"></a></h3>
|
|
</td>
|
|
<td valign="top">
|
|
<h1 align="center">Boost.Threads</h1>
|
|
<h2 align="center">Header <<a href="../../../boost/thread/tss.hpp">boost/thread/tss.hpp</a>></h2>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr>
|
|
<h2>Contents</h2>
|
|
<dl class="page-index">
|
|
<dt><a href="#introduction">Introduction</a></dt>
|
|
<dt><a href="#classes">Classes</a></dt>
|
|
<dl class="page-index">
|
|
<dt><a href="#class-thread_specific_ptr">Class <code>thread_specific_ptr</code></a></dt>
|
|
<dl class="page-index">
|
|
<dt><a href="#class-thread_specific_ptr-synopsis">Class <code>thread_specific_ptr</code>
|
|
synopsis</a></dt>
|
|
<dt><a href="#class-thread_specific_ptr-ctors">Class <code>thread_specific_ptr</code>
|
|
constructors and destructor</a></dt>
|
|
<dt><a href="#class-thread_specific_ptr-modifiers">Class <code>thread_specific_ptr</code>
|
|
modifier functions</a></dt>
|
|
<dt><a href="#class-thread_specific_ptr-observers">Class <code>thread_specific_ptr</code>
|
|
observer functions</a></dt>
|
|
</dl>
|
|
</dl>
|
|
<dt><a href="#examples">Example(s)</a></dt>
|
|
</dl>
|
|
<hr>
|
|
<h2><a name="introduction"></a>Introduction</h2>
|
|
<p>The header <<a href="../../../boost/thread/tss.hpp">boost/thread/tss.hpp</a>>
|
|
defines the class <a href="#class-thread_specific_ptr">thread_specific_ptr</a>
|
|
which is used to manage data associated with specific thread instances.</p>
|
|
<h2><a name="classes"></a>Classes</h2>
|
|
<h3><a name="class-thread_specific_ptr"></a>Class <code>thread_specific_ptr</code></h3>
|
|
<p>The <code>thread_specific_ptr</code> 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 <a href="definitions.html#Thread-safe">thread-safe</a>
|
|
that rely on global data.</p>
|
|
<p>Template <code>thread_specific_ptr</code> stores a pointer to an object obtained
|
|
via <code>new</code> 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 <code>thread_specific_ptr</code>s,
|
|
and for the initial thread are called by the destructor, providing the same
|
|
ordering gaurantees as for normal declarations. Each thread initially stores
|
|
the null pointer in each <code> thread_specific_ptr</code> instance.</p>
|
|
<p>The template <code>thread_specific_ptr</code> is useful in the following cases:</p>
|
|
<ul>
|
|
<li>An interface was originally written assuming a single thread of control
|
|
and is being ported to a multithreaded environment.</li>
|
|
<li>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.</li>
|
|
</ul>
|
|
<h4><a name="class-thread_specific_ptr-synopsis"></a>Class <code>thread_specific_ptr</code>
|
|
synopsis</h4>
|
|
<pre>
|
|
namespace boost
|
|
{
|
|
template <typename T>
|
|
class thread_specific_ptr : private boost::noncopyable // Exposition only.
|
|
// Class thread_specific_ptr meets the <a href="overview.html#non-copyable">NonCopyable</a> requirement.
|
|
{
|
|
public:
|
|
thread_specific_ptr();
|
|
~thread_specific_ptr();
|
|
|
|
T* get() const;
|
|
T* operator->() const;
|
|
T& operator*() const;
|
|
T* release();
|
|
void reset(T* p=0);
|
|
};
|
|
};
|
|
</pre>
|
|
<h4><a name="class-thread_specific_ptr-ctors"></a>Class <code>thread_specific_ptr</code>
|
|
constructors and destructor</h4>
|
|
<pre>
|
|
thread_specific_ptr();
|
|
</pre>
|
|
<dl class="function-semantics">
|
|
<dt><b>Requires:</b> The expression <code>delete get()</code> is well formed.</dt>
|
|
<dt><b>Effects:</b> A thread-specific data key is allocated and visible to all
|
|
threads in the process. Upon creation, the value <code>NULL</code> will be
|
|
associated with the new key in all active threads. Upon thread creation, the
|
|
value <code>NULL</code> will be associated with all defined keys in the new
|
|
thread. A cleanup method is registered with the key that will call <code>delete</code>
|
|
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-<code>NULL</code>
|
|
value associated with that key, the value of the key is set to <code>NULL</code>
|
|
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-<code>NULL</code> values, there are still some non-<code>NULL</code>
|
|
values with associated cleanup handlers the result is undefined behavior.</dt>
|
|
<dt><b>Throws:</b> <code>boost::thread_resource_error</code> if the necessary
|
|
resources can not be obtained.</dt>
|
|
<dt><b>Note:</b> 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.</dt>
|
|
<dt><b>Rationale:</b> The most common need for cleanup will be to call <code>delete</code>
|
|
on the associated value. If other forms of cleanup are required the overloaded
|
|
constructor should be called instead.</dt>
|
|
</dl>
|
|
<pre>
|
|
thread_specific_ptr(void (*cleanup)(void*));
|
|
</pre>
|
|
<dl class="function-semantics">
|
|
<dt><b>Effects:</b> A thread-specific data key is allocated and visible to all
|
|
threads in the process. Upon creation, the value <code>NULL</code> will be
|
|
associated with the new key in all active threads. Upon thread creation, the
|
|
value <code>NULL</code> will be associated with all defined keys in the new
|
|
thread. The <code>cleanup</code> 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-<code>NULL</code> value associated with that key,
|
|
the value of the key is set to <code>NULL</code> 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-<code>NULL</code>
|
|
values, there are still some non-<code>NULL</code> values with associated
|
|
cleanup handlers the result is undefined behavior.</dt>
|
|
<dt><b>Throws:</b> <code>boost::thread_resource_error</code> if the necessary
|
|
resources can not be obtained.</dt>
|
|
<dt><b>Note:</b> 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.</dt>
|
|
<dt><b>Rationale:</b> There is the occasional need to register specialized cleanup
|
|
methods, or to register no cleanup method at all (done by passing <code>NULL</code>
|
|
to this constructor.</dt>
|
|
</dl>
|
|
<pre>
|
|
~thread_specific_ptr();
|
|
</pre>
|
|
<dl class="function-semantics">
|
|
<dt><b>Effects:</b> Deletes the thread-specific data key allocated by the constructor.
|
|
The thread-specific data values associated with the key need not be <code>NULL</code>.
|
|
It is the responsibility of the application to perform any cleanup actions
|
|
for data associated with the key.</dt>
|
|
<dt><b>Note:</b> Does not destroy any data that may be stored in any thread's
|
|
thread specific storage. For this reason you should not destroy a <code>thread_specific_ptr</code>
|
|
object until you are certain there are no threads running that have made use
|
|
of its thread specific storage.</dt>
|
|
<dt><b>Rationale:</b> Associated data is not cleaned up because registered cleanup
|
|
methods need to be run in the thread that allocated the associated data to
|
|
be gauranteed 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.</dt>
|
|
</dl>
|
|
<h4><a name="class-thread_specific_ptr-modifiers"></a>Class <code>thread_specific_ptr</code>
|
|
modifier functions</h4>
|
|
<pre>
|
|
T* release();
|
|
</pre>
|
|
<dl class="function-semantics">
|
|
<dt><b>Postconditions:</b> <code>*this</code> holds the null pointer for the
|
|
current thread.</dt>
|
|
<dt><b>Returns:</b> <code>this->get()</code> prior to the call.</dt>
|
|
<dt><b>Rationale:</b> This method provides a mechanism for the user to relinquish
|
|
control of the data associated with the thread-specific key.</dt>
|
|
</dl>
|
|
<pre>
|
|
void reset(T* p=0);
|
|
</pre>
|
|
<dl class="function-semantics">
|
|
<dt><b>Effects:</b> If <code>this->get()!= p && p != NULL</code>
|
|
then call the associated cleanup function. </dt>
|
|
<dt><b>Postconditions:</b> <code>*this</code> holds the pointer <code> p</code>
|
|
for the current thread.</dt>
|
|
</dl>
|
|
<h4><a name="class-thread_specific_ptr-observers"></a>Class <code>thread_specific_ptr</code>
|
|
observer functions</h4>
|
|
<pre>
|
|
T* get() const;
|
|
</pre>
|
|
<dl class="function-semantics">
|
|
<dt><b>Returns:</b> The object stored in thread specific storage for the current
|
|
thread for <code>*this</code>.</dt>
|
|
<dt><b>Note:</b> Each thread initially returns 0.</dt>
|
|
</dl>
|
|
<pre>
|
|
T* operator->() const;
|
|
</pre>
|
|
<dl class="function-semantics">
|
|
<dt><b>Returns:</b> <code>this->get()</code>.</dt>
|
|
</dl>
|
|
<pre>
|
|
T& operator*() const;
|
|
</pre>
|
|
<dl class="function-semantics">
|
|
<dt><b>Requires:</b> <code>this->get() != 0</code></dt>
|
|
<dt><b>Returns:</b> <code>this->get()</code>.</dt>
|
|
</dl>
|
|
<h2><a name="examples"></a>Example(s)</h2>
|
|
<p><a href="../example/tss.cpp">libs/thread/example/tss.cpp</a></p>
|
|
<hr>
|
|
<p>Revised
|
|
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
|
|
05 November, 2001
|
|
<!--webbot bot="Timestamp" endspan i-checksum="39359" -->
|
|
</p>
|
|
<p><i>© Copyright <a href="mailto:wekempf@cox.net">William E. Kempf</a> 2001-2002.
|
|
All Rights Reserved.</i></p>
|
|
<p>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.</p>
|
|
</body>
|
|
</html>
|