NanoByte.Common  2.10.5
Task system

The NanoByte.Common.Tasks namespace provides a framework for managing long-running tasks and reporting progress to the user.

Tasks

Tasks are represented using the ITask interface.

This library provides general-purpose implementations such as NanoByte.Common.Tasks.SimpleTask and NanoByte.Common.Tasks.ForEachTask, as well as use-case specific ones such as NanoByte.Common.Net.DownloadFile and NanoByte.Common.Storage.ReadFile. You can also implement your own.

Handlers

The ITaskHandler interface represents a user interface for reporting task progress as well as displaying prompts and outputs to the user. This library provides a number of implementations:

Methods that wish to run ITasks should take an ITaskHandler as an input parameter.
To run an ITask pass it to the ITaskHandler.RunTask() method. This will then internally call ITask.Run() and take care of setting up progress tracking, cancellation, etc.. Additional methods such as ITaskHandler.Ask() can be used for user interaction.

Threading

ITasks provide no threading or asynchronicity concept by themselves. Their .Run() methods block until the tasks is complete. However, they can be cancelled from other threads via CancellationTokens.

ITaskHandler implementations are thread-safe and support running multiple ITasks concurrently.
ITaskHandler.RunTask() blocks until the tasks is complete, however some implementations may perform the actual task execution on a separate thread.
DialogTaskHandler.RunTask() keeps the WinForms message loop pumping while a task is running, so calling this from the GUI thread will not freeze the GUI. However it does prevent user actions (other than canceling the task) via a modal dialog box.

Comparison with async/await

While ITask has some superficial similarities with the Task class used by the C# async/await keywords, these two concepts should not be confused.

The async/await keywords are part of the Task Asynchronous Programming model (TAP). The TAP provides an abstraction over asynchronous code, enabling the execution of continuations after tasks have completed. This is intended to increase the performance and responsiveness of applications. Many TAP methods accept CancellationTokens to signal that a task should be cancelled and IProgress<> to report a task's progress.

NanoByte.Common's Task system is intended for managing long-running tasks. It provides an abstraction over UIs for interacting with such tasks. It uses the same CancellationToken and IProgress<> as the TAP, but takes care of managing them internally for most use cases.

As a rule of thumb:

  • Use await and Task if you want to trigger a short task from a GUI thread.
  • Use ITaskHandler.RunTask() and ITask if you want to run a longer task on a non-GUI thread (potentially reporting back to a GUI thread).