# TaskRunner

<a id="taskrunner-1"></a>

# TaskRunner

```cpp
#include <icy/task.h>

class TaskRunner
```

[Defined in src/base/include/icy/task.h:93](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L93)

> **Inherits:** [`Runnable`](https://auscaster.com/icey/docs/api-reference/icy-basic-Runnable.md#runnable)
> **Subclassed by:** [`Scheduler`](https://auscaster.com/icey/docs/api-reference/icy-sched-Scheduler.md#scheduler)

[Runner](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner) for tasks that inherit the [`Task`](https://auscaster.com/icey/docs/api-reference/icy-Task.md#task) interface.

The [`TaskRunner`](#taskrunner-1) continually loops through each task in the task list calling the task's [`run()`](#run-6) method.

The [`TaskRunner`](#taskrunner-1) is powered by an abstract [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner) instance, which means that tasks can be executed in a thread or event loop context.

## List of all members

| Name | Kind | Owner |
|------|------|-------|
| [`Idle`](#idle) | `variable` | Declared here |
| [`Shutdown`](#shutdown-1) | `variable` | Declared here |
| [`TaskRunner`](#taskrunner-2) | `function` | Declared here |
| [`~TaskRunner`](#taskrunner-3) | `function` | Declared here |
| [`TaskRunner`](#taskrunner-4) | `function` | Declared here |
| [`operator=`](#operator-98) | `function` | Declared here |
| [`TaskRunner`](#taskrunner-5) | `function` | Declared here |
| [`operator=`](#operator-99) | `function` | Declared here |
| [`start`](#start-7) | `function` | Declared here |
| [`cancel`](#cancel-5) | `function` | Declared here |
| [`destroy`](#destroy-3) | `function` | Declared here |
| [`exists`](#exists-1) | `function` | Declared here |
| [`get`](#get-12) | `function` | Declared here |
| [`setRunner`](#setrunner) | `function` | Declared here |
| [`className`](#classname-4) | `function` | Declared here |
| [`getDefault`](#getdefault-2) | `function` | Declared here |
| [`_mutex`](#_mutex-6) | `variable` | Declared here |
| [`_runner`](#_runner) | `variable` | Declared here |
| [`_tasks`](#_tasks) | `variable` | Declared here |
| [`_current`](#_current) | `variable` | Declared here |
| [`run`](#run-6) | `function` | Declared here |
| [`add`](#add-6) | `function` | Declared here |
| [`remove`](#remove-3) | `function` | Declared here |
| [`next`](#next-2) | `function` | Declared here |
| [`clear`](#clear-5) | `function` | Declared here |
| [`onAdd`](#onadd-2) | `function` | Declared here |
| [`onStart`](#onstart) | `function` | Declared here |
| [`onCancel`](#oncancel) | `function` | Declared here |
| [`onRemove`](#onremove-2) | `function` | Declared here |
| [`onRun`](#onrun) | `function` | Declared here |
| [`Runnable`](https://auscaster.com/icey/docs/api-reference/icy-basic-Runnable.md#runnable-1) | `function` | Inherited from [`Runnable`](https://auscaster.com/icey/docs/api-reference/icy-basic-Runnable.md#runnable) |
| [`~Runnable`](https://auscaster.com/icey/docs/api-reference/icy-basic-Runnable.md#runnable-2) | `function` | Inherited from [`Runnable`](https://auscaster.com/icey/docs/api-reference/icy-basic-Runnable.md#runnable) |
| [`run`](https://auscaster.com/icey/docs/api-reference/icy-basic-Runnable.md#run-11) | `function` | Inherited from [`Runnable`](https://auscaster.com/icey/docs/api-reference/icy-basic-Runnable.md#runnable) |
| [`cancel`](https://auscaster.com/icey/docs/api-reference/icy-basic-Runnable.md#cancel-7) | `function` | Inherited from [`Runnable`](https://auscaster.com/icey/docs/api-reference/icy-basic-Runnable.md#runnable) |
| [`cancelled`](https://auscaster.com/icey/docs/api-reference/icy-basic-Runnable.md#cancelled-3) | `function` | Inherited from [`Runnable`](https://auscaster.com/icey/docs/api-reference/icy-basic-Runnable.md#runnable) |
| [`exit`](https://auscaster.com/icey/docs/api-reference/icy-basic-Runnable.md#exit) | `variable` | Inherited from [`Runnable`](https://auscaster.com/icey/docs/api-reference/icy-basic-Runnable.md#runnable) |

## Inherited from [`Runnable`](https://auscaster.com/icey/docs/api-reference/icy-basic-Runnable.md#runnable)

| Kind | Name | Description |
|------|------|-------------|
| `function` | [`Runnable`](https://auscaster.com/icey/docs/api-reference/icy-basic-Runnable.md#runnable-1) `inline` |  |
| `function` | [`~Runnable`](https://auscaster.com/icey/docs/api-reference/icy-basic-Runnable.md#runnable-2) `virtual` | Defaulted destructor. |
| `function` | [`run`](https://auscaster.com/icey/docs/api-reference/icy-basic-Runnable.md#run-11) `virtual` | The run method will be called by the asynchronous context. |
| `function` | [`cancel`](https://auscaster.com/icey/docs/api-reference/icy-basic-Runnable.md#cancel-7) `virtual` `inline` | Cancel the current task. The [run()](https://auscaster.com/icey/docs/api-reference/icy-basic-Runnable.md#run-11) method should return ASAP. |
| `function` | [`cancelled`](https://auscaster.com/icey/docs/api-reference/icy-basic-Runnable.md#cancelled-3) `virtual` `const` `inline` | Returns true when the task has been cancelled. |
| `variable` | [`exit`](https://auscaster.com/icey/docs/api-reference/icy-basic-Runnable.md#exit)  |  |

## Public Attributes

| Return | Name | Description |
|--------|------|-------------|
| [`NullSignal`](https://auscaster.com/icey/docs/api-reference/base.md#nullsignal) | [`Idle`](#idle)  | Fires after completing an iteration of all tasks. |
| [`NullSignal`](https://auscaster.com/icey/docs/api-reference/base.md#nullsignal) | [`Shutdown`](#shutdown-1)  | Signals when the [`TaskRunner`](#taskrunner-1) is shutting down. |

---

<a id="idle"></a>

### Idle

```cpp
NullSignal Idle
```

Type: [`NullSignal`](https://auscaster.com/icey/docs/api-reference/base.md#nullsignal)

[Defined in src/base/include/icy/task.h:138](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L138)

Fires after completing an iteration of all tasks.

---

<a id="shutdown-1"></a>

### Shutdown

```cpp
NullSignal Shutdown
```

Type: [`NullSignal`](https://auscaster.com/icey/docs/api-reference/base.md#nullsignal)

[Defined in src/base/include/icy/task.h:141](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L141)

Signals when the [`TaskRunner`](#taskrunner-1) is shutting down.

## Public Methods

| Return | Name | Description |
|--------|------|-------------|
|  | [`TaskRunner`](#taskrunner-2)  |  |
|  | [`~TaskRunner`](#taskrunner-3) `virtual` |  |
|  | [`TaskRunner`](#taskrunner-4)  | Deleted constructor. |
| [`TaskRunner`](#taskrunner-1) & | [`operator=`](#operator-98)  | Deleted assignment operator. |
|  | [`TaskRunner`](#taskrunner-5)  | Deleted constructor. |
| [`TaskRunner`](#taskrunner-1) & | [`operator=`](#operator-99)  | Deleted assignment operator. |
| `bool` | [`start`](#start-7) `virtual` | Starts a task, adding it if it doesn't exist. |
| `bool` | [`cancel`](#cancel-5) `virtual` | Cancels a task. |
| `bool` | [`destroy`](#destroy-3) `virtual` | Queues a task for destruction. |
| `bool` | [`exists`](#exists-1) `virtual` `const` | Returns whether a task exists. |
| [`Task`](https://auscaster.com/icey/docs/api-reference/icy-Task.md#task) * | [`get`](#get-12) `virtual` `const` | Returns the task pointer matching the given ID, or nullptr if no task exists. |
| `void` | [`setRunner`](#setrunner) `virtual` | Set the asynchronous context for packet processing. This may be a [Thread](https://auscaster.com/icey/docs/api-reference/icy-Thread.md#thread-1) or another derivative of Async. Must be set before the stream is activated. |
| `const char *` | [`className`](#classname-4) `virtual` `const` `inline` |  |

---

<a id="taskrunner-2"></a>

### TaskRunner

```cpp
TaskRunner(std::shared_ptr< Runner > runner = nullptr)
```

[Defined in src/base/include/icy/task.h:97](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L97)

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `runner` | std::shared_ptr< [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner) > | Async runner to drive task execution; defaults to a new [`Thread`](https://auscaster.com/icey/docs/api-reference/icy-Thread.md#thread-1). |

---

<a id="taskrunner-3"></a>

### ~TaskRunner

`virtual`

```cpp
virtual ~TaskRunner()
```

[Defined in src/base/include/icy/task.h:98](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L98)

---

<a id="taskrunner-4"></a>

### TaskRunner

```cpp
TaskRunner(const TaskRunner &) = delete
```

[Defined in src/base/include/icy/task.h:100](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L100)

Deleted constructor.

---

<a id="operator-98"></a>

### operator=

```cpp
TaskRunner & operator=(const TaskRunner &) = delete
```

[Defined in src/base/include/icy/task.h:101](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L101)

Deleted assignment operator.

---

<a id="taskrunner-5"></a>

### TaskRunner

```cpp
TaskRunner(TaskRunner &&) = delete
```

[Defined in src/base/include/icy/task.h:102](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L102)

Deleted constructor.

---

<a id="operator-99"></a>

### operator=

```cpp
TaskRunner & operator=(TaskRunner &&) = delete
```

[Defined in src/base/include/icy/task.h:103](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L103)

Deleted assignment operator.

---

<a id="start-7"></a>

### start

`virtual`

```cpp
virtual bool start(Task * task)
```

[Defined in src/base/include/icy/task.h:106](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L106)

Starts a task, adding it if it doesn't exist.

---

<a id="cancel-5"></a>

### cancel

`virtual`

```cpp
virtual bool cancel(Task * task)
```

[Defined in src/base/include/icy/task.h:114](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L114)

Cancels a task.

The task reference will be managed by the [TaskRunner](#taskrunner-1) until the task is destroyed.

---

<a id="destroy-3"></a>

### destroy

`virtual`

```cpp
virtual bool destroy(Task * task)
```

[Defined in src/base/include/icy/task.h:117](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L117)

Queues a task for destruction.

---

<a id="exists-1"></a>

### exists

`virtual` `const`

```cpp
virtual bool exists(Task * task) const
```

[Defined in src/base/include/icy/task.h:120](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L120)

Returns whether a task exists.

---

<a id="get-12"></a>

### get

`virtual` `const`

```cpp
virtual Task * get(uint32_t id) const
```

[Defined in src/base/include/icy/task.h:124](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L124)

Returns the task pointer matching the given ID, or nullptr if no task exists.

---

<a id="setrunner"></a>

### setRunner

`virtual`

```cpp
virtual void setRunner(std::shared_ptr< Runner > runner)
```

[Defined in src/base/include/icy/task.h:129](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L129)

Set the asynchronous context for packet processing. This may be a [Thread](https://auscaster.com/icey/docs/api-reference/icy-Thread.md#thread-1) or another derivative of Async. Must be set before the stream is activated.

---

<a id="classname-4"></a>

### className

`virtual` `const` `inline`

```cpp
virtual inline const char * className() const
```

[Defined in src/base/include/icy/task.h:143](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L143)

## Public Static Methods

| Return | Name | Description |
|--------|------|-------------|
| [`TaskRunner`](#taskrunner-1) & | [`getDefault`](#getdefault-2) `static` | Returns the default [`TaskRunner`](#taskrunner-1) singleton, although [TaskRunner](#taskrunner-1) instances may be initialized individually. The default runner should be kept for short running tasks such as timers in order to maintain performance. |

---

<a id="getdefault-2"></a>

### getDefault

`static`

```cpp
static TaskRunner & getDefault()
```

[Defined in src/base/include/icy/task.h:135](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L135)

Returns the default [`TaskRunner`](#taskrunner-1) singleton, although [TaskRunner](#taskrunner-1) instances may be initialized individually. The default runner should be kept for short running tasks such as timers in order to maintain performance.

## Protected Attributes

| Return | Name | Description |
|--------|------|-------------|
| `std::mutex` | [`_mutex`](#_mutex-6)  |  |
| std::shared_ptr< [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner) > | [`_runner`](#_runner)  |  |
| `TaskList` | [`_tasks`](#_tasks)  |  |
| [`Task`](https://auscaster.com/icey/docs/api-reference/icy-Task.md#task) * | [`_current`](#_current)  | [Task](https://auscaster.com/icey/docs/api-reference/icy-Task.md#task) currently executing in [run()](#run-6). It is extracted from `_tasks` while running so other threads cannot delete it mid-execution; [exists()](#exists-1)/get()/remove() must consult it under `_mutex`. |

---

<a id="_mutex-6"></a>

### _mutex

```cpp
std::mutex _mutex
```

[Defined in src/base/include/icy/task.h:179](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L179)

---

<a id="_runner"></a>

### _runner

```cpp
std::shared_ptr< Runner > _runner
```

Type: std::shared_ptr< [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner) >

[Defined in src/base/include/icy/task.h:180](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L180)

---

<a id="_tasks"></a>

### _tasks

```cpp
TaskList _tasks
```

Type: `TaskList`

[Defined in src/base/include/icy/task.h:181](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L181)

---

<a id="_current"></a>

### _current

```cpp
Task * _current = nullptr
```

Type: [`Task`](https://auscaster.com/icey/docs/api-reference/icy-Task.md#task) *

[Defined in src/base/include/icy/task.h:186](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L186)

[Task](https://auscaster.com/icey/docs/api-reference/icy-Task.md#task) currently executing in [run()](#run-6). It is extracted from `_tasks` while running so other threads cannot delete it mid-execution; [exists()](#exists-1)/get()/remove() must consult it under `_mutex`.

## Protected Methods

| Return | Name | Description |
|--------|------|-------------|
| `void` | [`run`](#run-6) `virtual` `override` | Called by the async context to run the next task. |
| `bool` | [`add`](#add-6) `virtual` | Adds a task to the runner. |
| `bool` | [`remove`](#remove-3) `virtual` | Removes a task from the runner. |
| [`Task`](https://auscaster.com/icey/docs/api-reference/icy-Task.md#task) * | [`next`](#next-2) `virtual` `const` | Returns the next task to be run. |
| `void` | [`clear`](#clear-5) `virtual` | Destroys and clears all manages tasks. |
| `void` | [`onAdd`](#onadd-2) `virtual` | Called after a task is added. |
| `void` | [`onStart`](#onstart) `virtual` | Called after a task is started. |
| `void` | [`onCancel`](#oncancel) `virtual` | Called after a task is cancelled. |
| `void` | [`onRemove`](#onremove-2) `virtual` | Called after a task is removed. |
| `void` | [`onRun`](#onrun) `virtual` | Called after a task has run. |

---

<a id="run-6"></a>

### run

`virtual` `override`

```cpp
virtual void run() override
```

[Defined in src/base/include/icy/task.h:147](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L147)

Called by the async context to run the next task.

#### Reimplements

- [`Runnable::run`](https://auscaster.com/icey/docs/api-reference/icy-basic-Runnable.md#run-11)

---

<a id="add-6"></a>

### add

`virtual`

```cpp
virtual bool add(Task * task)
```

[Defined in src/base/include/icy/task.h:150](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L150)

Adds a task to the runner.

---

<a id="remove-3"></a>

### remove

`virtual`

```cpp
virtual bool remove(Task * task)
```

[Defined in src/base/include/icy/task.h:153](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L153)

Removes a task from the runner.

---

<a id="next-2"></a>

### next

`virtual` `const`

```cpp
virtual Task * next() const
```

[Defined in src/base/include/icy/task.h:156](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L156)

Returns the next task to be run.

---

<a id="clear-5"></a>

### clear

`virtual`

```cpp
virtual void clear()
```

[Defined in src/base/include/icy/task.h:159](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L159)

Destroys and clears all manages tasks.

#### Reimplemented by

- [`Scheduler::clear`](https://auscaster.com/icey/docs/api-reference/icy-sched-Scheduler.md#clear-9)

---

<a id="onadd-2"></a>

### onAdd

`virtual`

```cpp
virtual void onAdd(Task * task)
```

[Defined in src/base/include/icy/task.h:162](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L162)

Called after a task is added.

---

<a id="onstart"></a>

### onStart

`virtual`

```cpp
virtual void onStart(Task * task)
```

[Defined in src/base/include/icy/task.h:165](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L165)

Called after a task is started.

---

<a id="oncancel"></a>

### onCancel

`virtual`

```cpp
virtual void onCancel(Task * task)
```

[Defined in src/base/include/icy/task.h:168](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L168)

Called after a task is cancelled.

---

<a id="onremove-2"></a>

### onRemove

`virtual`

```cpp
virtual void onRemove(Task * task)
```

[Defined in src/base/include/icy/task.h:171](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L171)

Called after a task is removed.

---

<a id="onrun"></a>

### onRun

`virtual`

```cpp
virtual void onRun(Task * task)
```

[Defined in src/base/include/icy/task.h:174](https://github.com/auscaster/icey/blob/main/src/base/include/icy/task.h#L174)

Called after a task has run.