mirror of
https://github.com/boostorg/thread.git
synced 2026-01-22 05:42:37 +00:00
224 lines
6.4 KiB
HTML
224 lines
6.4 KiB
HTML
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content=
|
|
"text/html; charset=iso-8859-1">
|
|
<meta name="keywords" content=
|
|
"threads, Boost.Threads, thread library, C++">
|
|
<link rel="stylesheet" type="text/css" href="styles.css">
|
|
|
|
<title>Boost.Threads, thread_specific_ptr</title>
|
|
</head>
|
|
|
|
<body bgcolor="#FFFFFF" link="#0000FF" vlink="#800080">
|
|
<table summary="header" border="0" cellpadding="7" cellspacing="0"
|
|
width="100%">
|
|
<tr>
|
|
<td valign="top" width="300">
|
|
<h3><img src="../../../c++boost.gif" alt="C++ Boost" width=
|
|
"277" height="86"></h3>
|
|
</td>
|
|
|
|
<td valign="top">
|
|
<h1 align="center">Boost.Threads</h1>
|
|
|
|
<h2 align="center">thread_specific_ptr</h2>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr>
|
|
|
|
<p><a href="#Introduction">Introduction</a><br>
|
|
<a href="#Header">Header</a><br>
|
|
<a href="#Synopsis">Synopsis</a><br>
|
|
<a href="#Members">Members</a><br>
|
|
<a href="#Example">Example</a></p>
|
|
|
|
<h2><a name="Introduction">Introduction</a></h2>
|
|
|
|
<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 delete on the contained pointer when the thread terminates. 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 original written assuming a single thread of
|
|
control and is being ported to a multi-threaded 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>
|
|
|
|
<h2><a name="Header">Header</a></h2>
|
|
<pre>
|
|
#include <a href=
|
|
"../../../boost/thread/tss.hpp"><boost/thread/tss.hpp></a>
|
|
</pre>
|
|
|
|
<h2><a name="Synopsis">Synopsis</a></h2>
|
|
<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#NonCopyable">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);
|
|
};
|
|
|
|
} // namespace boost
|
|
</pre>
|
|
|
|
<h2><a name="Members">Members</a></h2>
|
|
<hr>
|
|
|
|
<h3>Constructor</h3>
|
|
<pre>
|
|
thread_specific_ptr();
|
|
</pre>
|
|
|
|
<p><b>Postconditions:</b> A thread specific storage has been reserved
|
|
for use by *this in all threads, with each thread initially storing a
|
|
null pointer.</p>
|
|
|
|
<p><b>Requires:</b> The expression <code>delete get()</code> is well
|
|
formed.</p>
|
|
|
|
<p><b>Throws:</b> <code>boost::thread_resource_error</code> if the
|
|
necessary resources can not be obtained.</p>
|
|
|
|
<p><b>Notes:</b> There is an implementation specific limit to the
|
|
number of thread specific storage objects that can be created, and this
|
|
limit may be small.</p>
|
|
<hr>
|
|
|
|
<h3>Destructor</h3>
|
|
<pre>
|
|
~thread_specific_ptr();
|
|
</pre>
|
|
|
|
<p><b>Notes:</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.</p>
|
|
<hr>
|
|
|
|
<h3>get</h3>
|
|
<pre>
|
|
T* get() const;
|
|
</pre>
|
|
|
|
<p><b>Returns:</b> The object stored in thread specific storage for the
|
|
current thread for *this.</p>
|
|
|
|
<p><b>Notes:</b> Each thread initially returns 0.</p>
|
|
<hr>
|
|
|
|
<h3>Smart Pointer Operations</h3>
|
|
<pre>
|
|
T* operator->() const;
|
|
</pre>
|
|
|
|
<p><b>Returns:</b> <code>get()</code></p>
|
|
<pre>
|
|
T& operator*() const;
|
|
</pre>
|
|
|
|
<p><b>Returns:</b> <code>get()</code></p>
|
|
|
|
<p><b>Requires:</b> <code>get() != 0</code></p>
|
|
<hr>
|
|
|
|
<h3>Release</h3>
|
|
<pre>
|
|
T* release();
|
|
</pre>
|
|
|
|
<p><b>Returns:</b> <code>get()</code></p>
|
|
|
|
<p><b>Postcondition:</b> *this holds the null pointer for the current
|
|
thread.</p>
|
|
<hr>
|
|
|
|
<h3>Reset</h3>
|
|
<pre>
|
|
void reset(T* p=0);
|
|
</pre>
|
|
|
|
<p><b>Effects:</b> If <code>get()!= p</code> then <code>delete
|
|
get()</code>.</p>
|
|
|
|
<p><b>Postconditions:</b> <code>*this</code> holds the pointer <code>
|
|
p</code> for the current thread.</p>
|
|
|
|
<p><b>Notes:</b> The pointer will be deleted when the thread
|
|
terminates.</p>
|
|
<hr>
|
|
|
|
<h2><a name="Example">Example Usage</a></h2>
|
|
<pre>
|
|
#include <a href=
|
|
"../../../boost/thread/thread.hpp"><boost/thread/thread.hpp></a>
|
|
#include <a href=
|
|
"../../../boost/thread/tss.hpp"><boost/thread/tss.hpp></a>
|
|
#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();
|
|
}
|
|
</pre>
|
|
<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:williamkempf@hotmail.com">
|
|
William E. Kempf</a> 2001 all rights reserved.</i></p>
|
|
</body>
|
|
</html>
|
|
|