Wrapper around an eventfd FileDescriptor. More...

#include <EventFile.hxx>

Inheritance diagram for cosmos::EventFile:

Public Types
enum class	Counter : uint64_t
	Strong counter type used with the event fd. More...

enum class	Flag : int { CLOSE_ON_EXEC = EFD_CLOEXEC , NONBLOCK = EFD_NONBLOCK , SEMAPHORE = EFD_SEMAPHORE }

using	Flags = BitMask<Flag>

Public Member Functions
	EventFile (const Counter initval=Counter{0}, const Flags flags=Flags{Flag::CLOSE_ON_EXEC})

Counter	wait ()
	Wait for the counter to become non-zero.

void	signal (const Counter increment=Counter{1})
	Signal the eventfd by adding the given value to the counter.

void	close () override
	Close the current file object.

FileDescriptor	fd () const
	Allows access to the underlying fd with const semantics.

bool	isOpen () const
	Returns whether currently a FileDescriptor is opened.

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.

void	close () override
	Close the current file object.

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

Wrapper around an eventfd FileDescriptor.

An eventfd is a lightweight event object using file descriptor representation. An unsigned 8 byte counter is associated with the eventfd that controls the event operation.

This type manages creation and the lifetime of the underlying file descriptor and provides an I/O API tailored towards the special event file semantics.

The event semantics are as follows:

if the counter is zero any wait() on it will block until the counter is increment by another thread.
upon return from wait() regular eventfd semantics cause the current counter value to be returned and the counter is reset to zero.
with semaphore semantics (
See also
Flag::SEMAPHORE) upon return from wait() the value 1 is returned and the counter is decremented by one.
the signal() function adds a value to the counter, thereby potentially waking up any current waiters.

If the counter would overflow due to signal() then the signal() call either blocks until the counter is decremented by another thread or it returns an error if the eventfd is in non-blocking mode (

See also: Flag::NONBLOCK).

Since this is a regular file descriptor the Poller facility can be used to wait for the file descriptor to become readable of writable. Reading corresponds to wait() and writing corresponds to signal().

Definition at line 41 of file EventFile.hxx.

Member Typedef Documentation

◆ Flags

using cosmos::EventFile::Flags = BitMask<Flag>

Definition at line 54 of file EventFile.hxx.

Member Enumeration Documentation

◆ Counter

enum class cosmos::EventFile::Counter : uint64_t

strong

Strong counter type used with the event fd.

Definition at line 46 of file EventFile.hxx.

46: uint64_t {};

◆ Flag

enum class cosmos::EventFile::Flag : int

strong

Enumerator
CLOSE_ON_EXEC	Create the eventfd with the close-on-exec flag set.
NONBLOCK	Sets the nonblocking flag upon creation, saving a separate fcntl() call.
SEMAPHORE	Use semaphore like semantics.

Definition at line 48 of file EventFile.hxx.

                        : int {
                CLOSE_ON_EXEC = EFD_CLOEXEC,  
                NONBLOCK      = EFD_NONBLOCK, 
                SEMAPHORE     = EFD_SEMAPHORE 
        };

Constructor & Destructor Documentation

◆ EventFile()

cosmos::EventFile::EventFile	(	const Counter	initval = Counter{0},
		const Flags	flags = Flags{Flag::CLOSE_ON_EXEC} )

explicit

Definition at line 9 of file EventFile.cxx.

                                                             {
        auto fd = ::eventfd(to_integral(initval), flags.raw());
 
        if (fd == -1) {
                cosmos_throw (ApiError("eventfd()"));
        }
 
        this->open(FileDescriptor{FileNum{fd}}, AutoCloseFD{true});
}

Member Function Documentation

◆ close()

void cosmos::FDFile::close ( )

inlineoverridevirtual

Close the current file object.

If currently no file is open then this does nothing. If currently an external FileDescriptor is wrapped and auto-close is not set then only the object's state will be invalidated. Otherwise the referenced file descriptor will also be closed on OS-level.

Reimplemented from cosmos::FileBase.

Definition at line 62 of file FDFile.hxx.

                              {
 
                if (!m_auto_close) {
                        m_fd.reset();
                        m_auto_close = AutoCloseFD{true};
                        return;
                }
 
                FileBase::close();
        }

◆ fd()

FileDescriptor cosmos::FileBase::fd ( ) const

inline

Allows access to the underlying fd with const semantics.

Definition at line 74 of file FileBase.hxx.

74{ return m_fd; }

◆ isOpen()

bool cosmos::FileBase::isOpen ( ) const

inline

Returns whether currently a FileDescriptor is opened.

Definition at line 71 of file FileBase.hxx.

71{ return m_fd.valid(); }

cosmos::FileDescriptor::valid

bool valid() const

Returns whether currently a valid file descriptor number is assigned.

Definition FileDescriptor.hxx:195

◆ signal()

void cosmos::EventFile::signal ( const Counter increment = Counter{1} )

Signal the eventfd by adding the given value to the counter.

This will wake up a potential thread currently blocked in wait(). If an increment larger than 1 is used then either a larger counter value is returned in wait(), or multiple threads can be waked if Flag::SEMAPHORE is active.

Definition at line 32 of file EventFile.cxx.

                                              {
        const auto bytes = this->write(&increment, sizeof(increment));
 
        if (bytes != sizeof(increment)) {
                cosmos_throw (RuntimeError("short eventfd write?!"));
        }
}

◆ wait()

EventFile::Counter cosmos::EventFile::wait ( )

Wait for the counter to become non-zero.

This potentially blocks until the counter associated with the eventfd becomes non-zero. Then the current counter value will be returned and the counter will be reset to zero.

If Flag::SEMAPHORE is active then only the value of one will be returned and the counter will be decremented by one.

If Flag::NONBLOCK is active then no blocking occurs but an error is thrown if the counter is currently zero.

Definition at line 19 of file EventFile.cxx.

                                 {
        Counter ret;
        // I don't believe short reads are possible with eventfds, so use
        // regular read() instead of readAll().
        const auto bytes = this->read(&ret, sizeof(Counter));
 
        if (bytes != sizeof(ret)) {
                cosmos_throw (RuntimeError("short eventfd read?!"));
        }
 
        return ret;
}

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

include/io/EventFile.hxx
src/io/EventFile.cxx

Public Types

Public Member Functions

Additional Inherited Members