cosmos::SignalFD Class Reference

A file descriptor for receiving process signals. More...

#include <SignalFD.hxx>

Classes
class	Info
	SigInfo style data structure returned by SignalFD::readEvent(). More...

Public Member Functions
	SignalFD ()
	Creates an invalid SignalFD object.
	SignalFD (const SigSet &mask)
	Creates a signal FD listening on the given signals.
	SignalFD (const std::initializer_list< Signal > siglist)
	Creates a signal FD listening on the given list of signals.
	SignalFD (const Signal s)
	Creates a signal FD listening on exactly the given signal.
	SignalFD (const SignalFD &)=delete
SignalFD &	operator= (const SignalFD &)=delete
void	create (const SigSet &mask)
	Creates a new SignalFD.
void	close ()
auto	valid () const
void	adjustMask (const SigSet &mask)
	Change the signals the file descriptor is listening for.
void	readEvent (Info &info)
	Reads the next event event from the SignalFD.
auto	fd ()
	Returns the FileDescriptor object associated with the SignalFD.

Protected Attributes
FileDescriptor	m_fd

Detailed Description

A file descriptor for receiving process signals.

A SignalFD is used for handling process signals on file descriptor level. During creation of the file descriptor the signals that the caller is interested in are declared. Once one of these signals is sent to the process, the file descriptor will become readable and returns the SignalFD::SigInfo data structure describing the event.

As usual with signal handling you need to block the signals that you want to handle synchronously via a SignalFD by calling cosmos::signal::block(). Use the readEvent() member function to comfortably receive the signal information. The underlying file descriptor can be used with common file descriptor monitoring interfaces like Poller.

The SignalFD mirrors the behaviour of other ways to handle signals: When calling readEvent() then signals directed to the calling thread and those directed to the process can be received. Signals directed at other threads cannot be seen.

The readEvent() function fills in SignalFD::Info, a data structure that is very similar to the SigInfo structure, but not quite, which made it necessary to model a distinct type for use with SignalFD.

Definition at line 37 of file SignalFD.hxx.

Constructor & Destructor Documentation

SignalFD() [1/4]

cosmos::SignalFD::SignalFD ( )

inline

Creates an invalid SignalFD object.

Definition at line 45 of file SignalFD.hxx.

{}

~SignalFD()

cosmos::SignalFD::~SignalFD

(

)

Definition at line 17 of file SignalFD.cxx.

                    {
        try {
                close();
        } catch (const std::exception &ex) {
                noncritical_error("Failed to close signal fd", ex);
        }
}

SignalFD() [2/4]

cosmos::SignalFD::SignalFD ( const SigSet & mask )

inlineexplicit

Creates a signal FD listening on the given signals.

Definition at line 50 of file SignalFD.hxx.

                                              {
                create(mask);
        }

SignalFD() [3/4]

cosmos::SignalFD::SignalFD ( const std::initializer_list< Signal > siglist )

inlineexplicit

Creates a signal FD listening on the given list of signals.

Definition at line 55 of file SignalFD.hxx.

                                                                     {
                create(SigSet{siglist});
        }

SignalFD() [4/4]

cosmos::SignalFD::SignalFD ( const Signal s )

inlineexplicit

Creates a signal FD listening on exactly the given signal.

Definition at line 60 of file SignalFD.hxx.

                                          {
                create(SigSet{{s}});
        }

Member Function Documentation

adjustMask()

void cosmos::SignalFD::adjustMask

(

const SigSet &

mask

)

Change the signals the file descriptor is listening for.

A valid SignalFD must be opened for this to work, otherwise an exception is thrown.

Definition at line 35 of file SignalFD.cxx.

                                            {
        if (!valid()) {
                cosmos_throw (UsageError("no signal fd currently open"));
        }
 
        // NOTE: it's unclear from the man page whether flags are used when
        // modifying an existing signal fd. Let's pass on zero, hoping that no
        // flags will be taken away again through this.
        auto fd = ::signalfd(to_integral(m_fd.raw()), mask.raw(), 0);
        if (fd == -1) {
                cosmos_throw (ApiError("signalfd()"));
        }
}

close()

void cosmos::SignalFD::close ( )

inline

Definition at line 75 of file SignalFD.hxx.

{ m_fd.close(); }

create()

void cosmos::SignalFD::create

(

const SigSet &

mask

)

Creates a new SignalFD.

if a SignalFD is already open then it will be closed first. If an error occurs creating the new SignalFD then an exception is thrown.

Definition at line 25 of file SignalFD.cxx.

                                        {
        close();
        auto fd = ::signalfd(-1, mask.raw(), SFD_CLOEXEC);
        if (fd == -1) {
                cosmos_throw (ApiError("signalfd()"));
        }
 
        m_fd.setFD(FileNum{fd});
}

fd()

auto cosmos::SignalFD::fd ( )

inline

Returns the FileDescriptor object associated with the SignalFD.

Definition at line 98 of file SignalFD.hxx.

{ return m_fd; }

readEvent()

void cosmos::SignalFD::readEvent

(

Info &

info

)

Reads the next event event from the SignalFD.

This is a blocking operation so you should use an efficient poll mechanism like select() to determine whether there is anything to read.

If an error occurs trying to read a signal description then an exception is thrown.

Definition at line 49 of file SignalFD.cxx.

                                   {
        auto raw = info.raw();
        constexpr auto RAW_SIZE = sizeof(*raw);
 
        auto res = ::read(to_integral(m_fd.raw()), raw, RAW_SIZE);
 
        if (res < 0) {
                cosmos_throw (ApiError("read(sigfd)"));
        }
        else if (static_cast<size_t>(res) < RAW_SIZE) {
                cosmos_throw (RuntimeError("short read from signal fd"));
        }
}

valid()

auto cosmos::SignalFD::valid ( ) const

inline

Definition at line 77 of file SignalFD.hxx.

{ return m_fd.valid(); }

Member Data Documentation

m_fd

FileDescriptor cosmos::SignalFD::m_fd

protected

Definition at line 102 of file SignalFD.hxx.

---

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

• include/proc/SignalFD.hxx
• src/proc/SignalFD.cxx