# Runner

<a id="runner"></a>

# Runner

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

class Runner
```

[Defined in src/base/include/icy/runner.h:34](https://github.com/auscaster/icey/blob/main/src/base/include/icy/runner.h#L34)

> **Subclassed by:** [`Idler`](https://auscaster.com/icey/docs/api-reference/icy-Idler.md#idler), [`Synchronizer`](https://auscaster.com/icey/docs/api-reference/icy-Synchronizer.md#synchronizer), [`Thread`](https://auscaster.com/icey/docs/api-reference/icy-Thread.md#thread-1), [`Timer`](https://auscaster.com/icey/docs/api-reference/icy-Timer.md#timer)

[Runner](#runner) is a virtual interface for implementing asynchronous objects such as threads and futures.

## Public Methods

| Return | Name | Description |
|--------|------|-------------|
|  | [`Runner`](#runner-1)  |  |
|  | [`~Runner`](#runner-2) `virtual` |  |
| `void` | [`start`](#start-3) `virtual` | Starts the asynchronous context with the given callback. The callback must remain valid for the lifetime of the [`Runner`](#runner). |
| `bool` | [`running`](#running) `const` | Returns true if the async context is currently running. |
| `void` | [`cancel`](#cancel-2)  | Signals the async context to stop at the earliest opportunity. |
| `bool` | [`cancelled`](#cancelled-1) `const` | Returns true if the context has been cancelled. The implementation is responsible for exiting as soon as possible after cancellation. |
| `bool` | [`repeating`](#repeating) `const` | Returns true if the runner is in repeating mode. |
| `void` | [`setRepeating`](#setrepeating)  | Enables or disables repeating mode. When repeating, the target function is invoked repeatedly until [`cancel()`](#cancel-2) is called. This normalizes behaviour across thread-based and event-loop-based [`Runner`](#runner) implementations. Must be called before [`start()`](#start-3). |
| `bool` | [`async`](#async-1) `virtual` `const` | Returns true if the implementation is thread-based. |
| `std::thread::id` | [`tid`](#tid) `const` | Returns the native thread ID of the thread running the async context. |
| `bool` | [`waitForExit`](#waitforexit)  | Blocks until the async context exits or the timeout elapses. The context should be cancelled before calling this method. Must be called from outside the runner's own thread to avoid deadlock. |

---

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

### Runner

```cpp
Runner()
```

[Defined in src/base/include/icy/runner.h:37](https://github.com/auscaster/icey/blob/main/src/base/include/icy/runner.h#L37)

---

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

### ~Runner

`virtual`

```cpp
virtual ~Runner()
```

[Defined in src/base/include/icy/runner.h:38](https://github.com/auscaster/icey/blob/main/src/base/include/icy/runner.h#L38)

---

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

### start

`virtual`

```cpp
virtual void start(std::function< void()> target)
```

[Defined in src/base/include/icy/runner.h:43](https://github.com/auscaster/icey/blob/main/src/base/include/icy/runner.h#L43)

Starts the asynchronous context with the given callback. The callback must remain valid for the lifetime of the [`Runner`](#runner).

#### Reimplemented by

- [`Idler::start`](https://auscaster.com/icey/docs/api-reference/icy-Idler.md#start-1)
- [`Synchronizer::start`](https://auscaster.com/icey/docs/api-reference/icy-Synchronizer.md#start-6)
- [`Thread::start`](https://auscaster.com/icey/docs/api-reference/icy-Thread.md#start-9)
- [`Timer::start`](https://auscaster.com/icey/docs/api-reference/icy-Timer.md#start-13)

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `target` | `std::function< void()>` | Callable to invoke when the context runs. |

---

<a id="running"></a>

### running

`const`

```cpp
bool running() const
```

[Defined in src/base/include/icy/runner.h:47](https://github.com/auscaster/icey/blob/main/src/base/include/icy/runner.h#L47)

Returns true if the async context is currently running. 
#### Returns
True if the runner's context has been started and has not yet stopped.

---

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

### cancel

```cpp
void cancel()
```

[Defined in src/base/include/icy/runner.h:50](https://github.com/auscaster/icey/blob/main/src/base/include/icy/runner.h#L50)

Signals the async context to stop at the earliest opportunity.

---

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

### cancelled

`const`

```cpp
bool cancelled() const
```

[Defined in src/base/include/icy/runner.h:55](https://github.com/auscaster/icey/blob/main/src/base/include/icy/runner.h#L55)

Returns true if the context has been cancelled. The implementation is responsible for exiting as soon as possible after cancellation. 
#### Returns
True if [`cancel()`](#cancel-2) has been called.

---

<a id="repeating"></a>

### repeating

`const`

```cpp
bool repeating() const
```

[Defined in src/base/include/icy/runner.h:59](https://github.com/auscaster/icey/blob/main/src/base/include/icy/runner.h#L59)

Returns true if the runner is in repeating mode. 
#### Returns
True if the target function is invoked in a loop until cancelled.

---

<a id="setrepeating"></a>

### setRepeating

```cpp
void setRepeating(bool flag)
```

[Defined in src/base/include/icy/runner.h:66](https://github.com/auscaster/icey/blob/main/src/base/include/icy/runner.h#L66)

Enables or disables repeating mode. When repeating, the target function is invoked repeatedly until [`cancel()`](#cancel-2) is called. This normalizes behaviour across thread-based and event-loop-based [`Runner`](#runner) implementations. Must be called before [`start()`](#start-3).

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `flag` | `bool` | True to enable repeating mode, false to run the target once. |

---

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

### async

`virtual` `const`

```cpp
virtual bool async() const
```

[Defined in src/base/include/icy/runner.h:70](https://github.com/auscaster/icey/blob/main/src/base/include/icy/runner.h#L70)

Returns true if the implementation is thread-based. 
#### Returns
True for thread-backed runners, false for event-loop-driven runners.

#### Reimplemented by

- [`Idler::async`](https://auscaster.com/icey/docs/api-reference/icy-Idler.md#async)
- [`Synchronizer::async`](https://auscaster.com/icey/docs/api-reference/icy-Synchronizer.md#async-2)
- [`Thread::async`](https://auscaster.com/icey/docs/api-reference/icy-Thread.md#async-3)
- [`Timer::async`](https://auscaster.com/icey/docs/api-reference/icy-Timer.md#async-4)

---

<a id="tid"></a>

### tid

`const`

```cpp
std::thread::id tid() const
```

[Defined in src/base/include/icy/runner.h:74](https://github.com/auscaster/icey/blob/main/src/base/include/icy/runner.h#L74)

Returns the native thread ID of the thread running the async context. 
#### Returns
`std::thread::id` of the runner thread, or a default-constructed ID if not started.

---

<a id="waitforexit"></a>

### waitForExit

```cpp
bool waitForExit(int timeout = 5000)
```

[Defined in src/base/include/icy/runner.h:81](https://github.com/auscaster/icey/blob/main/src/base/include/icy/runner.h#L81)

Blocks until the async context exits or the timeout elapses. The context should be cancelled before calling this method. Must be called from outside the runner's own thread to avoid deadlock. 
#### Returns
True if the context exited cleanly, false if the timeout was reached (throws instead).

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `timeout` | `int` | Maximum number of milliseconds to wait. Pass 0 to wait indefinitely. |

## Protected Attributes

| Return | Name | Description |
|--------|------|-------------|
| std::shared_ptr< [`Context`](https://auscaster.com/icey/docs/api-reference/icy-Runner-Context.md#context) > | [`_context`](#_context)  | Shared pointer to the internal [Context](https://auscaster.com/icey/docs/api-reference/icy-Runner-Context.md#context). |

---

<a id="_context"></a>

### _context

```cpp
std::shared_ptr< Context > _context
```

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

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

Shared pointer to the internal [Context](https://auscaster.com/icey/docs/api-reference/icy-Runner-Context.md#context).

## Protected Methods

| Return | Name | Description |
|--------|------|-------------|
|  | [`Runner`](#runner-3)  | NonCopyable and NonMovable. |
| [`Runner`](#runner) & | [`operator=`](#operator-81)  | Deleted assignment operator. |
|  | [`Runner`](#runner-4)  | Deleted constructor. |
| [`Runner`](#runner) & | [`operator=`](#operator-82)  | Deleted assignment operator. |

---

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

### Runner

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

[Defined in src/base/include/icy/runner.h:111](https://github.com/auscaster/icey/blob/main/src/base/include/icy/runner.h#L111)

NonCopyable and NonMovable.

---

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

### operator=

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

[Defined in src/base/include/icy/runner.h:112](https://github.com/auscaster/icey/blob/main/src/base/include/icy/runner.h#L112)

Deleted assignment operator.

---

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

### Runner

```cpp
Runner(Runner &&) = delete
```

[Defined in src/base/include/icy/runner.h:113](https://github.com/auscaster/icey/blob/main/src/base/include/icy/runner.h#L113)

Deleted constructor.

---

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

### operator=

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

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

Deleted assignment operator.