1.2
Classes | Public Types | Public Member Functions | Protected Types | Protected Member Functions | Protected Attributes | List of all members
Timer Class Reference

Basic one shot timer. More...

Inheritance diagram for Timer:
Inheritance graph
[legend]

Public Types

using RegisterHandle = uint64_t
 Handle type. More...
 
using TimerCallback = std::function< void()>
 Timer callback function definition. More...
 

Public Member Functions

 Timer () noexcept
 Construct a one-shot timer. More...
 
 Timer (const Timer &)=delete
 
 Timer (std::chrono::milliseconds duration) noexcept
 Construct a one-shot timer with the specified duration. More...
 
 Timer (Timer &&)
 
virtual ~Timer () noexcept
 
void cancel ()
 Cancel, or stop, the timer. More...
 
void change_duration (std::chrono::milliseconds duration)
 Change the duration of the timer. More...
 
void clear_handlers ()
 Clear all handlers. More...
 
EGT_NODISCARD std::chrono::milliseconds duration () const
 Return the current duration of the timer. More...
 
EGT_NODISCARD const std::string & name () const
 Get the name of the Timer. More...
 
void name (const std::string &name)
 Set the name of the Timer. More...
 
RegisterHandle on_timeout (TimerCallback callback)
 Add a handler callback to be called with the timer times out. More...
 
Timeroperator= (const Timer &)=delete
 
Timeroperator= (Timer &&)
 
void remove_handler (RegisterHandle handle)
 Remove an event handler. More...
 
EGT_NODISCARD bool running () const
 Returns true if the timer is currently running. More...
 
virtual void start ()
 Start the timer. More...
 
void start (std::chrono::milliseconds duration)
 Start the timer with the specified duration. More...
 
EGT_DEPRECATED void start_with_duration (std::chrono::milliseconds duration)
 Start the timer with the specified duration. More...
 
void stop ()
 Alias for cancel(). More...
 
void timeout ()
 Called when the timer times out. More...
 

Protected Types

using CallbackArray = std::vector< CallbackMeta >
 Type for array of registered callbacks. More...
 

Protected Member Functions

void invoke_handlers ()
 Invoke any registered handlers. More...
 

Protected Attributes

CallbackArray m_callbacks
 Array of registered callbacks. More...
 
std::chrono::milliseconds m_duration {}
 The duration of the timer. More...
 
RegisterHandle m_handle_counter {0}
 Counter used to generate unique handles for each callback registration. More...
 
std::unique_ptr< TimerImpl > m_impl
 
std::string m_name
 A user defined name for the Timer. More...
 
bool m_running {false}
 When true, currently running. More...
 
asio::steady_timer m_timer
 Asio timer object. More...
 

Detailed Description

Basic one shot timer.

This is a timer that will fire once after the specified duration. To handle the timeout, call on_timeout with a callback.

There are two main use cases for this class. One, is you can derive from this class and overload the Timer::timeout() member function.

struct MyTimer : public Timer
{
MyTimer()
: Timer(std::chrono::milliseconds(100))
{}
void timeout() override
{
...
}
};
MyTimer timer;
timer.start();
Timer() noexcept
Construct a one-shot timer.
void timeout()
Called when the timer times out.

The other way is to create an instance of this class and connect a handler by calling Timer::on_timeout().

Timer timer(std::chrono::milliseconds(100));
timer.on_timeout([]() {
...
});
timer.start();
See also
PeriodicTimer

Member Typedef Documentation

◆ CallbackArray

using CallbackArray = std::vector<CallbackMeta>
protected

Type for array of registered callbacks.

◆ RegisterHandle

using RegisterHandle = uint64_t

Handle type.

◆ TimerCallback

using TimerCallback = std::function<void()>

Timer callback function definition.

Constructor & Destructor Documentation

◆ Timer() [1/4]

Timer ( )
noexcept

Construct a one-shot timer.

The duration of the timer can be specified when calling start_with_duration() when using this constructor.

◆ Timer() [2/4]

Timer ( std::chrono::milliseconds  duration)
explicitnoexcept

Construct a one-shot timer with the specified duration.

◆ Timer() [3/4]

Timer ( const Timer )
delete

◆ Timer() [4/4]

Timer ( Timer &&  )

◆ ~Timer()

virtual ~Timer ( )
virtualnoexcept

Member Function Documentation

◆ cancel()

void cancel ( )

Cancel, or stop, the timer.

◆ change_duration()

void change_duration ( std::chrono::milliseconds  duration)

Change the duration of the timer.

This will stop the timer, change the duration, and restart the timer with the new duration if the timer was already running.

◆ clear_handlers()

void clear_handlers ( )

Clear all handlers.

◆ duration()

EGT_NODISCARD std::chrono::milliseconds duration ( ) const
inline

Return the current duration of the timer.

◆ invoke_handlers()

void invoke_handlers ( )
protected

Invoke any registered handlers.

◆ name() [1/2]

EGT_NODISCARD const std::string& name ( ) const
inline

Get the name of the Timer.

◆ name() [2/2]

void name ( const std::string &  name)
inline

Set the name of the Timer.

Assigns a human readable name to a Timer that can then be used to find timers by name or debug.

Parameters
[in]nameName to set for the Object.

◆ on_timeout()

RegisterHandle on_timeout ( TimerCallback  callback)

Add a handler callback to be called with the timer times out.

This function can be called any number of times to add handlers.

Parameters
callbackThe callback to invoke on event.
Returns
A handle used to identify the registration. This can then be passed to remove_handler().

◆ operator=() [1/2]

Timer& operator= ( const Timer )
delete

◆ operator=() [2/2]

Timer& operator= ( Timer &&  )

◆ remove_handler()

void remove_handler ( RegisterHandle  handle)

Remove an event handler.

Parameters
handleThe handle returned from on_timeout().

◆ running()

EGT_NODISCARD bool running ( ) const
inline

Returns true if the timer is currently running.

◆ start() [1/2]

virtual void start ( )
virtual

Start the timer.

It is safe to call start() on an already running timer. It will simply reset and start again.

Note
Assumes a duration is set already.

Reimplemented in PeriodicTimer, PeriodicTimer, and PeriodicTimer.

◆ start() [2/2]

void start ( std::chrono::milliseconds  duration)
inline

Start the timer with the specified duration.

This overwrites any duration specified previously.

◆ start_with_duration()

EGT_DEPRECATED void start_with_duration ( std::chrono::milliseconds  duration)

Start the timer with the specified duration.

This overwrites any duration specified previously.

Deprecated:

◆ stop()

void stop ( )
inline

Alias for cancel().

◆ timeout()

void timeout ( )

Called when the timer times out.

This will invoke any callback registered with add_handler(). If you override this you must make sure to call Timer::timeout() or equivalent if you want callbacks to still be called.

Member Data Documentation

◆ m_callbacks

CallbackArray m_callbacks
protected

Array of registered callbacks.

◆ m_duration

std::chrono::milliseconds m_duration {}
protected

The duration of the timer.

◆ m_handle_counter

RegisterHandle m_handle_counter {0}
protected

Counter used to generate unique handles for each callback registration.

◆ m_impl

std::unique_ptr<TimerImpl> m_impl
protected

◆ m_name

std::string m_name
protected

A user defined name for the Timer.

◆ m_running

bool m_running {false}
protected

When true, currently running.

◆ m_timer

asio::steady_timer m_timer
protected

Asio timer object.