Class Task<T, P>

#include <Geode/utils/Task.hpp>
template<move_constructible T,move_constructible P = std::monostate>classTask{ ... }

Tasks represent an asynchronous operation that will be finished at some unknown point in the future. Tasks can report their progress, and will end either through finishing into a value, or due to being cancelled. Tasks are designed to provide a thread-safe general purpose abstraction for dealing with any asynchronous operations. The Task class satisfies EventFilter and as such is listened to using the Geode events system; tasks may have multiple listeners, and even if a listener is attached after the Task has finished it will receive the finished value. Tasks are a very cheap and tiny struct that just have a reference to a task Handle; as such, Tasks may (and should) be copied around without worry. It should be noted that a Task never owns itself - the listener(s) of a Task are expected to hold an instance of the Task for as long as they intend to listen to it. Usually this is done via just setting the Task as the filter to an EventListener, as the EventListener manages the lifetime of its filter Task itself does not carry a notion of fallibility aside from cancellation; it is customary to use the Result type in Tasks that might finish to a failure value. Once a Task has finished or has been cancelled, it can no longer be revived

Template parameters

T

The type the Task will eventually finish to. This type must be move-constructible; though as there is no way to move the value out of the Task (because of potentially multiple listeners), one should ensure they can reasonably copy the value out in some form if they wish to gain ownership of it after the Task is finished

P

The type of the progress values the Task (may) post
Examples0
Public static methods5
staticgeode::Taskcancelled(
std::string_viewconstname
)

Create a new Task that is immediately cancelled

Parameters

name

The name of the Task; used for debugging
staticgeode::Taskimmediate(
Tvalue
,
std::string_viewconstname
)

Create a new Task that immediately finishes with the given value

Parameters

value

The value the Task shall be finished with

name

The name of the Task; used for debugging
staticgeode::Taskrun(
geode::Task::Run&&body
,
std::string_viewconstname
)

Create a new Task with a function that returns the finished value. See the class description for details about Tasks

Parameters

body

The body aka actual code of the Task. Note that this function MUST be synchronous - Task creates the thread for you!

name

The name of the Task; used for debugging
staticgeode::TaskrunWithCallback(
geode::Task::RunWithCallback&&body
,
std::string_viewconstname
)

Create a Task using a body that may need to create additional threads within itself; for example due to using an external library that creates its own thread

Parameters

body

The body aka actual code of the Task. The body may call its provided finish callback *exactly once* - subsequent calls will always be ignored

name

The name of the Task; used for debugging
template<move_constructible NP>staticgeode::Task<std::vector<T*>,std::monostate>all(
std::vector<geode::Task<T,NP>>&&tasks
,
std::string_viewconstname
)

Create a Task that waits for a list of other Tasks to finish, and then finishes with a list of their finish values

Parameters

tasks

The tasks to wait for

name

The name of the Task; used for debugging

⚠️ The result vector may contain nulls if any of the tasks were cancelled!

Public member functions25
geode::Task&operator=(
geode::Taskconst&other
)
No description provided
geode::Task&operator=(
geode::Task&&other
)
No description provided
booloperator==(
geode::Taskconst&other
)const
No description provided
booloperator!=(
geode::Taskconst&other
)const
No description provided
booloperator<(
geode::Taskconst&other
)const
No description provided
booloperator<=(
geode::Taskconst&other
)const
No description provided
booloperator>(
geode::Taskconst&other
)const
No description provided
booloperator>=(
geode::Taskconst&other
)const
No description provided
T*getFinishedValue()

Get the value this Task finished to, if the Task had finished, or null otherwise. Note that this is simply a mutable reference to the value - you may not move out of it!

voidcancel()

Cancel this Task. If this is a Task that owns other Task(s) (for example one created through Task::map) then that Task is cancelled as well. If this is undesirable, use shallowCancel() instead

voidshallowCancel()

If this is a Task that owns other Task(s) (for example created through Task::map or Task::all), then this method cancels only this Task and not any of the Task(s) it is built on top of. Ownership of the other Task(s) will be released, so if this is the only Task listening to them, they will still be destroyed due to a lack of listeners

boolisPending()const
No description provided
boolisFinished()const
No description provided
boolisCancelled()const
No description provided
boolisNull()const

Check if this Task doesn’t actually do anything (for instance it was default-constructed)

template<class ResultMapper,class ProgressMapper,class OnCancelled>automap(
ResultMapper&&resultMapper
,
ProgressMapper&&progressMapper
,
OnCancelled&&onCancelled
,
std::string_viewconstname
)const

Create a new Task that listens to this Task and maps the values using the provided functions. The new Task takes (shared) ownership of this Task, so the new Task may very well be its only listener

Parameters

resultMapper

Function that converts the finished values of the mapped Task to a desired type. Note that the function is only given a pointer to the finish value, as `T` is not guaranteed to be copyable - the mapper may NOT move out of the value!

progressMapper

Function that converts the progress values of the mapped Task to a desired type

onCancelled

Function that is called if the mapped Task is cancelled

name

The name of the Task; used for debugging. The name of the mapped task is appended to the end
template<class ResultMapper,class ProgressMapper>automap(
ResultMapper&&resultMapper
,
ProgressMapper&&progressMapper
,
std::string_viewconstname
)const

Create a new Task that listens to this Task and maps the values using the provided functions. The new Task takes (shared) ownership of this Task, so the new Task may very well be its only listener

Parameters

resultMapper

Function that converts the finished values of the mapped Task to a desired type. Note that the function is only given a pointer to the finish value, as `T` is not guaranteed to be copyable - the mapper may NOT move out of the value!

progressMapper

Function that converts the progress values of the mapped Task to a desired type

name

The name of the Task; used for debugging. The name of the mapped task is appended to the end
template<class ResultMapper>automap(
ResultMapper&&resultMapper
,
std::string_viewconstname
)const

Create a new Task that listens to this Task and maps the finish value using the provided function. Progress is mapped by copy-constructing the value as-is. The new Task takes (shared) ownership of this Task, so the new Task may very well be its only listener

Parameters

resultMapper

Function that converts the finished values of the mapped Task to a desired type. Note that the function is only given a pointer to the finish value, as `T` is not guaranteed to be copyable - the mapper may NOT move out of the value!

name

The name of the Task; used for debugging. The name of the mapped task is appended to the end
template<class OnResult,class OnProgress,class OnCancelled>voidlisten(
OnResult&&onResult
,
OnProgress&&onProgress
,
OnCancelled&&onCancelled
)const

Creates an implicit event listener for this Task that will call the provided functions when the Task finishes, progresses, or is cancelled. The listener will automatically be destroyed after the Task has finished.

Parameters

onResult

Function to call when the Task finishes. The function is given a pointer to the finished value, `T*`.

onProgress

Function to call when the Task progresses. The function is given a pointer to the progress value, `P*`.

onCancelled

Function to call when the Task is cancelled

⚠️ This method should only be used in a global context. If you rely on some node still existing when the task completes, use an event listener instead.

template<class OnResult,class OnProgress>voidlisten(
OnResult&&onResult
,
OnProgress&&onProgress
)const

Creates an implicit event listener for this Task that will call the provided functions when the Task finishes or progresses. The listener will automatically be destroyed after the Task has finished.

Parameters

onResult

Function to call when the Task finishes. The function is given a pointer to the finished value, `T*`.

onProgress

Function to call when the Task progresses. The function is given a pointer to the progress value, `P*`.

⚠️ This method should only be used in a global context. If you rely on some node still existing when the task completes, use an event listener instead.

template<class OnResult>voidlisten(
OnResult&&onResult
)const

Creates an implicit event listener for this Task that will call the provided function when the Task finishes. The listener will automatically be destroyed after the Task has finished.

Parameters

onResult

Function to call when the Task finishes. The function is given a pointer to the finished value, `T*`.

⚠️ This method should only be used in a global context. If you rely on some node still existing when the task completes, use an event listener instead.

geode::ListenerResulthandle(
geode::utils::MiniFunction<geode::Task::Callback>fn
,
geode::Task::Event*e
)
No description provided
geode::EventListenerPool*getPool()const
No description provided
voidsetListener(
geode::EventListenerProtocol*listener
)
No description provided
geode::EventListenerProtocol*getListener()const
No description provided
Fields0
Protected member functions0
Protected fields0