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

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

The type of the progress values the Task (may) post

Examples0

Public static methods5

staticgeode::Taskcancelled(

std::string_viewname

)

Create a new Task that is immediately cancelled

Parameters

name

The name of the Task; used for debugging

staticgeode::Taskimmediate(

Tvalue

std::string_viewname

)

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_viewname

)

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_viewname

)

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_viewname

)

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 functions26

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_viewname

)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_viewname

)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

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_viewname

)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

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.

template<invocable<T*> Mapper>decltype(mapper(std::declval<T *>()))chain(

Mappermapper

std::string_viewname

)const

Create a new Task that listens to this Task and maps the values using the provided function. The new Task will only start when this Task finishes.

Parameters

mapper

Function that makes a new task given the finished value of this task. The function signature should be `Task<NewType, NewProgress>(T*)`, and it will be executed on the main thread.

name

The name of the Task; used for debugging.

Return value

The new Task that will run when this Task finishes.