| Home | Libraries | People | FAQ | More

## Scoped Threads

#### Synopsis

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

    struct detach;
    struct join_if_joinable;
    struct interrupt_and_join_if_joinable;
    template <class CallableThread = join_if_joinable>
    class strict_scoped_thread;
    template <class CallableThread = join_if_joinable>
    class scoped_thread;
    void swap(scoped_thread& lhs,scoped_thread& rhs) noexcept;

### Motivation

Based on the scoped_thread class defined in C++ Concurrency in Action Boost.Thread defines a thread wrapper class that instead of calling terminate if the thread is joinable on destruction, call a specific action given as template parameter.

While the scoped_thread class defined in C++ Concurrency in Action is closer to strict_scoped_thread class that doesn't allows any change in the wrapped thread, Boost.Thread provides a class scoped_thread that provides the same non-deprecated interface as `thread`.

### Tutorial

Scoped Threads are wrappers around a thread that allows the user to state what to do at destruction time. One of the common uses is to join the thread at destruction time so this is the default behavior. This is the single difference respect to a thread. While thread call std::terminate() on the destructor if the thread is joinable, strict_scoped_thread<> or scoped_thread<> join the thread if joinable.

The difference between strict_scoped_thread and scoped_thread is that the strict_scoped_thread hides completely the owned thread and so the user can do nothing with the owned thread other than the specific action given as parameter, while scoped_thread provide the same interface as `thread` and forwards all the operations.

    boost::strict_scoped_thread<> t1((boost::thread(f)));
    //t1.detach(); // compile fails
    boost::scoped_thread<> t2((boost::thread(f)));
    t2.detach();

### Free Thread Functors

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

    struct detach;
    struct join_if_joinable;
    struct interrupt_and_join_if_joinable;

#### Functor `detach`

    struct detach
    {
      void operator()(thread& t)
      {
        t.detach();
      }
    };

#### Functor `join_if_joinable`

    struct join_if_joinable
    {
      void operator()(thread& t)
      {
        if (t.joinable())
        {
          t.join();
        }
      }
    };

#### Functor `interrupt_and_join_if_joinable`

    struct interrupt_and_join_if_joinable
    {
      void operator()(thread& t)
      {
        t.interrupt();
        if (t.joinable())
        {
          t.join();
        }
      }
    };

### Class `strict_scoped_thread`

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

    template <class CallableThread = join_if_joinable>
    class strict_scoped_thread
    {
      thread t_; // for exposition purposes only
    public:

      strict_scoped_thread(strict_scoped_thread const&) = delete;
      strict_scoped_thread& operator=(strict_scoped_thread const&) = delete;

      explicit strict_scoped_thread(thread&& t) noexcept;
      template <typename F&&, typename ...Args>
      explicit strict_scoped_thread(F&&, Args&&...);

      ~strict_scoped_thread();

    };

RAII `thread` wrapper adding a specific destroyer allowing to master what can be done at destruction time.

CallableThread: A callable `void(thread&)`.

The default is a `join_if_joinable`.

Thread destructor terminates the program if the `thread` is joinable. This wrapper can be used to join the thread before destroying it.

##### Example

    boost::strict_scoped_thread<> t((boost::thread(F)));

#### Constructor from a `thread`

    explicit strict_scoped_thread(thread&& t) noexcept;

Effects:

  move the thread to own `t_`

Throws:

  Nothing

#### Move Constructor from a Callable

    template <typename F&&, typename ...Args>
    explicit strict_scoped_thread(F&&, Args&&...);

Effects:

  Construct an internal thread in place.

Postconditions:

  `*this.t_` refers to the newly created thread of execution and `this->get_id()!=thread::id()`.

Throws:

  Any exception the thread construction can throw.

#### Destructor

    ~strict_scoped_thread();

Effects:

  Equivalent to `CallableThread()(t_)`.

Throws:

  Nothing: The `CallableThread()(t_)` should not throw when joining the thread as the scoped variable is on a scope outside the thread function.

### Class `scoped_thread`

    #include <boost/thread/scoped_thread.hpp>

    template <class CallableThread>
    class scoped_thread
    {
      thread t_; // for exposition purposes only
    public:
        scoped_thread() noexcept;
        scoped_thread(const scoped_thread&) = delete;
        scoped_thread& operator=(const scoped_thread&) = delete;

        explicit scoped_thread(thread&& th) noexcept;
        template <typename F&&, typename ...Args>
        explicit scoped_thread(F&&, Args&&...);

        ~scoped_thread();

        // move support
        scoped_thread(scoped_thread && x) noexcept;
        scoped_thread& operator=(scoped_thread && x) noexcept;

        void swap(scoped_thread& x) noexcept;

        typedef thread::id id;

        id get_id() const noexcept;

        bool joinable() const noexcept;
        void join();
    #ifdef BOOST_THREAD_USES_CHRONO
        template <class Rep, class Period>
        bool try_join_for(const chrono::duration<Rep, Period>& rel_time);
        template <class Clock, class Duration>
        bool try_join_until(const chrono::time_point<Clock, Duration>& t);
    #endif

        void detach();

        static unsigned hardware_concurrency() noexcept;
        static unsigned physical_concurrency() noexcept;

        typedef thread::native_handle_type native_handle_type;
        native_handle_type native_handle();

    #if defined BOOST_THREAD_PROVIDES_INTERRUPTIONS
        void interrupt();
        bool interruption_requested() const noexcept;
    #endif

    };

    void swap(scoped_thread& lhs,scoped_thread& rhs) noexcept;

RAII `thread` wrapper adding a specific destroyer allowing to master what can be done at destruction time.

CallableThread: A callable void(thread&). The default is join_if_joinable.

Thread destructor terminates the program if the thread is joinable. This wrapper can be used to join the thread before destroying it.

Remark: `scoped_thread` is not a `thread` as `thread` is not designed to be derived from as a polymorphic type.

Anyway `scoped_thread` can be used in most of the contexts a `thread` could be used as it has the same non-deprecated interface with the exception of the construction.

##### Example

    boost::scoped_thread<> t((boost::thread(F)));
    t.interrupt();

#### Default Constructor

    scoped_thread() noexcept;

Effects:

  Constructs a scoped_thread instance that wraps to Not-a-Thread.

Postconditions:

  `this->get_id()==thread::id()`

Throws:

  Nothing

#### Move Constructor

    scoped_thread(scoped_thread&& other) noexcept;

Effects:

  Transfers ownership of the scoped_thread managed by `other` (if any) to the newly constructed scoped_thread instance.

Postconditions:

  `other.get_id()==thread::id()` and `get_id()` returns the value of `other.get_id()` prior to the construction

Throws:

  Nothing

#### Move assignment operator

    scoped_thread& operator=(scoped_thread&& other) noexcept;

Effects:

  Transfers ownership of the scoped_thread managed by `other` (if any) to `*this`.

  - if defined `BOOST_THREAD_DONT_PROVIDE_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE`: If there was a `scoped_thread` previously associated with `*this` then that `scoped_thread` is detached, DEPRECATED

  - if defined `BOOST_THREAD_PROVIDES_THREAD_MOVE_ASSIGN_CALLS_TERMINATE_IF_JOINABLE`: If the `scoped_thread` is joinable calls to std::terminate.

Postconditions:

  `other->get_id()==thread::id()` and `get_id()` returns the value of `other.get_id()` prior to the assignment.

Throws:

  Nothing

#### Move Constructor from a `thread`

    scoped_thread(thread&& t);

Effects:

  Transfers ownership of the thread managed by `other` (if any) to the newly constructed scoped_thread instance.

Postconditions:

  other.get_id()==thread::id() and get_id() returns the value of other.get_id() prior to the construction.

Throws:

  Nothing

#### Move Constructor from a Callable

    template <typename F&&, typename ...Args>
    explicit scoped_thread(F&&, Args&&...);

Effects:

  Construct an internal thread in place.

Postconditions:

  `*this.t_` refers to the newly created thread of execution and `this->get_id()!=thread::id()`.

Throws:

  Any exception the thread construction can throw.

#### Destructor

    ~scoped_thread();

Effects:

  Equivalent to `CallableThread()(t_)`.

Throws:

  Nothing: The `CallableThread()(t_)` should not throw when joining the thread as the scoped variable is on a scope outside the thread function.

#### Member function `joinable()`

    bool joinable() const noexcept;

Returns:

  Equivalent to return t_.joinable().

Throws:

  Nothing

#### Member function `join()`

    void join();

Effects:

  Equivalent to t_.join().

#### Member function `try_join_for()`

    template <class Rep, class Period>
    bool try_join_for(const chrono::duration<Rep, Period>& rel_time);

Effects:

  Equivalent to return `t_.try_join_for(rel_time)`.

#### Member function `try_join_until()`

    template <class Clock, class Duration>
    bool try_join_until(const chrono::time_point<Clock, Duration>& abs_time);

Effects:

  Equivalent to return `t_.try_join_until(abs_time)`.

#### Member function `detach()`

    void detach();

Effects:

  Equivalent to `t_.detach()`.

#### Member function `get_id()`

    thread::id get_id() const noexcept;

Effects:

  Equivalent to return `t_.get_id()`.

#### Member function `interrupt()`

    void interrupt();

Effects:

  Equivalent to `t_.interrupt()`.

#### Static member function `hardware_concurrency()`

    unsigned hardware_concurrency() noexecpt;

Effects:

  Equivalent to return `thread::hardware_concurrency()`.

#### Static member function `physical_concurrency()`

    unsigned physical_concurrency() noexecpt;

Effects:

  Equivalent to return `thread::physical_concurrency()`.

#### Member function `native_handle()`

    typedef thread::native_handle_type native_handle_type;
    native_handle_type native_handle();

Effects:

  Equivalent to return `t_.native_handle()`.

#### Member function `swap()`

    void swap(scoped_thread& other) noexcept;

Effects:

  Equivalent `t_.swap(other.t_)`.

### Non-member function `swap(scoped_thread&,scoped_thread&)`

    #include <boost/thread/scoped_thread.hpp>

    void swap(scoped_thread& lhs,scoped_thread& rhs) noexcept;

Effects:

  `lhs.swap(rhs)`.