# Idler

<a id="idler"></a>

# Idler

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

class Idler
```

[Defined in src/base/include/icy/idler.h:31](https://github.com/auscaster/icey/blob/main/src/base/include/icy/idler.h#L31)

> **Inherits:** [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner)

Asynchronous type that triggers callbacks when the event loop is idle.

This class inherits the [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner) interface and may be used with any implementation that's powered by an asynchronous [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner).

## List of all members

| Name | Kind | Owner |
|------|------|-------|
| [`Idler`](#idler-1) | `function` | Declared here |
| [`Idler`](#idler-2) | `function` | Declared here |
| [`Idler`](#idler-3) | `function` | Declared here |
| [`start`](#start) | `function` | Declared here |
| [`start`](#start-1) | `function` | Declared here |
| [`~Idler`](#idler-4) | `function` | Declared here |
| [`handle`](#handle) | `function` | Declared here |
| [`_handle`](#_handle) | `variable` | Declared here |
| [`init`](#init-2) | `function` | Declared here |
| [`async`](#async) | `function` | Declared here |
| [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner-1) | `function` | Inherited from [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner) |
| [`~Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner-2) | `function` | Inherited from [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner) |
| [`start`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#start-3) | `function` | Inherited from [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner) |
| [`running`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#running) | `function` | Inherited from [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner) |
| [`cancel`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#cancel-2) | `function` | Inherited from [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner) |
| [`cancelled`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#cancelled-1) | `function` | Inherited from [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner) |
| [`repeating`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#repeating) | `function` | Inherited from [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner) |
| [`setRepeating`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#setrepeating) | `function` | Inherited from [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner) |
| [`async`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#async-1) | `function` | Inherited from [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner) |
| [`tid`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#tid) | `function` | Inherited from [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner) |
| [`waitForExit`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#waitforexit) | `function` | Inherited from [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner) |
| [`_context`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#_context) | `variable` | Inherited from [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner) |
| [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner-3) | `function` | Inherited from [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner) |
| [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#operator-81) | `function` | Inherited from [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner) |
| [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner-4) | `function` | Inherited from [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner) |
| [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#operator-82) | `function` | Inherited from [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner) |

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

| Kind | Name | Description |
|------|------|-------------|
| `function` | [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner-1)  |  |
| `function` | [`~Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner-2) `virtual` |  |
| `function` | [`start`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#start-3) `virtual` | Starts the asynchronous context with the given callback. The callback must remain valid for the lifetime of the [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner). |
| `function` | [`running`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#running) `const` | Returns true if the async context is currently running. |
| `function` | [`cancel`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#cancel-2)  | Signals the async context to stop at the earliest opportunity. |
| `function` | [`cancelled`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#cancelled-1) `const` | Returns true if the context has been cancelled. The implementation is responsible for exiting as soon as possible after cancellation. |
| `function` | [`repeating`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#repeating) `const` | Returns true if the runner is in repeating mode. |
| `function` | [`setRepeating`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#setrepeating)  | Enables or disables repeating mode. When repeating, the target function is invoked repeatedly until [`cancel()`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#cancel-2) is called. This normalizes behaviour across thread-based and event-loop-based [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner) implementations. Must be called before [`start()`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#start-3). |
| `function` | [`async`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#async-1) `virtual` `const` | Returns true if the implementation is thread-based. |
| `function` | [`tid`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#tid) `const` | Returns the native thread ID of the thread running the async context. |
| `function` | [`waitForExit`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#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. |
| `variable` | [`_context`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#_context)  | Shared pointer to the internal [Context](https://auscaster.com/icey/docs/api-reference/icy-Runner-Context.md#context). |
| `function` | [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner-3)  | NonCopyable and NonMovable. |
| `function` | [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#operator-81)  | Deleted assignment operator. |
| `function` | [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner-4)  | Deleted constructor. |
| `function` | [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#operator-82)  | Deleted assignment operator. |

## Public Methods

| Return | Name | Description |
|--------|------|-------------|
|  | [`Idler`](#idler-1)  | Create the idler bound to `loop` without starting it. |
|  | [`Idler`](#idler-2) `inline` `explicit` | Create and immediately start the idler on the default loop. |
|  | [`Idler`](#idler-3) `inline` `explicit` | Create and immediately start the idler on the given loop. |
| `void` | [`start`](#start) `inline` | Start the idler, invoking `func` (with `args`) on every idle iteration. |
| `void` | [`start`](#start-1) `virtual` `override` | Start the idler with a type-erased callback (implements [`Runner::start`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#start-3)). |
|  | [`~Idler`](#idler-4) `virtual` | Defaulted destructor. |
| [`uv::Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6)< uv_idle_t > & | [`handle`](#handle)  |  |

---

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

### Idler

```cpp
Idler(uv::Loop * loop = uv::defaultLoop())
```

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

Create the idler bound to `loop` without starting it.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `loop` | [`uv::Loop`](https://auscaster.com/icey/docs/api-reference/uv.md#loop-1) * | Event loop to associate with. Defaults to the process-wide default loop. |

---

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

### Idler

`inline` `explicit`

```cpp
template<typename Function, typename... Args> inline explicit Idler(Function && func, Args &&... args)
```

[Defined in src/base/include/icy/idler.h:44](https://github.com/auscaster/icey/blob/main/src/base/include/icy/idler.h#L44)

Create and immediately start the idler on the default loop.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `func` | `Function &&` | Callable invoked on every idle iteration. |
| `args` | `Args &&...` | Arguments forwarded to `func`. |

---

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

### Idler

`inline` `explicit`

```cpp
template<typename Function, typename... Args> inline explicit Idler(uv::Loop * loop, Function && func, Args &&... args)
```

[Defined in src/base/include/icy/idler.h:57](https://github.com/auscaster/icey/blob/main/src/base/include/icy/idler.h#L57)

Create and immediately start the idler on the given loop.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `loop` | [`uv::Loop`](https://auscaster.com/icey/docs/api-reference/uv.md#loop-1) * | Event loop to associate with. |
| `func` | `Function &&` | Callable invoked on every idle iteration. |
| `args` | `Args &&...` | Arguments forwarded to `func`. |

---

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

### start

`inline`

```cpp
template<typename Function, typename... Args> inline void start(Function && func, Args &&... args)
```

[Defined in src/base/include/icy/idler.h:73](https://github.com/auscaster/icey/blob/main/src/base/include/icy/idler.h#L73)

Start the idler, invoking `func` (with `args`) on every idle iteration.

The idler always runs in repeating mode; cancel via [`Runner::cancel()`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#cancel-2). Throws `std::logic_error` if the handle is already active or the runner context reports it is still running.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `func` | `Function &&` | Callable invoked each time the event loop is idle. |
| `args` | `Args &&...` | Arguments forwarded to `func` on each invocation. |

---

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

### start

`virtual` `override`

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

[Defined in src/base/include/icy/idler.h:118](https://github.com/auscaster/icey/blob/main/src/base/include/icy/idler.h#L118)

Start the idler with a type-erased callback (implements [`Runner::start`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#start-3)).

#### Reimplements

- [`Runner::start`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#start-3)

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `func` | `std::function< void()>` | Callback invoked on every idle iteration. |

---

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

### ~Idler

`virtual`

```cpp
virtual ~Idler() = default
```

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

Defaulted destructor.

---

<a id="handle"></a>

### handle

```cpp
uv::Handle< uv_idle_t > & handle()
```

[Defined in src/base/include/icy/idler.h:123](https://github.com/auscaster/icey/blob/main/src/base/include/icy/idler.h#L123)

#### Returns
Reference to the underlying `uv_idle_t` handle wrapper.

## Protected Attributes

| Return | Name | Description |
|--------|------|-------------|
| [`uv::Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6)< uv_idle_t > | [`_handle`](#_handle)  |  |

---

<a id="_handle"></a>

### _handle

```cpp
uv::Handle< uv_idle_t > _handle
```

Type: [`uv::Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6)< uv_idle_t >

[Defined in src/base/include/icy/idler.h:132](https://github.com/auscaster/icey/blob/main/src/base/include/icy/idler.h#L132)

## Protected Methods

| Return | Name | Description |
|--------|------|-------------|
| `void` | [`init`](#init-2) `virtual` | Initialize the underlying `uv_idle_t` handle and unref it from the loop. |
| `bool` | [`async`](#async) `virtual` `const` `override` |  |

---

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

### init

`virtual`

```cpp
virtual void init()
```

[Defined in src/base/include/icy/idler.h:127](https://github.com/auscaster/icey/blob/main/src/base/include/icy/idler.h#L127)

Initialize the underlying `uv_idle_t` handle and unref it from the loop.

---

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

### async

`virtual` `const` `override`

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

[Defined in src/base/include/icy/idler.h:130](https://github.com/auscaster/icey/blob/main/src/base/include/icy/idler.h#L130)

#### Returns
`false`; the idler is event-loop-driven, not thread-based.

#### Reimplements

- [`Runner::async`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#async-1)