| Home | Libraries | People | FAQ | More

## Class thread

boost::thread —

The thread class represents threads of execution, and provides the functionality to create and manage threads within the Boost.Threads library. See Glossary for a precise description of thread of execution, and for definitions of threading-related terms and of thread states such as blocked.

## Synopsis

    class thread : private boost::noncopyable   // Exposition only
    {
    public:
      // construct/copy/destruct
      thread();
      explicit thread(const boost::function0<void>&);
      ~thread();

      // comparison
      bool operator==() const;
      bool operator!=() const;

      // modifier
      void join();

      // static
      static void sleep(const xtime&);
      static void yield();
    };

## Description

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 thread object's constructor.

A thread of execution is said to be "finished" or to have "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()` first having been called, the thread of execution continues until its initial function completes.

### `thread` construct/copy/destruct

1.     thread();

   Effects: Constructs a thread object representing the current thread of execution.
   Postconditions: `*this` is non-joinable.
   Notes: Danger:`*this` is valid only within the current thread.

2.     explicit 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.
   Postconditions: `*this` is joinable.
   Throws: `boost::thread_resource_error` if a new thread of execution cannot be started.

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

### `thread` comparison

1.     bool operator==( rhs) const;

   Requires: The thread is non-terminated or `*this` is joinable.
   Returns: `true` if `*this` and `rhs` represent the same thread of execution.

2.     bool operator!=( rhs) const;

   Requires: The thread is non-terminated or `*this` is joinable.
   Returns: `!(*this==rhs)`.

### `thread` modifier

1.     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.
   Notes: If `*this == thread()` the result is implementation-defined. If the implementation doesn't detect this the result will be deadlock.

### `thread` static

1.     static void sleep(const xtime& xt);

   Effects: The current thread of execution blocks until `xt` is reached.

2.     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.

| Copyright © 2001-2003 William E. Kempf