# Boost.Threads - <boost/thread.hpp>

###

# Boost.Threads

## Header <boost/thread.hpp>

## Contents

Introduction
Classes

Class `thread`

Class `thread` synopsis
Class `thread` constructors and destructor
Class `thread` comparison functions
Class `thread` modifier functions
Class `thread` static functions

Class `thread_group`

Class `thread_group` synopsis
Class `thread_group` constructors and destructor
Class `thread_group` modifier functions

Example(s)

Simple usage of `boost::thread`
Simple usage of `boost::thread_group`

## Introduction

The header <boost/thread.hpp> defines the classes thread and thread_group which are used to create, observe and manage threads and groups of threads.

## Classes

### Class `thread`

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.

#### Class `thread` synopsis

    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

#### Class `thread` constructors and destructor

    thread();

Effects: Constructs a `thread` object representing the current thread of execution.
Postconditions: `*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.
Postconditions: `*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.
Note: 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()`.

#### Class `thread` comparison functions

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

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) const;

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

#### Class `thread` modifier functions

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

#### Class `thread` static functions

    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.

### Class `thread_group`

The `thread_group` class provides a container for easy grouping of threads to simplify several common thread creation and management idioms.

All `thread_group` member functions are thread-safe, except destruction.

#### Class `thread_group` synopsis

    namespace boost {
        class thread_group : boost::noncopyable
        {
        public:
            thread_group();
            ~thread_group();

            thread* create_thread(const boost::function0<void>& threadfunc);
            void add_thread(thread* thrd);
            void remove_thread(thread* thrd);
            void join_all();
        };
    } // namespace boost

#### Class `thread_group` constructors and destructor

    thread_group();

Effects: Constructs an empty `thread_group` container.

    ~thread_group();

Effects: Destroys each contained thread object. Destroys `*this`.
Notes: Behavior is undefined if another thread references *this during the execution of the destructor.

#### Class `thread_group` modifier functions

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

Effects: Creates a new `thread` object that executes `threadfunc` and adds it to the `thread_group` container object's list of managed `thread` objects.
Returns: Pointer to the newly created thread.

    void add_thread(thread* thrd);

Effects: Adds `thrd` to the `thread_group` object's list of managed `thread` objects. The `thrd` object must have been allocated via operator new and will be deleted when the group is destroyed.

    Void remove_thread(thread* thrd);

Effects: Removes `*this`'s list of managed `thread` objects.
Throws: ? if `thrd` is not it `*this`'s list of managed `thread` objects.

    Void join_all();

Effects: Calls `join()` on each of the managed `thread` objects.

## Functions

    {{function}}

Requires: {{text}}
Effects: {{text}}
Postconditions: {{text}}
Returns: {{text}}
Throws: {{text}}
Complexity: {{text}}
Rationale: {{text}}

## Objects

{{Object specifications}}

## Example(s)

### Simple usage of `boost::thread`

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

### Simple usage of `boost::thread_group`

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

    int count = 0;
    boost::mutex mutex;

    void increment_count()
    {
       boost::mutex::lock lock(mutex);
       std::cout << "count = " << ++count << std::endl;
    }

    int main(int argc, char* argv[])
    {
       boost::thread_group threads;
       for (int i = 0; i < 10; ++i)
          threads.create_thread(&increment_count);
       threads.join_all();
    }

The output is:

    count = 1
    count = 2
    count = 3
    count = 4
    count = 5
    count = 6
    count = 7
    count = 8
    count = 9
    count = 10

Revised 05 November, 2001

© Copyright William E. Kempf 2001-2002. All Rights Reserved.

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.