mirror of
https://github.com/boostorg/thread.git
synced 2026-01-23 06:02:14 +00:00
208 lines
8.4 KiB
HTML
208 lines
8.4 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/thread_pool.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/thread_pool.hpp">boost/thread/thread_pool.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_pool">Class <code>thread_pool</code></a></dt>
|
|
<dl class="page-index">
|
|
<dt><a href="#class-thread_pool-synopsis">Class <code>thread_pool</code> synopsis</a></dt>
|
|
<dt><a href="#class-thread_pool-ctors">Class <code>thread_pool</code> constructors and destructor</a></dt>
|
|
<dt><a href="#class-thread_pool-modifiers">Class <code>thread_pool</code> modifier functions</a></dt>
|
|
</dl>
|
|
</dl>
|
|
<dt><a href="#examples">Example(s)</a></dt>
|
|
</dl>
|
|
<hr>
|
|
<h2><a name="introduction"></a>Introduction</h2>
|
|
<p>Include the header <<a href="../../../boost/thread/thread_pool.hpp">boost/thread/thread_pool.hpp</a>>
|
|
to define the <a href="#class-thread_pool">thread_pool</a> class.</p>
|
|
<h2><a name="classes"></a>Classes</h2>
|
|
<h3><a name="class-thread_pool"></a>Class <code>thread_pool</code></h3>
|
|
|
|
<p>The <tt>thread_pool</tt> class provides an interface for running
|
|
jobs on a dynamically managed set of worker threads called a pool.
|
|
When a job is added, it can execute on any available thread in the pool.
|
|
This class controls both the maximum and minimum number of threads in
|
|
the pool. If a thread in the pool is sitting idle for a period of
|
|
time, it will exit unless by exiting the number of threads would dip below
|
|
the minimum. Thread pools provide an optimization over creating a new thread
|
|
for each job since the pool can often remove the overhead of thread creation.</p>
|
|
<h4><a name="class-thread_pool-synopsis"></a>Class <code>thread_pool</code> synopsis</h4>
|
|
<pre>
|
|
namespace boost
|
|
{
|
|
class thread_pool : <a href="../../utility/utility.htm#Class noncopyable">boost::noncopyable</a> // Exposition only.
|
|
// Class thread meets the <a href="overview.html#non-copyable">NonCopyable</a> requirement.
|
|
{
|
|
public:
|
|
thread_pool(int max_threads=std::numeric_limits<int>::max(),
|
|
int min_threads=0,
|
|
int timeout_secs=5);
|
|
~thread_pool();
|
|
|
|
void add(const boost::function0<void> &job);
|
|
void join();
|
|
void cancel();
|
|
void detach();
|
|
};
|
|
};
|
|
</pre>
|
|
<h4><a name="class-spec-ctors"></a>Class <code>thread_pool</code> constructors and destructor</h4>
|
|
<pre>
|
|
thread_pool(int max_threads=std::numeric_limits<int>::max(),
|
|
int min_threads=0,
|
|
int timeout_secs=5);
|
|
</pre>
|
|
<dl class="function-semantics">
|
|
<dt><b>Effects:</b> Constructs a thread pool object and starts min_threads threads
|
|
running in the pool.</dt>
|
|
</dl>
|
|
<pre>
|
|
~thread_pool();
|
|
</pre>
|
|
<dl class="function-semantics">
|
|
<dt><b>Effects:</b> Calls join() if neither join() nor detach() were called
|
|
previously for this thread_pool. If detach() was not called, destroys all
|
|
resources associated with the threads in the pool and with the queue of jobs
|
|
still waiting to be executed.</dt>
|
|
</dl>
|
|
<h4><a name="class-spec-modifiers"></a>Class <code>thread_pool</code> modifier
|
|
functions</h4>
|
|
<pre>
|
|
void add(const boost::function0<void>& job);
|
|
</pre>
|
|
<dl class="function-semantics">
|
|
<dt><b>Effects:</b> Adds <tt>job</tt> to the <tt>thread_pool</tt> object's list of
|
|
jobs waiting to be executed. If any threads in the pool are idle, the job
|
|
will be execute as soon as the idle thread is scheduled by the operating
|
|
system. If no threads are idle and the number of threads in the pool is
|
|
less than the maximum number provided to the constructor, an additional thread
|
|
is created and added to the pool. That new thread will execute this job
|
|
as soon as it is scheduled by the operating system. If no threads are
|
|
idle and the thread count is at the maximum, this job will be queued until
|
|
a thread becomes available. Currently, queued jobs are processed in FIFO
|
|
order.</dt>
|
|
<dt><b>Throws:</b> std::runtime_error if join() or detach() have
|
|
previously been called for this thread_pool object.</dt>
|
|
</dl>
|
|
<pre>
|
|
void detach();
|
|
</pre>
|
|
<dl class="function-semantics">
|
|
<dt><b>Effects:</b> Relinquishes control of the pool of threads by this thread_pool
|
|
object. Any threads in the pool will continue to run and continue to
|
|
process any queued jobs, but no new threads will be created, and any subsequent
|
|
attempts to add new jobs will result in an exception.</dt>
|
|
<dt><b>Throws:</b> std::runtime_error if join() has previously
|
|
been called for this thread_pool object.</dt>
|
|
</dl>
|
|
<pre>
|
|
void cancel();
|
|
</pre>
|
|
<dl class="function-semantics">
|
|
<dt><b>Effects:</b> Removes all queued jobs from the thread_pool's internal queue,
|
|
and calls cancel() on all boost::thread objects in the pool. The specific
|
|
behavior of those threads will be dictated by their cancellation behavior - the
|
|
pool threads may be executing a user's job that deferrs cancellation, for
|
|
example.</dt>
|
|
<dt><b>Throws:</b> std::runtime_error if join() or detach() have
|
|
previously been called for this thread_pool object.</dt>
|
|
<dt><b>Note:</b> for the current version (1.27.0) of Boost.Threads, thread::cancel() is
|
|
not provided. This function -will- clear out all queued jobs, but any
|
|
currently executing jobs will not be cancelled.</dt>
|
|
</dl>
|
|
<pre>
|
|
void join();
|
|
</pre>
|
|
<dl class="function-semantics">
|
|
<dt><b>Effects:</b> Waits until all queued jobs are completed by the thread pool,
|
|
and then join()s will all of the threads in the pool. When join()
|
|
returns, no running threads will remain in the pool, and this object is invalid
|
|
for anything except destruction. Any calls to cancel(), join(), detach(),
|
|
or add() will result in an exception.</dt>
|
|
</dl>
|
|
<h2><a name="examples"></a>Example(s)</h2>
|
|
<pre>
|
|
#include <boost/thread/thread_pool.hpp>
|
|
#include <boost/thread/mutex.hpp>
|
|
#include <iostream>
|
|
|
|
boost::mutex io_mutex;
|
|
|
|
class job_adapter {
|
|
public:
|
|
job_adapter(void (*func)(int), int param) :
|
|
_func(func), _param(param){ }
|
|
void operator()() const { _func(_param); }
|
|
private:
|
|
void (*_func)(int);
|
|
int _param;
|
|
};
|
|
|
|
void simple_job(int param)
|
|
{
|
|
boost::mutex::scoped_lock l(io_mutex);
|
|
std::cout << param << " squared is " << (param*param) << "\n";
|
|
}
|
|
|
|
int main(int argc, char* argv[])
|
|
{
|
|
boost::thread_pool tp;
|
|
for (int i = 1; i <= 10; ++i)
|
|
tp.add(simple_job);
|
|
tp.join();
|
|
return 0;
|
|
}
|
|
</pre>
|
|
<p>Typical output would be:</p>
|
|
<pre>
|
|
1 squared is 1
|
|
2 squared is 4
|
|
3 squared is 9
|
|
4 squared is 16
|
|
5 squared is 25
|
|
7 squared is 49
|
|
6 squared is 36
|
|
8 squared is 64
|
|
10 squared is 100
|
|
9 squared is 81
|
|
</pre>
|
|
<P>While the jobs are dispatched in the order they are received, the scheduling of
|
|
the individual threads in the pool is platform-dependent.</P>
|
|
<P>
|
|
<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>, David Moore 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>
|