.. index:: pair: class; EE::Task
.. _doxid-class_e_e_1_1_task:

template class EE::Task
=======================

.. toctree::
	:hidden:

Overview
~~~~~~~~

The result of an operation that completes later. :ref:`More...<details-class_e_e_1_1_task>`


.. ref-code-block:: cpp
	:class: doxyrest-overview-code-block

	#include <task.hpp>
	
	template <typename T>
	class Task {
	public:
		// typedefs
	
		typedef T :target:`ValueType<doxid-class_e_e_1_1_task_1a845384a93585cd2199b93b5def015a77>`;

		// construction
	
		:ref:`Task<doxid-class_e_e_1_1_task_1a4e4d2d17e8e6b12f3f85e6073230e99d>`();
		:target:`Task<doxid-class_e_e_1_1_task_1a92e3728353ab4b15e09e0473f37b19d0>`(Task&&);
		:target:`Task<doxid-class_e_e_1_1_task_1a65f5eb8e4d38aa530ce888c895e6139d>`(const Task&);

		// methods
	
		Task& :target:`operator=<doxid-class_e_e_1_1_task_1a6b551dfe100169e6f029ada44737f7cf>`(Task&&);
		Task& :target:`operator=<doxid-class_e_e_1_1_task_1af72f61704ad81e4bc145d4be3ed06ece>`(const Task&);
		bool :target:`valid<doxid-class_e_e_1_1_task_1a3c5be4fb27be147df5e1443ba9f55660>`() const;
		:ref:`TaskState<doxid-namespace_e_e_1ac2db4385f16b83a7a553865c98c38128>` :target:`state<doxid-class_e_e_1_1_task_1a638e972188330918cb5e42e0d208adac>`() const;
		bool :target:`isReady<doxid-class_e_e_1_1_task_1a0c5203fb02b5604911cfbac5cec2839a>`() const;
		bool :target:`isPending<doxid-class_e_e_1_1_task_1adcc0e24c64789c36cf71302ac14ea07f>`() const;
		:ref:`TaskState<doxid-namespace_e_e_1ac2db4385f16b83a7a553865c98c38128>` :ref:`wait<doxid-class_e_e_1_1_task_1acf8b201f4268b6e83e5db3cbf6bca89d>`() const;
	
		template <typename Rep, typename Period>
		:ref:`TaskState<doxid-namespace_e_e_1ac2db4385f16b83a7a553865c98c38128>` :ref:`waitFor<doxid-class_e_e_1_1_task_1a5d46eace4576d3ac725492155b3b4e7b>`(const std::chrono::duration<Rep, Period>& timeout) const;
	
		T :ref:`takeValue<doxid-class_e_e_1_1_task_1aba131eb7b0057279a5848a7b337b6230>`();
		auto :ref:`get<doxid-class_e_e_1_1_task_1a0ed4b345da7902b60215b36f22ae01a0>`();
	
		template <typename F>
		auto :ref:`then<doxid-class_e_e_1_1_task_1afd1872c589904c3ec68dba689a6eb4a6>`(:ref:`Executor<doxid-class_e_e_1_1_executor>`& executor, F&& fn);
	
		template <typename F>
		auto :ref:`then<doxid-class_e_e_1_1_task_1ae3fdfd59ad07733c367f4f5dd342d609>`(F&& fn);
	
		template <typename F>
		void :ref:`onComplete<doxid-class_e_e_1_1_task_1a5c1be4dd1c0a788ff6b5b0482cf24afa>`(F&& fn);
	
		static Task :ref:`create<doxid-class_e_e_1_1_task_1aca423d9dddbdf5a8ac467eba9a244939>`(:ref:`TaskResolver<doxid-class_e_e_1_1_task_resolver>`<T>& resolve);
	
		template <typename... Args>
		static Task :ref:`ready<doxid-class_e_e_1_1_task_1a840027a76560f1fe55a62085714d79a9>`(Args&&... args);
	};
.. _details-class_e_e_1_1_task:

Detailed Documentation
~~~~~~~~~~~~~~~~~~~~~~

The result of an operation that completes later.

The consumer's end. The producer completes it through the :ref:`TaskResolver <doxid-class_e_e_1_1_task_resolver>` that :ref:`create() <doxid-class_e_e_1_1_task_1aca423d9dddbdf5a8ac467eba9a244939>` fills in. :ref:`Task <doxid-class_e_e_1_1_task>` is move-only and carries no domain error semantics: fallible operations return :ref:`Task <doxid-class_e_e_1_1_task>` <Result<T, E>>. Attaching a continuation consumes the task (``std::move( task ).then( ... )``), so only one continuation chain can ever exist.

* then( executor, fn ): runs fn through the executor (for example the :ref:`UI <doxid-namespace_e_e_1_1_u_i>` thread's), even if the task has already completed. This is the normal way to use a result.

* then( fn ): runs fn on whichever thread completes the task, or right away on the calling thread if it already has. For cheap transformations that touch no thread-bound state.

* fn may return a value, void, or a :ref:`Task <doxid-class_e_e_1_1_task>`; nested tasks are flattened into :ref:`Task <doxid-class_e_e_1_1_task>`.

* If the task is abandoned, fn is not called and the returned task is abandoned too.

* onComplete( fn ) also observes abandonment: fn receives std::nullopt.

Construction
------------

.. index:: pair: function; Task
.. _doxid-class_e_e_1_1_task_1a4e4d2d17e8e6b12f3f85e6073230e99d:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	Task()

Creates an invalid task. Its :ref:`state() <doxid-class_e_e_1_1_task_1a638e972188330918cb5e42e0d208adac>` is Abandoned.

Methods
-------

.. index:: pair: function; wait
.. _doxid-class_e_e_1_1_task_1acf8b201f4268b6e83e5db3cbf6bca89d:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`TaskState<doxid-namespace_e_e_1ac2db4385f16b83a7a553865c98c38128>` wait() const

Blocks until the task is Ready or Abandoned.

This is a low-level bridge for worker-thread adapters and tests. It must never be called on the :ref:`UI <doxid-namespace_e_e_1_1_u_i>` thread, nor on the thread that is expected to resolve the task.

.. index:: pair: function; waitFor
.. _doxid-class_e_e_1_1_task_1a5d46eace4576d3ac725492155b3b4e7b:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	template <typename Rep, typename Period>
	:ref:`TaskState<doxid-namespace_e_e_1ac2db4385f16b83a7a553865c98c38128>` waitFor(const std::chrono::duration<Rep, Period>& timeout) const

Blocks until the task completes or the timeout expires.



.. rubric:: Returns:

The state on return.

.. index:: pair: function; takeValue
.. _doxid-class_e_e_1_1_task_1aba131eb7b0057279a5848a7b337b6230:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	T takeValue()

Extracts the value of a Ready task and consumes it. Precondition: :ref:`isReady() <doxid-class_e_e_1_1_task_1a0c5203fb02b5604911cfbac5cec2839a>`.

.. index:: pair: function; get
.. _doxid-class_e_e_1_1_task_1a0ed4b345da7902b60215b36f22ae01a0:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	auto get()

Blocks until completion and returns the value, or std::nullopt if abandoned. Same threading restrictions as :ref:`wait() <doxid-class_e_e_1_1_task_1acf8b201f4268b6e83e5db3cbf6bca89d>`.

.. index:: pair: function; then
.. _doxid-class_e_e_1_1_task_1afd1872c589904c3ec68dba689a6eb4a6:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	template <typename F>
	auto then(:ref:`Executor<doxid-class_e_e_1_1_executor>`& executor, F&& fn)

Runs fn( value ) through executor once the task completes, even if it already has. The executor must outlive the task chain. See the class documentation.

.. index:: pair: function; then
.. _doxid-class_e_e_1_1_task_1ae3fdfd59ad07733c367f4f5dd342d609:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	template <typename F>
	auto then(F&& fn)

Runs fn( value ) on the thread that completes the task, or right away on the calling thread if it already has. See the class documentation.

.. index:: pair: function; onComplete
.. _doxid-class_e_e_1_1_task_1a5c1be4dd1c0a788ff6b5b0482cf24afa:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	template <typename F>
	void onComplete(F&& fn)

Observes the outcome without producing a new task, on the thread that completes the task (or right away on the calling thread if it already has). fn( std::optional<T> value ) receives the value, or std::nullopt if the task was abandoned; for Task<void>, fn( bool completed ) receives false if it was abandoned.

.. index:: pair: function; create
.. _doxid-class_e_e_1_1_task_1aca423d9dddbdf5a8ac467eba9a244939:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	static Task create(:ref:`TaskResolver<doxid-class_e_e_1_1_task_resolver>`<T>& resolve)

.. ref-code-block:: cpp

	TaskResolver<int> resolve;
	auto task = Task<int>::create( resolve );
	pool.execute( [resolve] { resolve( 42 ); } );
	return task;



.. rubric:: Returns:

A pending task. resolve is set to the resolver that completes it (a resolver it held before is released).

.. index:: pair: function; ready
.. _doxid-class_e_e_1_1_task_1a840027a76560f1fe55a62085714d79a9:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	template <typename... Args>
	static Task ready(Args&&... args)



.. rubric:: Returns:

A task that is already Ready with the given value.