Reference for the Mosaic class Core::Task

Core::Task
Cancel()
Complete()
Continue()
GetQueue()
IsCurrent()
IsScheduled()
OnCancel()
OnComplete()
OnContinue()
OnStart()

The class Core::Task provides the basic functionality for implementing tasks which then can be scheduled for later execution. The execution of tasks is controlled by instances of the class Core::TaskQueue.

Usually you will use this class to derive your own task class. In your task class you can implement what to do when the task is started, canceled or completed. For this purpose you can override the methods OnStart(), OnCancel(), OnComplete() and OnContinue().

It is essential to understand, that the entire 'task' functionality has nothing to do with multi-threading or multi-tasking features known from operating systems. Applications developed with Chora are limited to a single-thread environment. There is no real background thread activity. Accordingly your implementation of a task should behave cooperatively. A well designed task should perform its job quickly, use timers or effects to delay execution and when the job is done reports its completion by calling the method Complete().

method void Cancel();

The method Cancel() removes this task from the task queue where the task has been previously scheduled. In the case the task is already in progress, the queue will advise the task to abort its work immediately before the task is removed from the queue (see OnCancel()).

Whether a task is waiting for execution can be determined by IsScheduled(). Whether a task is in progress can be determined by IsCurrent().

Canceling a running task will cause the task queue to start the next available task.

method void Complete();

The method Complete() informs the task queue about the completion of this task. Thereupon the next available task in the queue can be executed. This method is usually called in context of the OnStart() or OnContinue() method when the task has finalized its work. Calling the method for a not current task has no effect.

method void Continue();

The method Continue() schedules the task to execute its OnContinue() method after a short delay (usually after the next screen update). This is useful for tasks consisting of several execution steps. With every call of OnContinue() the task can perform the next step of its work. This results in a kind of simple cooperative multi-tasking functionality able to perform activities in the 'background'.

This method is usually called in context of the OnStart() or OnContinue() method when the task is currently executed. Calling the method for a not current task has no effect.

method Core::TaskQueue GetQueue();

The method GetQueue() returns the queue this task belongs to or 'null' if the task is not waiting for nor performing any execution.

method bool IsCurrent();

The method IsCurrent() returns 'true' if the affected task is currently performed. The method returns 'false' if the task is done, waiting for execution or it simply doesn't belong to any task queue.

method bool IsScheduled();

The method IsScheduled() returns 'true' if the affected task is waiting for execution or the task is currently performed. The method returns 'false' if the task is done or it doesn't belong to any task queue.

method void OnCancel
(
arg Core::TaskQueue aQueue
);

The method OnCancel() is called when the task is canceled after being started. The default implementation of this method does nothing. You can override this method in derived task classes and implement what to do when the task is prematurely aborted. For example, you can stop running timers and effects started in the preceding OnStart() method.

To cancel a task you should call explicitly the method Cancel(). The parameter aQueue refers to the queue this task belonged to. It can be used e.g. to schedule again a task to the same queue, etc.

method void OnComplete
(
arg Core::TaskQueue aQueue
);

The method OnComplete() is called when the task is done with its work. The default implementation of this method does nothing. You can override this method in derived task classes and implement what to do when the task is finished. For example, you can release resources used temporarily during animations.

To complete a task you should call explicitly the method Complete(). The parameter aQueue refers to the queue this task belonged to. It can be used e.g. to schedule again a task to the same queue, etc.

method void OnContinue
(
arg Core::TaskQueue aQueue
);

The method OnContinue() is called when the current task has it explicitly requested by using the method Continue(). The default implementation of this method does nothing. You can override this method in derived task classes and implement there the algorithm of the task.

OnContinue() is intended to implement long time tasks consisting of small execution steps. With every invocation of OnContinue() the task can perform its next step. To get invoked again, OnContinue() as well as OnStart() should call explicitly the method Continue().

At the end of the task, don't forget to call Complete(). The parameter aQueue refers to the queue this task belongs to. It can be used to schedule more task to execute later.

method void OnStart
(
arg Core::TaskQueue aQueue
);

The method OnStart() is called at the begin of the execution of this task. The default implementation of the method simply cancels the task causing the next available task in the task queue to be started. You should override this method in derived task classes to implement what the task should do.

There are three typical application cases how to implement the OnStart() method:

The parameter aQueue refers to the queue this task belongs to. It can be used to schedule more task to execute later.