|
|
Boost.ThreadsClass thread |
Introduction
Header
Synopsis
Members
Example
The thread class represents threads of execution, and
provides the functionality to create and manage threads within the
Boost.Threads library. See
Definitions for a precise description of "thread of
execution", and for definitions of threading related terms and of
thread states such as "blocked".
A thread of execution has an initial function. For the program's
initial thread, the initial function is main(). For other
threads, the initial function is operator() of the
function object passed to the class thread
constructor.
A thread of execution is said to be "finished" or "finished execution" when its initial function returns or is terminated. This includes completion of all thread cleanup handlers, and completion of the normal C++ function return behaviors, such as destruction of automatic storage (stack) objects and releasing any associated implementation resources.
A thread object has an associated state which is either "joinable" or "non-joinable".
Except as described below, the policy used by an implementation of Boost.Threads to schedule transitions between thread states is unspecified.
Note: Just as the lifetime of a file may be different from
the lifetime of an iostream object which represents the file, the
lifetime of a thread of execution may be different from the
thread object which represents the thread of execution. In
particular, after a call to join(), the thread of
execution will no longer exist even though the thread
object continues to exist until the end of its normal lifetime. The
converse is also possible; if a thread object is destroyed
without join() having first been called, the thread of
execution continues until its initial function completes.
#include <boost/thread/thread.hpp>
namespace boost {
class thread : boost::noncopyable // Exposition only.
// Class thread meets the NonCopyable requirement.
{
public:
thread();
explicit thread(const boost::function0<void>& threadfunc);
~thread();
bool operator==(const thread& rhs) const;
bool operator!=(const thread& rhs) const;
void join();
static void sleep(const xtime& xt);
static void yield();
};
} // namespace boost
thread();
Effects: Constructs a thread object representing
the current thread of execution.
Postcondition: *this is non-joinable.
Danger: *this is valid only within the current
thread.
thread(const boost::function0<void>& threadfunc);
Effects: Starts a new thread of execution and constructs a
thread object representing it. Copies
threadfunc (which in turn copies the function object wrapped by
threadfunc) to an internal location which persists for the
lifetime of the new thread of execution. Calls operator()
on the copy of the threadfunc function object in the new
thread of execution.
Postcondition: *this is joinable.
Throws: boost::thread_resource_error if a new
thread of execution cannot be started.
~thread();
Effects: Destroys *this. The actual thread of
execution may continue to execute after the thread object
has been destroyed.
Notes: If *this is joinable the actual thread of
execution becomes "detached". Any resources used by the
thread will be reclaimed when the thread of execution completes. To
ensure such a thread of execution runs to completion before the
thread object is destroyed, call join().
bool operator==(const thread& rhs);
Requires: The thread is non-terminated or *this
is joinable.
Returns: true if *this and
rhs represent the same thread of execution.
bool operator!=(const thread& rhs);
Returns: !(*this==rhs).
void join();
Requires: *this is joinable.
Effects: The current thread of execution blocks until the
initial function of the thread of execution represented by
*this finishes and all resources are reclaimed.
Postcondition: *this is non-joinable.
Note: If *this == thread() the result is
implementation defined. If the implementation doesn't detect this
the result will be
deadlock.
static void sleep(const xtime& xt);
Effects: The current thread of execution blocks until
xt is reached.
static void yield();
Effects: The current thread of execution is placed in the "ready" state.
Notes: Allow the current thread to give up the rest of its time slice (or other scheduling quota) to another thread. Particularly useful in non-preemptive implementations.
#include <boost/thread/thread.hpp>
#include <iostream>
struct thread_alarm
{
thread_alarm(int secs) : m_secs(secs) { }
void operator()()
{
boost::xtime xt;
boost::xtime_get(&xt, boost::TIME_UTC);
xt.sec += m_secs;
boost::thread::sleep(xt);
std::cout << "alarm sounded..." << std::endl;
}
int m_secs;
};
int main(int argc, char* argv[])
{
int secs = 5;
std::cout << "setting alarm for 5 seconds..." << std::endl;
thread_alarm alarm(secs);
boost::thread thrd(alarm);
thrd.join();
}
The output is:
setting alarm for 5 seconds... alarm sounded...
Revised 05 November, 2001
© Copyright William E. Kempf 2001 all rights reserved.