third_party/boost/thread/doc/async_executors.qbk

[/
 / Copyright (c) 2014-2017 Vicente J. Botet Escriba
 /
 / Distributed under the Boost Software License, Version 1.0. (See accompanying
 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 /]

[//////////////////////////////////////////////////////////]
[section:executors Executors and Schedulers -- EXPERIMENTAL]

[warning These features are experimental and subject to change in future versions. There are not too much tests yet, so it is possible that you can find out some trivial bugs :(] 

[note These features are based on the [@http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2013/n3785.pdf [*N3785 - Executors and Schedulers revision 3]] C++1y proposal from Chris Mysen, Niklas Gustafsson, Matt Austern, Jeffrey Yasskin. The text that follows has been adapted from this paper to show the differences.]

Executors are objects that can execute units of work packaged as function objects. Boost.Thread differs from N3785 mainly in the an Executor doesn't needs to inherit from an abstract class Executor. Static polymorphism is used instead and type erasure is used internally. 

[////////////////////]
[section Introduction]

Multithreaded programs often involve discrete (sometimes small) units of work that are executed asynchronously. This often involves passing work units to some component that manages execution. We already have boost::async, which potentially executes a function asynchronously and eventually returns its result in a future. (“As if” by launching a new thread.)

If there is a regular stream of small work items then we almost certainly don’t want to launch a new thread for each, and it’s likely that we want at least some control over which thread(s) execute which items. It is often convenient to represent that control as multiple executor objects. This allows programs to start executors when necessary, switch from one executor to another to control execution policy, and use multiple executors to prevent interference and thread exhaustion. Several possible implementations exist of the executor class and in practice there are a number of main groups of executors which have been found to be useful in real-world code (more implementations exist, this is simply a high level classification of them). These differ along a couple main dimensions, how many execution contexts will be used, how they are selected, and how they are prioritized. 

# Thread Pools
	# Simple unbounded thread pool, which can queue up an unbounded amount of work and maintains a dedicated set of threads (up to some maximum) which
dequeue and execute work as available.
	# Bounded thread pools, which can be implemented as a specialization of the previous ones with a bounded queue or semaphore, which limits the amount of queuing in an attempt to bound the time spent waiting to execute and/or limit resource utilization for work tasks which hold state which is expensive to hold.
	# Thread-spawning executors, in which each work always executes in a new thread.
	# Prioritized thread pools, which have works which are not equally prioritized such that work can move to the front of the execution queue if necessary. This requires a special comparator or prioritization function to allow for work ordering and normally is implemented as a blocking priority queue in front of the pool instead of a blocking queue. This has many uses but is a somewhat specialized in nature and would unnecessarily clutter the initial interface.
	# Work stealing thread pools, this is a specialized use case and is encapsulated in the ForkJoinPool in java, which allows lightweight work to be created by tasks in the pool and either run by the same thread for invocation efficiency or stolen by another thread without additional work. These have been left out until there is a more concrete fork-join proposal or until there is a more clear need as these can be complicated to implement

# Mutual exclusion executors
	# Serial executors, which guarantee all work to be executed such that no two works will execute concurrently. This allows for a sequence of operations to be queued in sequence and that sequential order is maintained and work can be queued on a separate thread but with no mutual exclusion required.
	# Loop executor, in which one thread donates itself to the executor to execute all queued work. This is related to the serial executor in that it guarantees mutual exclusion, but instead guarantees a particular thread will execute the work. These are particularly useful for testing purposes where code assumes an executor but testing code desires control over execution.
	# GUI thread executor, where a GUI framework can expose an executor interface to allow other threads to queue up work to be executed as part of the GUI thread. This behaves similarly to a loop executor, but must be implemented as a custom interface as part of the framework.

# Inline executors, which execute inline to the thread which calls submit(). This has no queuing and behaves like a normal executor, but always uses the caller’s thread to execute. This allows parallel execution of works, though. This type of executor is often useful when there is an executor required by an interface, but when for performance reasons it’s better not to queue work or switch threads. This is often very useful as an optimization for work continuations which should execute immediately or quickly and can also be useful for optimizations when an interface requires an executor but the work tasks are too small to justify the overhead of a full thread pool. 

A question arises of which of these executors (or others) be included in this library. There are use cases for these and many other executors. Often it is useful to have more than one implemented executor (e.g. the thread pool) to have more precise control of where the work is executed due to the existence of a GUI thread, or for testing purposes. A few core executors are frequently useful and these have been outlined here as the core of what should be in this library, if common use cases arise for alternative executor implementations, they can be added in the future. The current set provided here are: a basic thread pool `basic_thread_pool`, a serial executor `serial_executor`, a loop executor `loop_executor`, an inline executor `inline_executor` and a thread-spawning executor `thread_executor`.
[endsect]

[/
[/////////////////////////]
[section:tutorial Tutorial]


[endsect]
]
[////////////////]
[section:examples Examples]

[section:quick_sort Parallel Quick Sort]


  #include <boost/thread/executors/basic_thread_pool.hpp>
  #include <boost/thread/future.hpp> 
  #include <numeric>
  #include <algorithm>
  #include <functional>
  #include <iostream>
  #include <list>
  
  template<typename T>
  struct sorter
  {
      boost::basic_thread_pool pool;
      typedef std::list<T> return_type;
  
      std::list<T> do_sort(std::list<T> chunk_data)
      {
          if(chunk_data.empty()) {
              return chunk_data;
          }
  
          std::list<T> result;
          result.splice(result.begin(),chunk_data, chunk_data.begin());
          T const& partition_val=*result.begin();
  
          typename std::list<T>::iterator divide_point =
              std::partition(chunk_data.begin(), chunk_data.end(), 
                             [&](T const& val){return val<partition_val;});
  
          std::list<T> new_lower_chunk;
          new_lower_chunk.splice(new_lower_chunk.end(), chunk_data, 
                                 chunk_data.begin(), divide_point);
          boost::future<std::list<T> > new_lower = 
               boost::async(pool, &sorter::do_sort, this, std::move(new_lower_chunk));
          std::list<T> new_higher(do_sort(chunk_data));
          result.splice(result.end(),new_higher);
          while(!new_lower.is_ready()) {
              pool.schedule_one_or_yield();
          }
          result.splice(result.begin(),new_lower.get());
          return result;
      }
  };
  
  template<typename T>
  std::list<T> parallel_quick_sort(std::list<T>& input) {
      if(input.empty()) {
          return input;
      }
      sorter<T> s;
      return s.do_sort(input);
  }


[endsect]
[endsect]


[////////////////////////]
[section:rationale Design Rationale]

The authors of Boost.Thread have taken a different approach respect to N3785. Instead of basing all the design on an abstract executor class we make executor concepts. We believe that this is the good direction as a static polymorphic executor can be seen as a dynamic polymorphic executor using a simple adaptor. We believe also that it would make the library more usable, and more convenient for users.

The major design decisions concern deciding what a unit of work is, how to manage with units of work and time related functions in a polymorphic way.

An Executor is an object that schedules the closures that have been submitted to it, usually asynchronously. There could be multiple models of the Executor class. Some specific design notes:

* Thread pools are well know models of the Executor concept, and this library does indeed include a basic_thread_pool class, but other implementations also exist, including the ability to schedule work on GUI threads, scheduling work on a donor thread, as well as several specializations of thread pools.

* The choice of which executor to use is explicit. This is important for reasons described in the Motivation section. In particular, consider the common case of an asynchronous operation that itself spawns asynchronous operations. If both operations ran on the same executor, and if that executor had a bounded number of worker threads, then we could get deadlock. Programs often deal with such issues by splitting different kinds of work between different executors.

* Even if there could be a strong value in having a default executor, that can be used when detailed control is unnecessary, the authors don't know how to implement it in a portable and robust way.

* The library provides Executors based on static and dynamic polymorphism. The static polymorphism interface is intended to be used on contexts that need to have the best performances. The dynamic polymorphism interface has the advantage to been able to change the executor a function is using without making it a template and is possible to pass executors across a binary interface. For some applications, the cost of an additional virtual dispatch could be almost certainly negligible compared to the other operations involved.

* Conceptually, an executor puts closures on a queue and at some point executes them. The queue is always unbounded, so adding a closure to an executor never blocks. (Defining “never blocks” formally is challenging, but informally we just mean that submit() is an ordinary function that executes something and returns, rather than waiting for the completion of some potentially long running operation in another thread.)

[heading Closure]

One important question is just what a closure is. This library has a very simple answer: a closure is a `Callable` with no parameters and returning `void`. 

N3785 choose the more specific `std::function<void()>` as it provides only dynamic polymorphism and states that in practice the implementation of a template based approach or another approach is impractical. The authors of this library think that the template based approach is compatible with a dynamic based approach. They give some arguments:

The first one is that a virtual function can not be a template. This is true but it is also true that the executor interface can provide the template functions that call to the virtual public functions. Another reason they give is that "a template parameter would complicate the interface without adding any real generality. In the end an executor class is going to need some kind of type erasure to handle all the different kinds of function objects with `void()` signature, and that’s exactly what std::function already does". We think that it is up to the executor to manage with this implementation details, not to the user.

We share all the argument they give related to the `void()` interface of the work unit. A work unit is a closure that takes no arguments and returns no value. This is indeed a limitation on user code, but combined with `boost::async` taking executors as parameters the user has all what she needs.

The third one is related to performance. They assert that "any mechanism for storing closures on an executor’s queue will have to use some form of type erasure. There’s no reason to believe that a custom closure mechanism, written just for std::executor and used nowhere else within the standard library, would be better in that respect than `std::function<void()>`". We believe that the implementation can do better that storing the closure on a `std::function<void()>`. e.g. the implementation can use intrusive data to store the closure and the pointers to other nodes needed to store the closures in a given order. 

In addition `std::function<void()>` can not be constructed by moving the closure, so e.g. `std::packaged_task` could not be a Closure.

[/
[heading Scheduled work]

The approach of this library respect to scheduled work of the N3785 proposal is quite different. Instead of adding the scheduled operations to a specific scheduled_executor polymorphic interface, we opt by adding two member template functions to a class scheduled_executor that wraps an existing executor. This has several advantages:

* The scheduled operations are available for all the executors.
* The template functions could accept any chrono `time_point` and `duration` respectively as we are not working with virtual functions.

In order to manage with all the clocks, there are two alternatives:

* transform the submit_at operation to a `submit_after` operation and let a single `scheduled_executor` manage with a single clock.
* have a single instance of a `scheduled_executor<Clock>` for each `CLock`.

The library chose the first of those options, largely for simplicity.
]

[heading Scheduled work]

The approach of this library respect to scheduled work of the N3785 proposal is quite different. Instead of adding the scheduled operations to a specific scheduled_executor polymorphic interface, we opt by adding a specific `scheduler` class that is not an executor and knows how to manage with the scheduling of timed tasks `submit_at`/`submit_after`. 


`scheduler` provides executor factories `at`/`after` given a specific `time_point` or a `duration`. The built executors wrap a reference to this scheduler and the time at which the submitted task will be executed. 

If we want to schedule these operations on an existing executor (as `serial_executor` does), these classes provide a `on` factory taking another  executor as parameter and wraps both instance on the returned executor. 

      sch.on(tp).after(seconds(i)).submit(boost::bind(fn,i));

This has several advantages:

* The scheduled operations are available for all the executors via wrappers.
* The template functions could accept any chrono `time_point` and `duration` respectively as we are not working with virtual functions.

In order to manage with all the clocks, this library propose generic solution. `scheduler<Clock>` know how to manage with the `submit_at`/`submit_after` `Clock::time_point`/`Clock::duration` tasks. Note that the durations on different clocks differ.

[heading Not Handled Exceptions]
As in N3785 and based on the same design decision than `std`/`boost::thread` if a user closure throws an exception, the executor must call the `std::terminate` function.
Note that when we combine `boost::async` and `Executors`, the exception will be caught by the closure associated to the returned future, so that the exception is stored on the returned future, as for the other `async` overloads.

[heading At thread entry]

It is common idiom to set some thread local variable at the beginning of a thread. As Executors could instantiate threads internally these Executors shall have the ability to call a user specific function at thread entry on the executor constructor.

For executors that don't instantiate any thread and that would use the current thread this function shall be called only for the thread calling the `at_thread_entry` member function. 

[heading Cancelation]

The library does not provision yet for the ability to cancel/interrupt work, though this is a commonly requested feature.

This could be managed externally by an additional cancelation object that can be shared between the creator of the unit of work and the unit of work. 

We can think also of a cancelable closure that could be used in a more transparent way.

An alternative is to make async return a cancelable_task but this will need also a cancelable closure.


[/
The library would provide in the future a cancelable_task that could support cancelation.

  class cancelation_state
  {
    std::atomic<bool> requested;
    std::atomic<bool> enabled;
    std::condition_variable* cond;
    std::mutex cond_mutex;
  public:
    cancelation_state() :
      thread_cond(0)
    {
    }
    void cancel()
    {
      requested.store(true, std::memory_order_relaxed);
      std::lock_guard < std::mutex > lk(cond_mutex);
      if (cond)
      {
        cond->notify_all();
      }
    }
    bool cancellation_requested() const
    {
      return requested.load(std::memory_order_relaxed);
    }
    void enable()
    {
      enable.store(true, std::memory_order_relaxed);
    }
    void disable()
    {
      enable.store(false, std::memory_order_relaxed);
    }
    bool cancellation_enabled() const
    {
      return enabled.load(std::memory_order_relaxed);
    }
    void set_condition_variable(std::condition_variable& cv)
    {
      std::lock_guard < std::mutex > lk(cond_mutex);
      cond = &cv;
    }
    void clear_condition_variable()
    {
      std::lock_guard < std::mutex > lk(cond_mutex);
      cond = 0;
    }
    struct clear_cv_on_destruct
    {
      ~clear_cv_on_destruct()
      {
        this_thread_interrupt_flag.clear_condition_variable();
      }
    };
    void cancelation_point();
    void cancelable_wait(std::condition_variable& cv, std::unique_lock<std::mutex>& lk)
    {
      cancelation_point();
      this_cancelable_state.set_condition_variable(cv);
      this_cancelable_state::clear_cv_on_destruct guard;
      interruption_point();
      cv.wait_for(lk, std::chrono::milliseconds(1));
      this_cancelable_state.clear_condition_variable();
      cancelation_point();
    }
    class disable_cancelation
    {
    public:
      disable_cancelation(const disable_cancelation&)= delete;
      disable_cancelation& operator=(const disable_cancelation&)= delete;
      disable_cancelation(cancelable_closure& closure)
  noexcept    ;
      ~disable_cancelation() noexcept;
    };
    class restore_cancelation
    {
    public:
      restore_cancelation(const restore_cancelation&) = delete;
      restore_cancelation& operator=(const restore_cancelation&) = delete;
      explicit restore_cancelation(cancelable_closure& closure, disable_cancelation& disabler) noexcept;
      ~restore_cancelation() noexcept;
    };
  };
  
  template <class Closure>
  struct cancelable_closure_mixin: cancelable_closure
  {
    void operator()
    {
      cancel_point();this->Closure::run();
    }
  };
  
  struct my_clousure: cancelable_closure_mixin<my_clousure>
  {
    void run()
    {
      while ()
      {
        cancel_point();
      }
    }
  }
]

[heading Current executor]

The library does not provision for the ability to get the current executor, though having access to it could simplify a lot the user code.

The reason is that the user can always use a thread_local variable and reset it using the `at_thread_entry ` member function.

	thread_local current_executor_state_type current_executor_state;
	executor* current_executor() { return current_executor_state.current_executor(); }
	basic_thread_pool pool(
		// at_thread_entry
		[](basic_thread_pool& pool) { 
			current_executor_state.set_current_executor(pool);
		}
	);

[
[heading Default executor]

The library authors share some of the concerns of the C++ standard committee (introduction of a new single shared resource, a singleton, could make it difficult to make it portable to all the environments) and that this library doesn't need to provide a default executor for the time been. 

The user can always define his default executor himself.

	boost::generic_executor_ref default_executor()
	{
  		static boost::basic_thread_pool tp(4);
  		return generic_executor_ref(tp);
	}


[endsect]


[/////////////////////]
[section:ref Reference]


[////////////////////////////////]
[section:concept_closure Concept `Closure`]


A type `E` meets the `Closure` requirements if is a model of `Callable(void())` and a model of `CopyConstructible`/`MoveConstructible`.

[endsect]
[////////////////////////////////]
[section:concept_executor  Concept `Executor`]

The `Executor` concept models the common operations of all the executors.
 
A type `E` meets the `Executor` requirements if the following expressions are well-formed and have the specified semantics 

* `e.submit(lc);`
* `e.submit(rc);`
* `e.close();`
* `b = e.closed();`
* `e.try_executing_one();`
* `e.reschedule_until(p);`

where 

* `e` denotes a value of type `E`, 
* `lc` denotes a lvalue reference of type `Closure`, 
* `rc` denotes a rvalue reference of type `Closure`
* `p` denotes a value of type `Predicate`

[/////////////////////////////////////]
[section:submitlc `e.submit(lc);`]

[variablelist

[[Effects:] [The specified closure will be scheduled for execution at some point in the future.
If invoked closure throws an exception the executor will call std::terminate, as is the case with threads.]]

[[Synchronization:] [completion of closure on a particular thread happens before destruction of thread's thread local variables.]]

[[Return type:] [`void`.]]

[[Throws:] [sync_queue_is_closed if the thread pool is closed. Whatever exception that can be throw while storing the closure.]]

[[Exception safety:] [If an exception is thrown then the executor state is unmodified.]]

]

[endsect]
[/////////////////////////////////////]
[section:submitrc `e.submit(rc);`]

[variablelist

[[Effects:] [The specified closure will be scheduled for execution at some point in the future.
If invoked closure throws an exception the executor will call std::terminate, as is the case with threads.]]

[[Synchronization:] [completion of closure on a particular thread happens before destruction of thread's thread local variables.]]

[[Return type:] [`void`.]]

[[Throws:] [sync_queue_is_closed if the thread pool is closed. Whatever exception that can be throw while storing the closure.]]

[[Exception safety:] [If an exception is thrown then the executor state is unmodified.]]

]

[endsect]
[/////////////////////////////////////]
[section:close `e.close();`]

[variablelist

[[Effects:] [close the executor `e` for submissions.]]

[[Remark:] [The worker threads will work until there is no more closures to run.]]

[[Return type:] [`void`.]]

[[Throws:] [Whatever exception that can be thrown while ensuring the thread safety.]]

[[Exception safety:] [If an exception is thrown then the executor state is unmodified.]]

]

[endsect]
[/////////////////////////////////////]
[section:closed `b = e.closed();`]

[variablelist

[[Return type:] [`bool`.]]

[[Return:] [whether the executor is closed for submissions.]]

[[Throws:] [Whatever exception that can be throw while ensuring the thread safety.]]


]

[endsect]
[/////////////////////////////////////]
[section:try_executing_one `e.try_executing_one();`]

[variablelist

[[Effects:] [try to execute one work.]]

[[Remark:] [whether a work has been executed.]]

[[Return type:] [`bool`.]]

[[Return:] [Whether a work has been executed.]]

[[Throws:] [whatever the current work constructor throws or the `work()` throws.]]

]

[endsect]
[/////////////////////////////////////]
[section:reschedule_until `e.reschedule_until(p);`]

[variablelist

[[Requires:] [This must be called from a scheduled work]]

[[Effects:] [reschedule works until `p()`.]]

[[Return type:] [`bool`.]]

[[Return:] [Whether a work has been executed.]]

[[Throws:] [whatever the current work constructor throws or the `work()` throws.]]

]

[endsect]

[endsect]

[/////////////////////////]
[section:work Class `work`]

  #include <boost/thread/executors/work.hpp>
  namespace boost {
    typedef 'implementation_defined' work;
  }

[variablelist

[[Requires:] [work is a model of 'Closure']]

]

[endsect]

[/////////////////////////////////]
[section:executor Class `executor`]

Executor abstract base class.

  #include <boost/thread/executors/executor.hpp>
  namespace boost {
    class executor
    {
    public:
      typedef  boost::work work;
  
      executor(executor const&) = delete;
      executor& operator=(executor const&) = delete;

      executor(); 
      virtual ~executor() {};
  
      virtual void close() = 0;
      virtual bool closed() = 0;
  
      virtual void submit(work&& closure) = 0;
      virtual void submit(work& closure) = 0;
      template <typename Closure>
      void submit(Closure&& closure);
  
      virtual bool try_executing_one() = 0;
      template <typename Pred>
      bool reschedule_until(Pred const& pred);
    };
  }

[/////////////////////////////////////]
[section:constructor Constructor `executor()`]

      executor();

[variablelist

[[Effects:] [Constructs an executor. ]]

[[Throws:] [Nothing. ]]

]


[endsect]
[/////////////////////////////////////]
[section:constructor Destructor `~executor()`]

      virtual ~executor();

[variablelist

[[Effects:] [Destroys the executor.]]

[[Synchronization:] [The completion of all the closures happen before the completion of the executor destructor.]]

]


[endsect]

[endsect]

[//////////////////////////////////////////////////////////]
[section:executor_adaptor Template Class `executor_adaptor`]

Polymorphic adaptor of a model of Executor to an executor.

  #include <boost/thread/executors/executor.hpp>
  namespace boost {
    template <typename Executor>
    class executor_adaptor : public executor
    {
      Executor ex; // for exposition only
    public:
      typedef  executor::work work;
  
      executor_adaptor(executor_adaptor const&) = delete;
      executor_adaptor& operator=(executor_adaptor const&) = delete;
  
      template <typename ...Args>
      executor_adaptor(Args&& ... args);

      Executor& underlying_executor() noexcept;
  
      void close();
      bool closed();
  
      void submit(work&& closure);
      void submit(work& closure);
  
      bool try_executing_one();
  
    };
  }

[/////////////////////////////////////]
[section:constructor Constructor `executor_adaptor(Args&& ...)`]

      template <typename ...Args>
      executor_adaptor(Args&& ... args);

[variablelist

[[Effects:] [Constructs an executor_adaptor. ]]

[[Throws:] [Nothing. ]]

]


[endsect]
[/////////////////////////////////////]
[section:destructor Destructor `~executor_adaptor()`]

      virtual ~executor_adaptor();

[variablelist

[[Effects:] [Destroys the executor_adaptor.]]

[[Synchronization:] [The completion of all the closures happen before the completion of the executor destructor.]]

]

[endsect]
[/////////////////////////////////////]
[section:underlying_executor Function member `underlying_executor()`]

      Executor& underlying_executor() noexcept;

[variablelist

[[Return:] [The underlying executor instance. ]]

]


[endsect]

[endsect]

[/////////////////////////////////]
[section:generic_executor_ref Class `generic_executor_ref`]

Executor abstract base class.

  #include <boost/thread/executors/generic_executor_ref.hpp>
  namespace boost {
    class generic_executor_ref
    {
    public:
      generic_executor_ref(generic_executor_ref const&);
      generic_executor_ref& operator=(generic_executor_ref const&);

      template <class Executor>
      generic_executor_ref(Executor& ex); 
      generic_executor_ref() {};
  
      void close() = 0;
      bool closed() = 0;
  
      template <typename Closure>
      void submit(Closure&& closure);
  
      virtual bool try_executing_one() = 0;
      template <typename Pred>
      bool reschedule_until(Pred const& pred);
    };
  }

[endsect]

[//////////////////////////////////////////////////////////]
[section: scheduler Template Class `scheduler `]

Scheduler providing time related functions. Note that `scheduler` is not an Executor.

  #include <boost/thread/executors/scheduler.hpp>
  namespace boost {

    template <class Clock=steady_clock>
    class scheduler
    {
    public:
      using work = boost::function<void()> ;
      using clock = Clock;

      scheduler(scheduler const&) = delete;
      scheduler& operator=(scheduler const&) = delete;
  
      scheduler();
      ~scheduler();
 
      void close();
      bool closed();
  
      template <class Duration, typename Closure>  
      void submit_at(chrono::time_point<clock,Duration> abs_time, Closure&& closure);
      template <class Rep, class Period, typename Closure>  
      void submit_after(chrono::duration<Rep,Period> rel_time, Closure&& closure);

      template <class Duration>  
      at_executor<scheduler> submit_at(chrono::time_point<clock,Duration> abs_time);
      template <class Rep, class Period>  
      at_executor<scheduler> submit_after(chrono::duration<Rep,Period> rel_time);

      template <class Executor>
      scheduler_executor_wrapper<scheduler, Executor> on(Executor& ex);

    };
  }

[/////////////////////////////////////]
[section:constructor Constructor `scheduler()`]

      scheduler();

[variablelist

[[Effects:] [Constructs a `scheduler`. ]]

[[Throws:] [Nothing. ]]

]


[endsect]
[/////////////////////////////////////]
[section:destructor Destructor `~scheduler()`]

      ~scheduler();

[variablelist

[[Effects:] [Destroys the scheduler.]]

[[Synchronization:] [The completion of all the closures happen before the completion of the executor destructor.]]

]

[endsect]
[/////////////////////////////////////]
[section:submit_at Template Function Member `submit_at()`]

      template <class Clock, class Duration, typename Closure>  
      void submit_at(chrono::time_point<Clock,Duration> abs_time, Closure&& closure);

[variablelist

[[Effects:] [Schedule a `closure` to be executed at `abs_time`. ]]

[[Throws:] [Nothing.]]

]


[endsect]
[/////////////////////////////////////]
[section:submit_after Template Function Member `submit_after()`]

      template <class Rep, class Period, typename Closure>  
      void submit_after(chrono::duration<Rep,Period> rel_time, Closure&& closure);

[variablelist

[[Effects:] [Schedule a `closure` to be executed after `rel_time`. ]]

[[Throws:] [Nothing.]]

]


[endsect]

[endsect]

[//////////////////////////////////////////////////////////]
[section:at_executor Template Class `at_executor`]


  #include <boost/thread/executors/scheduler.hpp>
  namespace boost {

    template <class Scheduler>
    class at_executor
    {
    public:
      using work = Scheduler::work;
      using clock = Scheduler::clock;

      at_executor(at_executor const&) = default;
      at_executor(at_executor &&) = default;
      at_executor& operator=(at_executor const&) = default;
      at_executor& operator=(at_executor &&) = default;
  
      at_executor(Scheduler& sch, clock::time_point const& tp);
      ~at_executor();
 
      void close();
      bool closed();
  
      Scheduler& underlying_scheduler();

      template <class Closure>
      void submit(Closure&& closure);
      template <class Duration, typename Work>  
      void submit_at(chrono::time_point<clock,Duration> abs_time, Closure&& closure);
      template <class Rep, class Period, typename Work>  
      void submit_after(chrono::duration<Rep,Period> rel_time, Closure&& closure);

      template <class Executor>
      resubmit_at_executor<Scheduler, Executor> on(Executor& ex);

    };
  }

[/////////////////////////////////////]
[section:constructor Constructor `at_executor(Scheduler&, clock::time_point const&)`]

      at_executor(Scheduler& sch, clock::time_point const& tp);

[variablelist

[[Effects:] [Constructs a `at_executor`. ]]

[[Throws:] [Nothing. ]]

]


[endsect]
[/////////////////////////////////////]
[section:destructor Destructor `~at_executor()`]

      ~at_executor();

[variablelist

[[Effects:] [Destroys the `at_executor`.]]

[[Synchronization:] [The completion of all the closures happen before the completion of the executor destructor.]]

]

[endsect]
[/////////////////////////////////////]
[section:underlying_scheduler Function member `underlying_scheduler()`]

      Scheduler& underlying_scheduler() noexcept;

[variablelist

[[Return:] [The underlying scheduler instance. ]]

]

[endsect]
[/////////////////////////////////////]
[section:submit_at Template Function Member `submit()`]

      template <typename Closure>  
      void submit(Closure&& closure);

[variablelist

[[Effects:] [Schedule the `closure` to be executed at the `abs_time` given at construction time. ]]

[[Throws:] [Nothing.]]

]

[endsect]
[/////////////////////////////////////]
[section:submit_at Template Function Member `submit_at()`]

      template <class Clock, class Duration, typename Closure>  
      void submit_at(chrono::time_point<Clock,Duration> abs_time, Closure&& closure);

[variablelist

[[Effects:] [Schedule a `closure` to be executed at `abs_time`. ]]

[[Throws:] [Nothing.]]

]


[endsect]
[/////////////////////////////////////]
[section:submit_after Template Function Member `submit_after()`]

      template <class Rep, class Period, typename Closure>  
      void submit_after(chrono::duration<Rep,Period> rel_time, Closure&& closure);

[variablelist

[[Effects:] [Schedule a `closure` to be executed after `rel_time`. ]]

[[Throws:] [Nothing.]]

]


[endsect]

[endsect]


[//////////////////////////////////////////////////////////]
[section:scheduler_executor_wrapper Template Class `scheduler_executor_wrapper`]

  #include <boost/thread/executors/scheduler.hpp>
  namespace boost {

    template <class Scheduler, class Executor>
    class scheduler_executor_wrapper
    {
    public:
      using work = Scheduler::work;
      using clock = Scheduler::clock;

      scheduler_executor_wrapper(scheduler_executor_wrapper const&) = default;
      scheduler_executor_wrapper(scheduler_executor_wrapper &&) = default;
      scheduler_executor_wrapper& operator=(scheduler_executor_wrapper const&) = default;
      scheduler_executor_wrapper& operator=(scheduler_executor_wrapper &&) = default;
  
      scheduler_executor_wrapper(Scheduler& sch, Executor& ex);

      ~scheduler_executor_wrapper();
 
      void close();
      bool closed();

      Executor& underlying_executor();
      Scheduler& underlying_scheduler();
 
      template <class Closure>
      void submit(Closure&& closure);
      template <class Duration, typename Work>  
      void submit_at(chrono::time_point<clock,Duration> abs_time, Closure&& closure);
      template <class Rep, class Period, typename Work>  
      void submit_after(chrono::duration<Rep,Period> rel_time, Closure&& closure);

      template <class Duration>  
      resubmit_at_executor<Scheduler, Executor> at(chrono::time_point<clock,Duration> abs_time);
      template <class Rep, class Period>  
      resubmit_at_executor<Scheduler, Executor> after(chrono::duration<Rep,Period> rel_time);

    };
  }

[/////////////////////////////////////]
[section:constructor Constructor `scheduler_executor_wrapper(Scheduler&, Executor&)`]

      scheduler_executor_wrapper(Scheduler& sch, Executor& ex);

[variablelist

[[Effects:] [Constructs a `scheduler_executor_wrapper`. ]]

[[Throws:] [Nothing. ]]

]

[endsect]
[/////////////////////////////////////]
[section:destructor Destructor `~scheduler_executor_wrapper()`]

      ~scheduler_executor_wrapper();

[variablelist

[[Effects:] [Destroys the `scheduler_executor_wrapper`.]]

[[Synchronization:] [The completion of all the closures happen before the completion of the executor destructor.]]

]

[endsect]
[/////////////////////////////////////]
[section:underlying_scheduler Function member `underlying_scheduler()`]

      Scheduler& underlying_scheduler() noexcept;

[variablelist

[[Return:] [The underlying scheduler instance. ]]

]

[endsect]
[/////////////////////////////////////]
[section:underlying_executor Function member `underlying_executor()`]

      Executor& underlying_executor() noexcept;

[variablelist

[[Return:] [The underlying executor instance. ]]

]

[endsect]
[/////////////////////////////////////]
[section:submit_at Template Function Member `submit()`]

      template <typename Closure>  
      void submit(Closure&& closure);

[variablelist

[[Effects:] [Submit the `closure` on the underlying executor. ]]

[[Throws:] [Nothing.]]

]

[endsect]
[/////////////////////////////////////]
[section:submit_at Template Function Member `submit_at()`]

      template <class Clock, class Duration, typename Closure>  
      void submit_at(chrono::time_point<Clock,Duration> abs_time, Closure&& closure);

[variablelist

[[Effects:] [Resubmit the `closure` to be executed on the underlying executor at `abs_time`. ]]

[[Throws:] [Nothing.]]

]

[endsect]
[/////////////////////////////////////]
[section:submit_after Template Function Member `submit_after()`]

      template <class Rep, class Period, typename Closure>  
      void submit_after(chrono::duration<Rep,Period> rel_time, Closure&& closure);

[variablelist

[[Effects:] [Resubmit the `closure` to be executed on the underlying executor after `rel_time`. ]]

[[Throws:] [Nothing.]]

]

[endsect]

[endsect]


[//////////////////////////////////////////////////////////]
[section:resubmit_at_executor Template Class `resubmit_at_executor`]

`Executor` wrapping an `Scheduler`, an `Executor` and a `time_point` providing an `Executor` interface.

  #include <boost/thread/executors/scheduler.hpp>
  namespace boost {

    template <class Scheduler, class Executor>
    class resubmit_at_executor
    {
    public:
      using work = Scheduler::work;
      using clock = Scheduler::clock;
  
      resubmit_at_executor(resubmit_at_executor const&) = default;
      resubmit_at_executor(resubmit_at_executor &&) = default;
      resubmit_at_executor& operator=(resubmit_at_executor const&) = default;
      resubmit_at_executor& operator=(resubmit_at_executor &&) = default;
  
      template <class Duration>  
      resubmit_at_executor(Scheduler& sch, Executor& ex, clock::time_point<Duration> const& tp);
      ~resubmit_at_executor();
 
      void close();
      bool closed();
 
      Executor& underlying_executor();
      Scheduler& underlying_scheduler();
 
      template <class Closure>
      void submit(Closure&& closure);
      template <class Duration, typename Work>  
      void submit_at(chrono::time_point<clock,Duration> abs_time, Closure&& closure);
      template <class Rep, class Period, typename Work>  
      void submit_after(chrono::duration<Rep,Period> rel_time, Closure&& closure);

    };
  }


[/////////////////////////////////////]
[section:constructor Constructor `resubmit_at_executor(Scheduler&, Executor&, clock::time_point<Duration>)`]

      template <class Duration>  
      resubmit_at_executor(Scheduler& sch, Executor& ex, clock::time_point<Duration> const& tp);

[variablelist

[[Effects:] [Constructs a `resubmit_at_executor`. ]]

[[Throws:] [Nothing. ]]

]


[endsect]
[/////////////////////////////////////]
[section:destructor Destructor `~resubmit_at_executor()`]

      ~resubmit_at_executor();

[variablelist

[[Effects:] [Destroys the executor_adaptor.]]

[[Synchronization:] [The completion of all the closures happen before the completion of the executor destructor.]]

]

[endsect]
[/////////////////////////////////////]
[section:underlying_executor Function member `underlying_executor()`]

      Executor& underlying_executor() noexcept;

[variablelist

[[Return:] [The underlying executor instance. ]]

]

[endsect]
[/////////////////////////////////////]
[section:underlying_scheduler Function member `underlying_scheduler()`]

      Scheduler& underlying_scheduler() noexcept;

[variablelist

[[Return:] [The underlying scheduler instance. ]]

]

[endsect]
[/////////////////////////////////////]
[section:submit_at Template Function Member `submit()`]

      template <typename Closure>  
      void submit(Closure&& closure);

[variablelist

[[Effects:] [Resubmit the `closure` to be executed on the underlying executor at the `abs_time` given at construction time. ]]

[[Throws:] [Nothing.]]

]

[endsect]
[/////////////////////////////////////]
[section:submit_at Template Function Member `submit_at()`]

      template <class Clock, class Duration, typename Closure>  
      void submit_at(chrono::time_point<Clock,Duration> abs_time, Closure&& closure);

[variablelist

[[Effects:] [Resubmit the `closure` to be executed on the underlying executor at `abs_time`. ]]

[[Throws:] [Nothing.]]

]

[endsect]
[/////////////////////////////////////]
[section:submit_after Template Function Member `submit_after()`]

      template <class Rep, class Period, typename Closure>  
      void submit_after(chrono::duration<Rep,Period> rel_time, Closure&& closure);

[variablelist

[[Effects:] [Resubmit the `closure` to be executed on the underlying executor after `rel_time`. ]]

[[Throws:] [Nothing.]]

]

[endsect]

[endsect]


[//////////////////////////////////////////////////////////]
[/
[section:scheduled_executor_ref Template Class `scheduled_executor_ref`]

Executor providing time related functions.

  #include <boost/thread/executors/scheduled_executor_ref.hpp>
  namespace boost {
    template <class Executor>
    class scheduled_executor_ref
    {
	Executor& ex;
    public:
      typedef  executor::work work;
  
      scheduled_executor_ref(scheduled_executor_ref const&) = delete;
      scheduled_executor_ref& operator=(scheduled_executor_ref const&) = delete;
  
      template <class Rep, class Period>  
      scheduled_executor_ref(Executor& ex, chrono::duration<Rep, Period> granularity=chrono::milliseconds(100));
 
      Executor& underlying_executor() noexcept;

      void close();
      bool closed();
  
      void submit(work&& closure);
      void submit(work& closure);
      template <typename Closure>
      void submit(Closure&& closure);
  
      bool try_executing_one();
      template <typename Pred>
      bool reschedule_until(Pred const& pred);

      template <class Clock, class Duration, typename Closure>  
      void submit_at(chrono::time_point<Clock,Duration> abs_time, Closure&& closure);
      template <class Rep, class Period, typename Closure>  
      void submit_after(chrono::duration<Rep,Period> rel_time, Closure&& closure);
    };
  }

[/////////////////////////////////////]
[section:constructor Constructor `scheduled_executor_ref(Executor&, chrono::duration<Rep, Period>)`]

      template <class Rep, class Period>  
      scheduled_executor_ref(Executor& ex, chrono::duration<Rep, Period> granularity=chrono::milliseconds(100));

[variablelist

[[Effects:] [Constructs a scheduled_executor_ref. ]]

[[Throws:] [Nothing. ]]

]


[endsect]
[/////////////////////////////////////]
[section:destructor Destructor `~scheduled_executor_ref()`]

      ~scheduled_executor_ref();

[variablelist

[[Effects:] [Destroys the executor_adaptor.]]

[[Synchronization:] [The completion of all the closures happen before the completion of the executor destructor.]]

]

[endsect]
[/////////////////////////////////////]
[section:underlying_executor Function member `underlying_executor()`]

      Executor& underlying_executor() noexcept;

[variablelist

[[Return:] [The underlying executor instance. ]]

]

[endsect]
[/////////////////////////////////////]
[section:submit_at Template Function Member `submit()`]

      template <typename Closure>  
      void submit(Closure&& closure);

[variablelist

[[Effects:] [Resubmit the `closure` to be executed on the underlying executor. ]]

[[Throws:] [Nothing.]]

]

[endsect]
[/////////////////////////////////////]
[section:submit_at Template Function Member `submit_at()`]

      template <class Clock, class Duration, typename Closure>  
      void submit_at(chrono::time_point<Clock,Duration> abs_time, Closure&& closure);

[variablelist

[[Effects:] [Schedule a `closure` to be executed at `abs_time`. ]]

[[Throws:] [Nothing.]]

]


[endsect]
[/////////////////////////////////////]
[section:submit_after Template Function Member `submit_after()`]

      template <class Rep, class Period, typename Closure>  
      void submit_after(chrono::duration<Rep,Period> rel_time, Closure&& closure);

[variablelist

[[Effects:] [Schedule a `closure` to be executed after `rel_time`. ]]

[[Throws:] [Nothing.]]

]

[endsect]


[endsect]
]

[//////////////////////////////////////////////////////////]
[section:serial_executor Template Class `serial_executor`]

A serial executor ensuring that there are no two work units that executes concurrently.

  #include <boost/thread/executors/serial_executor.hpp>
  namespace boost {
    template <class Executor>
    class serial_executor
    {
    public:
      serial_executor(serial_executor const&) = delete;
      serial_executor& operator=(serial_executor const&) = delete;
  
      template <class Executor>
      serial_executor(Executor& ex);
 
      Executor& underlying_executor() noexcept;

      void close();
      bool closed();
  
      template <typename Closure>
      void submit(Closure&& closure);
  
      bool try_executing_one();
      template <typename Pred>
      bool reschedule_until(Pred const& pred);

    };
  }

[/////////////////////////////////////]
[section:constructor Constructor `serial_executor(Executor&)`]

      template <class Executor>
      serial_executor(Executor& ex);

[variablelist

[[Effects:] [Constructs a serial_executor. ]]

[[Throws:] [Nothing. ]]

]


[endsect]
[/////////////////////////////////////]
[section:destructor Destructor `~serial_executor()`]

      ~serial_executor();

[variablelist

[[Effects:] [Destroys the serial_executor.]]

[[Synchronization:] [The completion of all the closures happen before the completion of the executor destructor.]]

]

[endsect]
[/////////////////////////////////////]
[section:underlying_executor Function member `underlying_executor()`]

      generic_executor_ref& underlying_executor() noexcept;

[variablelist

[[Return:] [The underlying executor instance. ]]

[[Throws:] [Nothing.]]

]


[endsect]

[endsect]


[//////////////////////////////////////////////////////////]
[section:inline_executor Class `inline_executor`]

A serial executor ensuring that there are no two work units that executes concurrently.

  #include <boost/thread/executors/inline_executor.hpp>
  namespace boost {
    class inline_executor
    {
    public:
      inline_executor(inline_executor const&) = delete;
      inline_executor& operator=(inline_executor const&) = delete;
  
      inline_executor();
 
      void close();
      bool closed();
  
      template <typename Closure>
      void submit(Closure&& closure);
  
      bool try_executing_one();
      template <typename Pred>
      bool reschedule_until(Pred const& pred);

    };
  }

[/////////////////////////////////////]
[section:constructor Constructor `inline_executor()`]

      inline_executor();

[variablelist

[[Effects:] [Constructs an inline_executor. ]]

[[Throws:] [Nothing. ]]

]


[endsect]
[/////////////////////////////////////]
[section:destructor Destructor `~inline_executor()`]

      ~inline_executor();

[variablelist

[[Effects:] [Destroys the inline_executor.]]

[[Synchronization:] [The completion of all the closures happen before the completion of the executor destructor.]]

]

[endsect]


[endsect]




[///////////////////////////////////////]
[section:basic_thread_pool Class `basic_thread_pool`]

A thread pool with up to a fixed number of threads.

  #include <boost/thread/executors/basic_thread_pool.hpp>
  namespace boost {
    class basic_thread_pool
    { 
    public:
 
      basic_thread_pool(basic_thread_pool const&) = delete;
      basic_thread_pool& operator=(basic_thread_pool const&) = delete;
  
      basic_thread_pool(unsigned const thread_count = thread::hardware_concurrency());
      template <class AtThreadEntry>
      basic_thread_pool( unsigned const thread_count, AtThreadEntry at_thread_entry);
      ~basic_thread_pool();
  
      void close();
      bool closed();
  
      template <typename Closure>
      void submit(Closure&& closure);
  
      bool try_executing_one();

      template <typename Pred>
      bool reschedule_until(Pred const& pred);
  
    };
  }

[/////////////////////////////////////]
[section:constructor Constructor `basic_thread_pool(unsigned const)`]

[variablelist

[[Effects:] [creates a thread pool that runs closures on `thread_count` threads. ]]

[[Throws:] [Whatever exception is thrown while initializing the needed resources. ]]

]


[endsect]
[/////////////////////////////////////]
[section:destructor Destructor `~basic_thread_pool()`]

     ~basic_thread_pool();

[variablelist

[[Effects:] [Interrupts and joins all the threads and then destroys the threads.]]

[[Synchronization:] [The completion of all the closures happen before the completion of the executor destructor.]]

]
[endsect]

[endsect]

[///////////////////////////////////////]
[section:thread_executor Class `thread_executor`]

A thread_executor with a threads for each task.

  #include <boost/thread/executors/thread_executor.hpp>
  namespace boost {
    class thread_executor
    { 
    public:
 
      thread_executor(thread_executor const&) = delete;
      thread_executor& operator=(thread_executor const&) = delete;
  
      thread_executor();
      template <class AtThreadEntry>
      basic_thread_pool( unsigned const thread_count, AtThreadEntry at_thread_entry);
      ~thread_executor();
  
      void close();
      bool closed();
  
      template <typename Closure>
      void submit(Closure&& closure);
   
    };
  }

[/////////////////////////////////////]
[section:constructor Constructor `thread_executor()`]

[variablelist

[[Effects:] [creates a thread_executor. ]]

[[Throws:] [Whatever exception is thrown while initializing the needed resources. ]]

]


[endsect]
[/////////////////////////////////////]
[section:destructor Destructor `~thread_executor()`]

     ~thread_executor();

[variablelist

[[Effects:] [Waits for closures (if any) to complete, then joins and destroys the threads.]]

[[Synchronization:] [The completion of all the closures happen before the completion of the executor destructor.]]

]
[endsect]

[endsect]


[/////////////////////////////////]
[section:loop_executor Class `loop_executor`]

A user scheduled executor.

  #include <boost/thread/executors/loop_executor.hpp>
  namespace boost {
    class loop_executor
    { 
    public:
 
      loop_executor(loop_executor const&) = delete;
      loop_executor& operator=(loop_executor const&) = delete;
  
      loop_executor();
      ~loop_executor();
  
      void close();
      bool closed();
  
      template <typename Closure>
      void submit(Closure&& closure);

      bool try_executing_one();
      template <typename Pred>
      bool reschedule_until(Pred const& pred);

      void loop();
      void run_queued_closures();
    };
  }

[/////////////////////////////////////]
[section:constructor Constructor `loop_executor()`]

      loop_executor();

[variablelist

[[Effects:] [creates an executor that runs closures using one of its closure-executing methods. ]]

[[Throws:] [Whatever exception is thrown while initializing the needed resources. ]]

]


[endsect]
[/////////////////////////////////////]
[section:destructor Destructor `~loop_executor()`]

      virtual ~loop_executor();

[variablelist

[[Effects:] [Destroys the executor.]]

[[Synchronization:] [The completion of all the closures happen before the completion of the executor destructor.]]

]
[endsect]
[/////////////////////////////////////]
[section:loop Function member `loop()`]

      void loop();

[variablelist

[[Return:] [reschedule works until `closed()` or empty. ]]

[[Throws:] [whatever the current work constructor throws or the `work()` throws.]]

]


[endsect]

[/////////////////////////////////////]
[section:run_queued_closures Function member `run_queued_closures()`]

      void run_queued_closures();

[variablelist

[[Return:] [reschedule the enqueued works. ]]

[[Throws:] [whatever the current work constructor throws or the `work()` throws.]]

]


[endsect]



[endsect]

[endsect]

[endsect]