# Timer # Timer ```cpp #include class Timer ``` [Defined in src/base/include/icy/timer.h:27](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L27) > **Inherits:** [`Runner`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#runner) Asynchronous event based timer. ## List of all members | Name | Kind | Owner | |------|------|-------| | [`Timeout`](#timeout-6) | `variable` | Declared here | | [`Timer`](#timer-1) | `function` | Declared here | | [`Timer`](#timer-2) | `function` | Declared here | | [`Timer`](#timer-3) | `function` | Declared here | | [`~Timer`](#timer-4) | `function` | Declared here | | [`start`](#start-12) | `function` | Declared here | | [`start`](#start-13) | `function` | Declared here | | [`stop`](#stop-5) | `function` | Declared here | | [`restart`](#restart-1) | `function` | Declared here | | [`again`](#again) | `function` | Declared here | | [`setTimeout`](#settimeout-2) | `function` | Declared here | | [`setInterval`](#setinterval) | `function` | Declared here | | [`active`](#active-2) | `function` | Declared here | | [`timeout`](#timeout-7) | `function` | Declared here | | [`interval`](#interval) | `function` | Declared here | | [`count`](#count) | `function` | Declared here | | [`handle`](#handle-3) | `function` | Declared here | | [`async`](#async-4) | `function` | Declared here | | [`_handle`](#_handle-3) | `variable` | Declared here | | [`_timeout`](#_timeout-1) | `variable` | Declared here | | [`_interval`](#_interval) | `variable` | Declared here | | [`_count`](#_count) | `variable` | Declared here | | [`Timer`](#timer-5) | `function` | Declared here | | [`operator=`](#operator-106) | `function` | Declared here | | [`Timer`](#timer-6) | `function` | Declared here | | [`operator=`](#operator-107) | `function` | Declared here | | [`init`](#init-5) | `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 Attributes | Return | Name | Description | |--------|------|-------------| | [`NullSignal`](https://auscaster.com/icey/docs/api-reference/base.md#nullsignal) | [`Timeout`](#timeout-6) | [Signal](https://auscaster.com/icey/docs/api-reference/icy-Signal.md#signal) that gets triggered on timeout. | --- ### Timeout ```cpp NullSignal Timeout ``` Type: [`NullSignal`](https://auscaster.com/icey/docs/api-reference/base.md#nullsignal) [Defined in src/base/include/icy/timer.h:130](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L130) [Signal](https://auscaster.com/icey/docs/api-reference/icy-Signal.md#signal) that gets triggered on timeout. ## Public Methods | Return | Name | Description | |--------|------|-------------| | | [`Timer`](#timer-1) | Create a timer without a timeout or interval; values must be set before [`start()`](#start-12). | | | [`Timer`](#timer-2) | Create a one-shot timer that fires after `timeout` milliseconds. | | | [`Timer`](#timer-3) | Create a repeating timer with an initial delay and a repeat period. | | | [`~Timer`](#timer-4) `virtual` | Destructor. | | `void` | [`start`](#start-12) | Start the timer using the previously configured timeout and interval. | | `void` | [`start`](#start-13) `virtual` `override` | Connect `func` to the [`Timeout`](https://auscaster.com/icey/docs/api-reference/icy-Timeout.md#timeout-1) signal and start the timer. | | `void` | [`stop`](#stop-5) | Stop the timer. Resets the fire count to zero. | | `void` | [`restart`](#restart-1) | Restart the timer. | | `void` | [`again`](#again) | Reset the countdown without stopping and restarting the timer. | | `void` | [`setTimeout`](#settimeout-2) | Set the initial delay before the first timeout event. | | `void` | [`setInterval`](#setinterval) | Set the repeat interval (calls `uv_timer_set_repeat`). | | `bool` | [`active`](#active-2) `const` | | | `std::int64_t` | [`timeout`](#timeout-7) `const` | | | `std::int64_t` | [`interval`](#interval) `const` | | | `std::int64_t` | [`count`](#count) | | | [`uv::Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6)< uv_timer_t > & | [`handle`](#handle-3) | | | `bool` | [`async`](#async-4) `virtual` `const` `override` | | --- ### Timer ```cpp Timer(uv::Loop * loop = uv::defaultLoop()) ``` [Defined in src/base/include/icy/timer.h:33](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L33) Create a timer without a timeout or interval; values must be set before [`start()`](#start-12). #### 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. | --- ### Timer ```cpp Timer(std::int64_t timeout, uv::Loop * loop = uv::defaultLoop(), std::function< void()> func = nullptr) ``` [Defined in src/base/include/icy/timer.h:44](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L44) Create a one-shot timer that fires after `timeout` milliseconds. If `func` is provided the timer starts immediately; otherwise call [`start()`](#start-12) manually. #### Parameters | Parameter | Type | Description | |-----------|------|-------------| | `timeout` | `std::int64_t` | Delay in milliseconds before the first (and only) fire. | | `loop` | [`uv::Loop`](https://auscaster.com/icey/docs/api-reference/uv.md#loop-1) * | Event loop to associate with. | | `func` | `std::function< void()>` | Optional callback connected to the [`Timeout`](https://auscaster.com/icey/docs/api-reference/icy-Timeout.md#timeout-1) signal and used to start the timer immediately. | --- ### Timer ```cpp Timer(std::int64_t timeout, std::int64_t interval, uv::Loop * loop = uv::defaultLoop(), std::function< void()> func = nullptr) ``` [Defined in src/base/include/icy/timer.h:57](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L57) Create a repeating timer with an initial delay and a repeat period. Fires once after `timeout` milliseconds, then repeatedly every `interval` milliseconds. If `func` is provided the timer starts immediately; otherwise call [`start()`](#start-12) manually. #### Parameters | Parameter | Type | Description | |-----------|------|-------------| | `timeout` | `std::int64_t` | Initial delay in milliseconds. | | `interval` | `std::int64_t` | Repeat period in milliseconds. | | `loop` | [`uv::Loop`](https://auscaster.com/icey/docs/api-reference/uv.md#loop-1) * | Event loop to associate with. | | `func` | `std::function< void()>` | Optional callback connected to the [`Timeout`](https://auscaster.com/icey/docs/api-reference/icy-Timeout.md#timeout-1) signal and used to start the timer immediately. | --- ### ~Timer `virtual` ```cpp virtual ~Timer() ``` [Defined in src/base/include/icy/timer.h:60](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L60) Destructor. --- ### start ```cpp void start() ``` [Defined in src/base/include/icy/timer.h:67](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L67) Start the timer using the previously configured timeout and interval. Throws `std::logic_error` if neither a timeout nor an interval has been set, or if the handle has not been allocated. Has no effect if already active. --- ### start `virtual` `override` ```cpp virtual void start(std::function< void()> func) override ``` [Defined in src/base/include/icy/timer.h:72](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L72) Connect `func` to the [`Timeout`](https://auscaster.com/icey/docs/api-reference/icy-Timeout.md#timeout-1) signal and start the timer. #### 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 each timeout event. | --- ### stop ```cpp void stop() ``` [Defined in src/base/include/icy/timer.h:77](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L77) Stop the timer. Resets the fire count to zero. Has no effect if the timer is not active. --- ### restart ```cpp void restart() ``` [Defined in src/base/include/icy/timer.h:85](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L85) Restart the timer. If the timer is not currently active, behaves like [`start()`](#start-12). If it is active, calls [`again()`](#again) to reset the countdown using the repeat value. A timeout or interval must be set beforehand, otherwise [`start()`](#start-12) will throw `std::logic_error`. --- ### again ```cpp void again() ``` [Defined in src/base/include/icy/timer.h:93](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L93) Reset the countdown without stopping and restarting the timer. For repeating timers this restarts the repeat interval from now. For non-repeating timers this has the same effect as stopping the timer. Throws on error if `uv_timer_again` fails (e.g. the timer was never started). Resets the fire count to zero. --- ### setTimeout ```cpp void setTimeout(std::int64_t timeout) ``` [Defined in src/base/include/icy/timer.h:100](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L100) Set the initial delay before the first timeout event. Has no effect if the timer is currently active. #### Parameters | Parameter | Type | Description | |-----------|------|-------------| | `timeout` | `std::int64_t` | Delay in milliseconds. | --- ### setInterval ```cpp void setInterval(std::int64_t interval) ``` [Defined in src/base/include/icy/timer.h:109](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L109) Set the repeat interval (calls `uv_timer_set_repeat`). Takes effect from the next timeout event. If set from within a timer callback on a repeating timer, the new value is used from the following iteration; on a non-repeating timer the timer will have already stopped. #### Parameters | Parameter | Type | Description | |-----------|------|-------------| | `interval` | `std::int64_t` | Repeat period in milliseconds; 0 disables repeating. | --- ### active `const` ```cpp bool active() const ``` [Defined in src/base/include/icy/timer.h:112](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L112) #### Returns `true` if the timer is currently counting down. --- ### timeout `const` ```cpp std::int64_t timeout() const ``` [Defined in src/base/include/icy/timer.h:115](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L115) #### Returns The configured initial timeout in milliseconds. --- ### interval `const` ```cpp std::int64_t interval() const ``` [Defined in src/base/include/icy/timer.h:118](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L118) #### Returns The effective repeat interval reported by libuv, in milliseconds. --- ### count ```cpp std::int64_t count() ``` [Defined in src/base/include/icy/timer.h:121](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L121) #### Returns The number of times the timer has fired since the last start or [again()](#again). --- ### handle ```cpp uv::Handle< uv_timer_t > & handle() ``` [Defined in src/base/include/icy/timer.h:124](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L124) #### Returns Reference to the underlying `uv_timer_t` handle wrapper. --- ### async `virtual` `const` `override` ```cpp virtual bool async() const override ``` [Defined in src/base/include/icy/timer.h:127](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L127) #### Returns `false`; the timer is event-loop-driven, not thread-based. #### Reimplements - [`Runner::async`](https://auscaster.com/icey/docs/api-reference/icy-Runner.md#async-1) ## Protected Attributes | Return | Name | Description | |--------|------|-------------| | [`uv::Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6)< uv_timer_t > | [`_handle`](#_handle-3) | | | `std::int64_t` | [`_timeout`](#_timeout-1) | | | `std::int64_t` | [`_interval`](#_interval) | | | `std::int64_t` | [`_count`](#_count) | | --- ### _handle ```cpp uv::Handle< uv_timer_t > _handle ``` Type: [`uv::Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6)< uv_timer_t > [Defined in src/base/include/icy/timer.h:140](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L140) --- ### _timeout ```cpp std::int64_t _timeout ``` [Defined in src/base/include/icy/timer.h:141](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L141) --- ### _interval ```cpp std::int64_t _interval ``` [Defined in src/base/include/icy/timer.h:142](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L142) --- ### _count ```cpp std::int64_t _count ``` [Defined in src/base/include/icy/timer.h:143](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L143) ## Protected Methods | Return | Name | Description | |--------|------|-------------| | | [`Timer`](#timer-5) | Deleted constructor. | | [`Timer`](#timer) & | [`operator=`](#operator-106) | Deleted assignment operator. | | | [`Timer`](#timer-6) | Deleted constructor. | | [`Timer`](#timer) & | [`operator=`](#operator-107) | Deleted assignment operator. | | `void` | [`init`](#init-5) | | --- ### Timer ```cpp Timer(const Timer &) = delete ``` [Defined in src/base/include/icy/timer.h:133](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L133) Deleted constructor. --- ### operator= ```cpp Timer & operator=(const Timer &) = delete ``` [Defined in src/base/include/icy/timer.h:134](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L134) Deleted assignment operator. --- ### Timer ```cpp Timer(Timer &&) = delete ``` [Defined in src/base/include/icy/timer.h:135](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L135) Deleted constructor. --- ### operator= ```cpp Timer & operator=(Timer &&) = delete ``` [Defined in src/base/include/icy/timer.h:136](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L136) Deleted assignment operator. --- ### init ```cpp void init() ``` [Defined in src/base/include/icy/timer.h:138](https://github.com/auscaster/icey/blob/main/src/base/include/icy/timer.h#L138)