cosmos::TimerFD< CLOCK > Class Template Reference

Timers that notify via file descriptors. More...

#include <TimerFD.hxx>

Inheritance diagram for cosmos::TimerFD< CLOCK >:

Classes
struct	CreateT
	Helper type for construction of a ready-to-use TimerFD with default CreateFlags. More...
struct	TimerSpec
	Combined start time and repeat interval for a TimerFD setting. More...

Public Types
enum class	CreateFlag : int { NONBLOCK = TFD_NONBLOCK , CLOEXEC = TFD_CLOEXEC }
	Flags provided at TimerFD creation time. More...
enum class	StartFlag : int { ABSTIME = TFD_TIMER_ABSTIME , CANCEL_ON_SET = TFD_TIMER_CANCEL_ON_SET }
	Flags available for starting a TimerFD. More...
using	CreateFlags = BitMask<CreateFlag>
using	StartFlags = BitMask<StartFlag>

Public Member Functions
	TimerFD ()=default
	Creates an empty (invalid) timer fd.
	TimerFD (const CreateFlags flags)
	Creates a timer fd with the given flags ready for operation.
	TimerFD (const CreateT)
	Creates a timer fd with default flags ready for operation.
	TimerFD (TimerFD &&other) noexcept
TimerFD &	operator= (TimerFD &&other) noexcept
void	create (const CreateFlags flags=CreateFlags{CreateFlag::CLOEXEC})
	Creates a new timer fd using the given flags.
void	close () override
	Closes the timer fd.
void	setTime (const TimerSpec spec, const StartFlags flags=StartFlags{})
	Arm the timer using the given settings and flags.
TimerSpec	getTime () const
	Returns the current timer settings from the kernel.
uint64_t	wait ()
	Waits on the timer returning the tick count.
void	disarm ()
	Disarms any active timer settings, no more ticks will occur.
FileDescriptor	fd () const
	Allows access to the underlying fd with const semantics.
bool	isOpen () const
	Returns whether currently a FileDescriptor is opened.

Static Public Attributes
static CreateT	defaults

Additional Inherited Members
Protected Types inherited from cosmos::StreamIO
enum class	SeekType : int {   SET = SEEK_SET , CUR = SEEK_CUR , END = SEEK_END , DATA = SEEK_DATA ,   HOLE = SEEK_HOLE }
	Different methods for changing the file read/write position. More...
Protected Member Functions inherited from cosmos::FDFile
	FDFile (const FileDescriptor fd, const AutoCloseFD auto_close)
	Wrap the given file descriptor applying the specified auto-close behaviour.
	FDFile (FDFile &&other) noexcept
FDFile &	operator= (FDFile &&other) noexcept
void	open (const FileDescriptor fd, const AutoCloseFD auto_close)
	Takes the already open file descriptor fd and operates on it.
Protected Member Functions inherited from cosmos::FileBase
	FileBase (const FileDescriptor fd=FileDescriptor{})
	FileBase (FileBase &&other) noexcept
FileBase &	operator= (FileBase &&other) noexcept
	FileBase (const FileBase &)=delete
FileBase &	operator= (const FileBase &)=delete
bool	isOpen () const
	Returns whether currently a FileDescriptor is opened.
FileDescriptor	fd () const
	Allows access to the underlying fd with const semantics.
void	truncate (const off_t length)
Protected Member Functions inherited from cosmos::StreamIO
	StreamIO (FileDescriptor &fd)
	StreamIO (const StreamIO &)=delete
StreamIO &	operator= (const StreamIO &)=delete
StreamIO &	operator= (StreamIO &&) noexcept
size_t	read (void *buf, size_t length)
	Read up to length bytes from the file into buf.
size_t	write (const void *buf, size_t length)
	Write up to length bytes from buf into the underlying file.
size_t	write (const std::string_view data)
	string_view wrapper around write(const void*, size_t).
void	readAll (void *buf, size_t length)
	Read all length bytes from the underlying file.
void	readAll (std::string &s, size_t length)
	Like readAll(void*, size_t) using an STL string.
void	writeAll (const void *buf, size_t length)
	Write all length bytes into the underlying file.
void	writeAll (const std::string_view data)
	string_view wrapper around writeAll(const void*, size_t).
bool	read (ReadIOVector &iovec)
	Read data from file into a vector of data regions.
bool	write (WriteIOVector &iovec)
	Write data to file from a vector of data regions.
void	readAll (ReadIOVector &iovec)
	Read into all data regions specified in iovec.
void	writeAll (WriteIOVector &iovec)
	Write all data regions specified in iovec.
off_t	seek (const SeekType type, off_t off)
	Seek to the given offset based on the given offset type.
off_t	seekFromStart (off_t off)
	Seek to the given offset relative to the start of the file.
off_t	seekFromCurrent (off_t off)
	Seek to the given offset relative to the current file position.
off_t	seekFromEnd (off_t off)
	Seek to the given offset relative to the end of the file.
Protected Attributes inherited from cosmos::FDFile
AutoCloseFD	m_auto_close
Protected Attributes inherited from cosmos::FileBase
FileDescriptor	m_fd
Protected Attributes inherited from cosmos::StreamIO
FileDescriptor &	m_stream_fd

Detailed Description

template<ClockType CLOCK>
class cosmos::TimerFD< CLOCK >

Timers that notify via file descriptors.

A TimerFD is associated with an 8 byte integer (uint64_t) that is increased upon each timer tick, until somebody read()s it. The file descriptor can be used for polling it together with other file descriptors. It will be readable once at least one timer event is available.

Currently TimerFDs only work with few clock types: RealTimeClock, MonotonicClock and BootTimeClock. Two special _ALARM clock types are currently not implemented in libcosmos which would cause a system to wake up from suspend when triggered.

A TimerFD is inherited across fork() as a copy and preserved across execve() depending on the CLOEXEC creation/file descriptor flag.

A TimerFD is a move-only type that cannot be copied due to the file descriptor ownership.

A TimerFD is strongly coupled to the template CLOCK type as most of the other time classes are. This is to avoid mixing absolute time values from different clocks.

Definition at line 36 of file TimerFD.hxx.

Member Typedef Documentation

CreateFlags

template<ClockType CLOCK>

using cosmos::TimerFD< CLOCK >::CreateFlags = BitMask<CreateFlag>

Definition at line 51 of file TimerFD.hxx.

StartFlags

template<ClockType CLOCK>

using cosmos::TimerFD< CLOCK >::StartFlags = BitMask<StartFlag>

Definition at line 61 of file TimerFD.hxx.

Member Enumeration Documentation

CreateFlag

template<ClockType CLOCK>

enum class cosmos::TimerFD::CreateFlag : int

strong

Flags provided at TimerFD creation time.

Enumerator
NONBLOCK	Create a non-blocking file descriptor.
CLOEXEC	Sets the close-on-exec flag upon creation.

Definition at line 44 of file TimerFD.hxx.

                              : int {
                NONBLOCK = TFD_NONBLOCK,
                CLOEXEC  = TFD_CLOEXEC
        };

StartFlag

template<ClockType CLOCK>

enum class cosmos::TimerFD::StartFlag : int

strong

Flags available for starting a TimerFD.

Enumerator
ABSTIME	Interpret the initial (not the interval!) timer setting as an absolute clock time value.
CANCEL_ON_SET	For RealTime based clocks report discontinous clock changes via Errno::CANCELED.

Definition at line 54 of file TimerFD.hxx.

                             : int {
                ABSTIME       = TFD_TIMER_ABSTIME,
                CANCEL_ON_SET = TFD_TIMER_CANCEL_ON_SET
        };

Constructor & Destructor Documentation

TimerFD() [1/3]

template<ClockType CLOCK>

cosmos::TimerFD< CLOCK >::TimerFD ( const CreateFlags flags )

inlineexplicit

Creates a timer fd with the given flags ready for operation.

Definition at line 127 of file TimerFD.hxx.

                                                  {
                create(flags);
        }

TimerFD() [2/3]

template<ClockType CLOCK>

cosmos::TimerFD< CLOCK >::TimerFD ( const CreateT )

inlineexplicit

Creates a timer fd with default flags ready for operation.

Default flags most notably include the CLOEXEC creation flag.

Definition at line 135 of file TimerFD.hxx.

                                        {
                create();
        }

TimerFD() [3/3]

template<ClockType CLOCK>

cosmos::TimerFD< CLOCK >::TimerFD ( TimerFD< CLOCK > && other )

inlinenoexcept

Definition at line 139 of file TimerFD.hxx.

                                          {
                *this = std::move(other);
        }

Member Function Documentation

close()

template<ClockType CLOCK>

void cosmos::TimerFD< CLOCK >::close ( )

inlineoverridevirtual

Closes the timer fd.

The file descriptor will be closed and any timers associated with it will be disarmed, resources freed. When further copies of the file descriptor exist (dup'ed) then this will only happen after all copies are closed.

If isOpen() returns false then close() returns without doing anything.

Reimplemented from cosmos::FDFile.

Definition at line 176 of file TimerFD.hxx.

                              {
                FDFile::close();
        }

create()

template<ClockType CLOCK>

void cosmos::TimerFD< CLOCK >::create

(

const CreateFlags

flags = CreateFlags{CreateFlag::CLOEXEC}

)

Creates a new timer fd using the given flags.

After this function call the timer will be ready for operation.

If there already is a valid timer fd (i.e. isOpen() == true) then close() will be called first.

This call can cause an ApiError to be thrown e.g. if the maximum file descriptor limit has been reached, memory is exhausted, clock or flags are invalid or permission is denied (for the special _ALARM clocks).

Definition at line 13 of file TimerFD.cxx.

                                                          {
        close();
 
        if (auto fd = timerfd_create(to_integral(CLOCK), flags.raw()); FileNum{fd} != FileNum::INVALID) {
                this->open(FileDescriptor{FileNum{fd}}, AutoCloseFD{true});
                return;
        }
 
        cosmos_throw (ApiError("timerfd_create()"));
}

disarm()

template<ClockType CLOCK>

void cosmos::TimerFD< CLOCK >::disarm ( )

inline

Disarms any active timer settings, no more ticks will occur.

Any already registered ticks will be reset, a future wait() will block forever unless the timer is armed again via setTime(). This behaviour is not clearly documented in the man page though.

Definition at line 225 of file TimerFD.hxx.

                      {
                setTime(TimerSpec{});
        }

fd()

template<ClockType CLOCK>

FileDescriptor cosmos::FileBase::fd ( ) const

inline

Allows access to the underlying fd with const semantics.

Definition at line 74 of file FileBase.hxx.

{ return m_fd; }

getTime()

template<ClockType CLOCK>

TimerFD< CLOCK >::TimerSpec cosmos::TimerFD< CLOCK >::getTime

(

)

const

Returns the current timer settings from the kernel.

Note that this function always returns a relative timer in TimerSpec.initial(), even if StartFlag::ABSTIME was used to set it.

If the timer is currently disarmed then all zero values are returned.

Definition at line 25 of file TimerFD.cxx.

                                                               {
        TimerSpec ret;
 
        if (auto res = timerfd_gettime(to_integral(m_fd.raw()), &ret); res != 0) {
                cosmos_throw (ApiError("timerfd_gettime()"));
        }
 
        return ret;
}

isOpen()

template<ClockType CLOCK>

bool cosmos::FileBase::isOpen ( ) const

inline

Returns whether currently a FileDescriptor is opened.

Definition at line 71 of file FileBase.hxx.

{ return m_fd.valid(); }

operator=()

template<ClockType CLOCK>

TimerFD & cosmos::TimerFD< CLOCK >::operator= ( TimerFD< CLOCK > && other )

inlinenoexcept

Definition at line 143 of file TimerFD.hxx.

                                                     {
                static_cast<FDFile&>(*this) = std::move(other);
                return *this;
        }

setTime()

template<ClockType CLOCK>

void cosmos::TimerFD< CLOCK >::setTime	(	const TimerSpec	spec,
		const StartFlags	flags = StartFlags{} )

Arm the timer using the given settings and flags.

See TimerSpec for more information on the initial and interval values. If spec.initial() is non-zero then the timer will be armed and produce at least one tick event at the given time.

Definition at line 36 of file TimerFD.cxx.

                                                                         {
        if (timerfd_settime(
                                to_integral(m_fd.raw()),
                                flags.raw(),
                                &spec,
                                nullptr) == 0) {
                return;
        }
 
        cosmos_throw (ApiError("timerfd_settime()"));
}

wait()

template<ClockType CLOCK>

uint64_t cosmos::TimerFD< CLOCK >::wait

(

)

Waits on the timer returning the tick count.

This operation will read() on the associated timer fd.

If no timer tick occurred yet then this will block the caller until a timer tick or an error occurs (e.g. ApiError with Errno::CANCELED, if StartFlag::CANCEL_ON_SET is active).

If one or more timer ticks already occurred then this call will not block and returns the number of ticks that happened.

If NONBLOCK mode was specified during creation and no timer tick occurred yet then this will throw a WouldBlock exception.

On successful return the tick count associated with the timer will be reset to zero, so a subsequent wait() can block again until a new tick event occurs.

Definition at line 49 of file TimerFD.cxx.

                              {
        uint64_t ret;
 
        const auto bytes = this->read(reinterpret_cast<void*>(&ret), sizeof(ret));
 
        // from the man page I deduce that short reads should not be possible
        // (reads with less than 8 bytes return EINVAL)
        if (bytes != sizeof(ret)) {
                cosmos_throw (RuntimeError("Short read on timer fd"));
        }
 
        return ret;
}

Member Data Documentation

defaults

template<ClockType CLOCK>

CreateT cosmos::TimerFD< CLOCK >::defaults

static

Definition at line 119 of file TimerFD.hxx.

---

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

• include/time/TimerFD.hxx
• src/time/TimerFD.cxx