ne::Timer Class Reference

#include <Timer.h>

Public Member Functions
	Timer (const Timer &)=delete
Timer &	operator= (const Timer &)=delete
void	setCallbackForTimeout (long long iTimeToWaitInMs, const std::function< void()> &callback, bool bIsLooping=false)
void	start ()
void	stop (bool bDisableTimer=false)
std::optional< long long >	getElapsedTimeInMs ()
std::string	getName () const
size_t	getStartCount ()
bool	isRunning ()
bool	isStopped ()
bool	isEnabled ()

Protected Member Functions
	Timer (const std::string &sTimerName)
void	setCallbackValidator (const std::function< bool(size_t)> &validator)
void	setEnable (bool bEnable)

Private Member Functions
void	timerThread (std::chrono::milliseconds timeToWaitInMs)

Private Attributes
std::optional< std::future< void > >	timerThreadFuture
std::optional< std::function< void()> >	callbackForTimeout
std::optional< std::function< bool(size_t)> >	callbackValidator
std::string	sTimerName
std::pair< std::mutex, std::optional< std::chrono::steady_clock::time_point > >	mtxTimeWhenStarted
size_t	iStartCount = 0
std::mutex	mtxTerminateTimerThread
std::condition_variable	cvTerminateTimerThread
std::atomic_flag	bIsShuttingDown {}
std::atomic_flag	bIsStopRequested {}
std::optional< long long >	elapsedTimeWhenStopped
long long	iTimeToWaitInMs = 0
bool	bIsRunning = false
bool	bIsEnabled = true
bool	bIsLooping = false

Friends
class	Node
class	GameInstance

Detailed Description

Simple timer that can trigger a callback function on a timeout.

Constructor & Destructor Documentation

Timer()

ne::Timer::Timer ( const std::string &  sTimerName )

protected

Constructor.

Parameters

sTimerName

Name of this timer (used for logging). Don't add "timer" word to your timer's name as it will be appended in the logs.

Member Function Documentation

getElapsedTimeInMs()

std::optional< long long > ne::Timer::getElapsedTimeInMs

(

)

Returns the time that has passed since the timer was started (see start).

Returns

Empty if the start was never called before, otherwise time in milliseconds since the timer was started.

Remarks

For looping timers (see start) returns time since the beginning of the current loop iteration. Each new loop will reset elapsed time to 0.

Note that if you call this function right after the call to start with a callback function set (see setCallbackForTimeout) this function may return empty because the timer thread is not started yet.

getName()

std::string ne::Timer::getName

(

)

const

Returns timer's name (only used for logging purposes).

Returns

Timer's name.

getStartCount()

size_t ne::Timer::getStartCount

(

)

Returns the amount of times start was called.

Returns

start call count.

isEnabled()

bool ne::Timer::isEnabled

(

)

Whether this timer can use start function or not.

Returns

true if start can be called, false otherwise.

isRunning()

bool ne::Timer::isRunning

(

)

Whether this timer is running (started) or not (finished/not started).

Returns

true if currently running, false otherwise.

isStopped()

bool ne::Timer::isStopped

(

)

Whether this timer was running (started) and was stopped using stop.

Returns

true if the timer was stopped using stop and is not running right now, false otherwise.

setCallbackForTimeout()

void ne::Timer::setCallbackForTimeout	(	long long	iTimeToWaitInMs,
		const std::function< void()> &	callback,
		bool	bIsLooping = false
	)

Sets a function to be executed when the waiting time is over (timeout event).

Example:

class GrenadeNode : public MeshNode
{
public:
    // ...
 
    void throw(){
        pExplodeTimer->setCallbackForTimeout(3000, [this]() { explode(); });
        pExplodeTimer->start();
    }
private:
    void explode(){
        // ...
    }
 
    Timer* pExplodeTimer = nullptr;
}

Remarks

If the timer is currently running (see isRunning) this call will be ignored and an error will be logged.

Upon a timeout the timer will submit a deferred task with your callback function to the main thread because deferred tasks are executed each frame you might expect a slight delay after the timeout event and before your callback is actually started, the delay should be generally smaller that ~30 ms so it should not make a big difference to you, but note that you probably want to avoid using callback timers for benchmarking or other high precision timing events due to this delay.

Parameters

iTimeToWaitInMs	Time this timer should wait (in milliseconds) until the callback is called.
callback	Function to execute on timeout.
bIsLooping	Whether the timer should start again after a timeout or not. If specified true, after the waiting time is over (timeout) the timer will automatically restart itself and will start the waiting time again.

setCallbackValidator()

void ne::Timer::setCallbackValidator ( const std::function< bool(size_t)> &  validator )

protected

Sets a function to be called from a deferred task before the actual callback to test if the actual callback should be started or not.

Example of typical callback validator:

pTimer->setCallbackValidator([pTimer](size_t iStartCount) -> bool {
    // Timer does not have a validator by default because it does not know whether
    // the timer object will still be alive or not at the moment when the validator is started
    // so it's up to the owner to guarantee that.
 
    if (iStartCount != pTimer->getStartCount()) {
        // The timer was stopped and started (probably with some other callback).
        return false; // don't run the actual callback
    }
 
    return !pTimer->isStopped(); // only run the actual callback if the timer was not stopped
}

Remarks

If the timer is currently running (see isRunning) this call will be ignored and an error will be logged.

Parameters

validator

Validator function. The only parameter is getStartCount at the moment of timeout event. Returns true if the actual callback needs to be started and false if the actual callback should not be started.

setEnable()

void ne::Timer::setEnable ( bool  bEnable )

protected

Determines whether start will work or not.

Parameters

bEnable

true to allow using start, false otherwise.

start()

void ne::Timer::start

(

)

Starts the timer.

Remarks

If you want to add a callback function to be executed on timeout see setCallbackForTimeout.

If the timer is currently running it will be stopped (see stop).

stop()

void ne::Timer::stop

(

bool

bDisableTimer = false

)

Stops the timer and timer looping (if was specified in start).

Remarks

If a callback function was previously specified (see setCallbackForTimeout), the timer was running and the callback function was started it will continue running without stopping. If the timer was running and the callback function was not started yet it will be never started.

Parameters

bDisableTimer

Specify true to make future start calls to be ignored, false to allow restarting the timer.

timerThread()

void ne::Timer::timerThread ( std::chrono::milliseconds  timeToWaitInMs )

private

Timer thread that waits until a timeout or a shutdown.

Parameters

timeToWaitInMs

Time this thread should wait.

Member Data Documentation

bIsEnabled

bool ne::Timer::bIsEnabled = true

private

true if start calls should be allowed (able to restart the timer) or false to ignore calls to start function (won't be able to start the timer).

bIsLooping

bool ne::Timer::bIsLooping = false

private

Whether the timer should restart itself upon a timeout or not.

bIsRunning

bool ne::Timer::bIsRunning = false

private

Whether the timer is currently running or not.

bIsShuttingDown

std::atomic_flag ne::Timer::bIsShuttingDown {}

private

Whether the destructor was called or not.

bIsStopRequested

std::atomic_flag ne::Timer::bIsStopRequested {}

private

Whether the timer was explicitly stopped or not.

callbackForTimeout

std::optional<std::function<void()> > ne::Timer::callbackForTimeout

private

Function to call on timeout.

callbackValidator

std::optional<std::function<bool(size_t)> > ne::Timer::callbackValidator

private

Function to call from a deferred task before callbackForTimeout to test if the callback should be started or not.

cvTerminateTimerThread

std::condition_variable ne::Timer::cvTerminateTimerThread

private

Condition variable for timer thread termination.

elapsedTimeWhenStopped

std::optional<long long> ne::Timer::elapsedTimeWhenStopped

private

getElapsedTimeInMs when stop was called.

iStartCount

size_t ne::Timer::iStartCount = 0

private

The number of times start was called.

iTimeToWaitInMs

long long ne::Timer::iTimeToWaitInMs = 0

private

Time to wait until the callback is called.

mtxTerminateTimerThread

std::mutex ne::Timer::mtxTerminateTimerThread

private

Mutex for read/write operations on data that the timer thread is using.

mtxTimeWhenStarted

std::pair<std::mutex, std::optional<std::chrono::steady_clock::time_point> > ne::Timer::mtxTimeWhenStarted

private

Time when the start was called. Not empty if start was called.

sTimerName

std::string ne::Timer::sTimerName

private

Name of this timer (used for logging).

timerThreadFuture

std::optional<std::future<void> > ne::Timer::timerThreadFuture

private

Future of the waiting thread.

---

The documentation for this class was generated from the following files:

• src/engine_lib/public/misc/Timer.h
• src/engine_lib/private/misc/Timer.cpp