| Home | Libraries | People | FAQ | More

#### post (2 of 7 overloads)

Submits a completion token or function object for execution.

    template<
        typename Executor,
        typename NullaryToken = default_completion_token_t<Executor>>
    auto post(
        const Executor & ex,
        NullaryToken && token = default_completion_token_t< Executor >(),
        constraint_t<(execution::is_executor< Executor >::value &&can_require< Executor, execution::blocking_t::never_t >::value)||is_executor< Executor >::value >  = 0);

This function submits an object for execution using the specified executor. The function object is queued for execution, and is never called from the current thread prior to returning from `post()`.

The use of `post()`, rather than `defer`, indicates the caller's preference that the function object be eagerly queued for execution.

###### Parameters

ex

  The target executor.

token

  The completion token that will be used to produce a completion handler. The function signature of the completion handler must be:

      void handler();

###### Return Value

This function returns `async_initiate<NullaryToken, void()>(Init{ex}, token)`, where `Init` is a function object type defined as:

    class Init
    {
    public:
      using executor_type = Executor;
      explicit Init(const Executor& ex) : ex_(ex) {}
      executor_type get_executor() const noexcept { return ex_; }
      template <typename CompletionHandler>
        void operator()(CompletionHandler&& completion_handler) const;
    private:
      Executor ex_; // exposition only
    };

The function call operator of `Init:`

- Obtains the handler's associated executor object `ex1` of type `Ex1` by performing

  auto ex1 = get_associated_executor(completion_handler, ex);

- Obtains the handler's associated allocator object `alloc` by performing

  auto alloc = get_associated_allocator(completion_handler);

- If `execution::is_executor<Ex1>::value` is true, constructs a function object `f` with a member `executor_` that is initialised with `prefer(ex1, execution::outstanding_work.tracked)`, a member `handler_` that is a decay-copy of `completion_handler`, and a function call operator that performs:

  auto a = get_associated_allocator(handler_); prefer(executor_, execution::allocator(a)).execute(std::move(handler_));

- If `execution::is_executor<Ex1>::value` is false, constructs a function object `f` with a member `work_` that is initialised with `make_work_guard(ex1)`, a member `handler_` that is a decay-copy of `completion_handler`, and a function call operator that performs:

  auto a = get_associated_allocator(handler_); work_.get_executor().dispatch(std::move(handler_), a); work_.reset();

- If `execution::is_executor<Executor>::value` is true, performs

  prefer( require(ex, execution::blocking.never), execution::relationship.fork, execution::allocator(alloc) ).execute(std::move(f));

- If `execution::is_executor<Executor>::value` is false, performs

  ex.post(std::move(f), alloc);

###### Completion Signature

    void()