Boost.Threads

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 Formal Definition of "Thread" for a precise description of "thread of execution", and definitions 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, and any associated implementation resources have been released.

Except as described below, the policy used by an implementation of Boost.Threads to schedule transitions between thread states is unspecified.

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& other) const;
    bool operator!=(const thread& other) const;

    void join();
    bool try_join();
    bool timed_join(const xtime& xt);

    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.

    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.

Throws: std::bad_alloc if a new thread of execution cannot be started.

Destructor

    ~thread();

Effects: Destroys the thread object. The actual thread of execution may continue to execute after the thread object has been destroyed.

Notes: To ensure a thread of execution runs to completion before the thread object is destroyed, call join().

Comparison Operators

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

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

join

    void join();

Requires: *this != thread()

Effects: The current thread of execution blocks until the thread of execution represented by *this finishes. In other words, causes the currently executing thread of execution to "join" the associated running thread of execution.

try_join

    bool try_join();

Requires: *this != thread()

Returns: true if the thread of execution represented by *this has finished execution.

Notes: try_join() is in effect a non-blocking attempt to "join".

timed_join

    bool timed_join(const xtime& xt);

Requires: *this != thread()

Effects: The current thread of execution blocks until either the thread of execution represented by *this finishes or the time specified by xt expires.

Returns: true if the thread of execution represented by *this finished execution.

Notes: timed_join() is in effect an attempt to "join" which only blocks for a specified time.

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. Also 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 19 July, 2001