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
Class Task<T, P>
#include <Geode/utils/Task.hpp>
T
P
Examples0
Public static methods3
staticgeode::Taskimmediate(Tvalue,)
Create a new Task that immediately finishes with the given value
value
name
staticgeode::Taskrun(,)
Create a new Task with a function that returns the finished value. See the class description for details about Tasks
body
name
staticgeode::TaskrunWithCallback(,)
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
body
name
Public member functions19
geode::Task&operator=(geode::Taskconst&other)
geode::Task&operator=(geode::Task&&other)
booloperator==(geode::Taskconst&other)const
booloperator!=(geode::Taskconst&other)const
booloperator<(geode::Taskconst&other)const
booloperator<=(geode::Taskconst&other)const
booloperator>(geode::Taskconst&other)const
booloperator>=(geode::Taskconst&other)const
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
boolisFinished()const
boolisCancelled()const
boolisNull()const
Check if this Task doesn’t actually do anything (for instance it was default-constructed)