dfx::FdWatch::Timer Class Reference

FD-integrated timer utility (timerfd-backed). More...

#include <dfx-fdwatch/Timer.hpp>

Public Types
enum class	Mode : bool { SingleShot , Repeating }
	Timer firing mode. More...
using	Callback = std::move_only_function<void ()>
	Callback invoked when the timer expires.

Public Member Functions
	Timer ()
	Constructs a detached (inactive) timer.
	Timer (Poller &poller, std::chrono::milliseconds timeout, Callback cb, Mode mode=Mode::SingleShot)
	Constructs and attaches a timer to a poller.
	DFX_PRIVATE_STATE_DECLARE_RULE_OF_5 (Timer)
std::chrono::milliseconds	timeout () const noexcept
	Returns the configured timeout/period.
std::chrono::milliseconds	remainingTime () const
	Returns the remaining time before the next expiration. If the timer is inactive, the returned duration is 0.
Mode	mode () const noexcept
	Returns the current mode.
bool	isSingleShot () const noexcept
	Convenience check for Mode::SingleShot.
bool	isRepeating () const noexcept
	Convenience check for Mode::Repeating.
bool	isActive () const noexcept
	Returns whether the timer is currently armed. A timer is considered active when it is registered in a Poller.
void	attach (Poller &poller, std::chrono::milliseconds timeout, Callback cb, Mode mode=Mode::SingleShot)
	Attaches the timer to a poller and configures it.
void	start ()
	Arms the timer using the currently configured timeout.
void	start (std::chrono::milliseconds timeout)
	Sets a new timeout and arms the timer.
void	stop ()
	Disarms the timer without releasing the underlying FD.
void	close () noexcept
	Closes the underlying timer resources and detaches from the poller.

Detailed Description

FD-integrated timer utility (timerfd-backed).

Timer provides a simple API to schedule a callback after a given timeout. It integrates with Poller by registering an internal timer FD and dispatching the user callback when the timer expires.

A timer can be configured as:

• Mode::SingleShot : fires once and then stops.
• Mode::Repeating : fires periodically until stopped.

A Timer can be default-constructed in a detached state and later configured via attach(). Alternatively, it can be constructed already attached to a poller.

The underlying timer FD is created lazily (implementation detail) and is not closed directly by stop(); either use close() to release the associated kernel resource explicitly or destroy it. It will also be close automatically after 30 seconds if start / attach hasn't been called in between.

Thread-safety is not guaranteed. All operations are expected to be performed from the same thread as the associated Poller event loop.

Note

A timer with a timeout set to 0 is currently not possible and will throw an exception if tried

See also

Poller

Member Typedef Documentation

Callback

using dfx::FdWatch::Timer::Callback = std::move_only_function<void ()>

Callback invoked when the timer expires.

Member Enumeration Documentation

Mode

enum class dfx::FdWatch::Timer::Mode : bool

strong

Timer firing mode.

Enumerator
SingleShot	Fire once, then automatically become inactive.
Repeating	Fire repeatedly at the configured interval until stopped.

Constructor & Destructor Documentation

Timer() [1/2]

dfx::FdWatch::Timer::Timer

(

)

Constructs a detached (inactive) timer.

The timer is not associated with any poller and cannot be started until attach() has been called.

Timer() [2/2]

dfx::FdWatch::Timer::Timer	(	Poller &	poller,
		std::chrono::milliseconds	timeout,
		Callback	cb,
		Mode	mode = Mode::SingleShot )

Constructs and attaches a timer to a poller.

Equivalent to default-constructing and then calling attach().

Parameters

poller	Poller used to monitor the timer FD.
timeout	Initial timeout/period. Must be positive.
cb	Callback invoked upon expiration.
mode	Single-shot or repeating mode.

Member Function Documentation

attach()

void dfx::FdWatch::Timer::attach	(	Poller &	poller,
		std::chrono::milliseconds	timeout,
		Callback	cb,
		Mode	mode = Mode::SingleShot )

Attaches the timer to a poller and configures it.

This sets the poller, timeout, callback, and mode. The timer is not automatically started; call start() after attaching if you want it armed.

Parameters

poller	Poller used to monitor the timer FD.
timeout	Timeout/period to configure. Must be positive.
cb	Callback invoked upon expiration.
mode	Single-shot or repeating mode.

Note

If the timer was previously attached/active, then it will first be deregister from the old poller then attached to the new one.

close()

void dfx::FdWatch::Timer::close ( )

noexcept

Closes the underlying timer resources and detaches from the poller.

After this call, the timer is effectively reset to a detached state and must be attach()'d again before it can be started.

Note

This function is noexcept and should be safe to call multiple times.

isActive()

bool dfx::FdWatch::Timer::isActive ( ) const

noexcept

Returns whether the timer is currently armed. A timer is considered active when it is registered in a Poller.

isRepeating()

bool dfx::FdWatch::Timer::isRepeating ( ) const

noexcept

Convenience check for Mode::Repeating.

isSingleShot()

bool dfx::FdWatch::Timer::isSingleShot ( ) const

noexcept

Convenience check for Mode::SingleShot.

mode()

Mode dfx::FdWatch::Timer::mode ( ) const

noexcept

Returns the current mode.

remainingTime()

std::chrono::milliseconds dfx::FdWatch::Timer::remainingTime

(

)

const

Returns the remaining time before the next expiration. If the timer is inactive, the returned duration is 0.

start() [1/2]

void dfx::FdWatch::Timer::start

(

)

Arms the timer using the currently configured timeout.

Precondition

The timer must be attached to a Poller (via constructor or attach()).

start() [2/2]

void dfx::FdWatch::Timer::start

(

std::chrono::milliseconds

timeout

)

Sets a new timeout and arms the timer.

Parameters

timeout

New timeout/period to use. Must be positive.

Precondition

The timer must be attached to a Poller (via constructor or attach()).

stop()

void dfx::FdWatch::Timer::stop

(

)

Disarms the timer without releasing the underlying FD.

After this call, the timer becomes inactive and will not fire until started again. This does not necessarily close or destroy the internal timer FD; use close() if you want to release kernel resources.

timeout()

std::chrono::milliseconds dfx::FdWatch::Timer::timeout ( ) const

noexcept

Returns the configured timeout/period.

---

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

• lib/dfx-fdwatch/Timer.hpp