Boost.Threads

Class thread

Introduction
Header
Synopsis
Members
Example

Introduction

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.

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.

Header

#include <boost/thread/thread.hpp>

Synopsis

namespace boost {

class thread : boost::noncopyable
{
public:
    thread();
    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

Members

Constructors

    thread();

Effects: Constructs a thread object for the current thread of execution.

Notes: *this is not "joinable".

Danger: *this is valid only within the current thread.

    thread(const boost::function0<void>& threadfunc);

Effects: Starts a new thread of execution. 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.

Notes: *this is "joinable".

Throws: boost::thread_resource_error if a new thread of execution cannot be started.

Destructor

    ~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().

Comparison Operators

    bool operator==(const thread& rhs);
    bool operator!=(const thread& rhs);

Requires: The thread to still be running or *this to be "joinable".

Returns: true if *this and rhs represent the same thread of execution.

join

    void join();

Requires: *this != thread() and *this to be "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 no longer "joinable".

sleep

    static void sleep(const xtime& xt);

Effects: The current thread of execution blocks until xt.

yield

    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.

Example Usage

#include <boost/thread/thread.hpp>
#include <iostram>

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;
   boost::thread thrd(thread_alarm(5));
   thrd.join();
}

The output is:

setting alarm for 5 seconds...
alarm sounded...

Revised 10 August, 2001