cosmos::SubProc Class Reference

Represents a child process created via ChildCloner. More...

#include <SubProc.hxx>

Public Member Functions
	SubProc ()=default
	Creates an empty sub process without state.
	SubProc (SubProc &&other) noexcept
	Implements move-semantics.
SubProc &	operator= (SubProc &&other) noexcept
auto	running () const
	Returns whether a child process is still active.
ChildData	wait (const WaitFlags flags=WaitFlags{WaitFlag::WAIT_FOR_EXITED})
	Performs a blocking wait until the child process exits.
std::optional< ChildData >	waitTimed (const IntervalTime max, const WaitFlags flags=WaitFlags{WaitFlag::WAIT_FOR_EXITED})
	Wait for sub process exit within a timeout in milliseconds.
void	kill (const Signal signal)
	Send the specified signal to the child process.
ProcessID	pid () const
	Returns the PID of the currently running child process or ProcessID::INVALID.
PidFD	pidFD () const
	Returns a pidfd referring to the currently running child.

Protected Member Functions
	SubProc (const ProcessID pid, const PidFD pidfd)
	Wraps the given process ID and pidfd.
void	reset ()

Protected Attributes
ProcessID	m_pid = ProcessID::INVALID
	The pid of the child process, if any.
PidFD	m_child_fd
	Pidfd referring to the active child, if any.

Friends
class	ChildCloner

Detailed Description

Represents a child process created via ChildCloner.

This is a lightweight sub process description returned from ChildCloner::run(). It is used to interact with a running sub process:

• sending signals to it
• waiting for it to exit, optionally with timeout
• getting a pidfd for waiting for it in event driven I/O, or otherwise operate on the child (e.g. Linux namespace operations).

This is a non-copyable move-only type. If you want to store it in a member variable then use std::move().

Each running() SubProc instance needs to be wait()ed on to free the associated resources. The destructor will otherwise abort().

Definition at line 30 of file SubProc.hxx.

Constructor & Destructor Documentation

~SubProc()

cosmos::SubProc::~SubProc

(

)

Definition at line 12 of file SubProc.cxx.

                  {
        if (running()) {
                fatal_error("destroying SubProc while child process still running");
        }
}

SubProc() [1/2]

cosmos::SubProc::SubProc ( SubProc && other )

inlinenoexcept

Implements move-semantics.

This type can be moved but not copied. This is because the internal state cannot be copied, once the child process has exited all instances of the pidfd have to be invalidated.

The move-semantics allow to keep a SubProc as a class member.

Definition at line 50 of file SubProc.hxx.

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

SubProc() [2/2]

cosmos::SubProc::SubProc ( const ProcessID pid, const PidFD pidfd )

inlineprotected

Wraps the given process ID and pidfd.

Definition at line 112 of file SubProc.hxx.

                                                        :
                m_pid{pid}, m_child_fd{pidfd}
        {}

Member Function Documentation

kill()

void cosmos::SubProc::kill

(

const Signal

signal

)

Send the specified signal to the child process.

Definition at line 18 of file SubProc.cxx.

                                 {
        signal::send(m_child_fd, s);
}

operator=()

SubProc & cosmos::SubProc::operator= ( SubProc && other )

noexcept

Definition at line 67 of file SubProc.cxx.

                                                    {
        if (running()) {
                fatal_error("moving into SubProc object with still running child process");
        }
        m_pid = other.m_pid;
        m_child_fd = other.m_child_fd;
        other.m_pid = ProcessID::INVALID;
        other.m_child_fd.reset();
        return *this;
}

pid()

ProcessID cosmos::SubProc::pid ( ) const

inline

Returns the PID of the currently running child process or ProcessID::INVALID.

Definition at line 93 of file SubProc.hxx.

{ return m_pid; }

pidFD()

PidFD cosmos::SubProc::pidFD ( ) const

inline

Returns a pidfd referring to the currently running child.

This file descriptor can be used for efficiently waiting for child exit using poll() or select() APIs, see man pidfd_open. This somewhat breaks encapsulation, so take care not to misuse this file descriptor in a way that could break the SubProc class logic.

The ownership of the file descriptor stays with the SubProc implementation. Never close this descriptor.

Definition at line 105 of file SubProc.hxx.

{ return m_child_fd; }

reset()

void cosmos::SubProc::reset ( )

protected

Definition at line 22 of file SubProc.cxx.

                    {
        m_pid = ProcessID::INVALID;
        m_child_fd.close();
}

running()

auto cosmos::SubProc::running ( ) const

inline

Returns whether a child process is still active.

This can return true even if the child process already exited, in case the child process's exit status was not yet collected via wait().

Definition at line 62 of file SubProc.hxx.

{ return m_child_fd.valid(); }

wait()

ChildData cosmos::SubProc::wait

(

const WaitFlags

flags = WaitFlags{WaitFlag::WAIT_FOR_EXITED}

)

Performs a blocking wait until the child process exits.

The caller can pass special flags in order to collect also other child process state changes. If the child process actually exits, and WaitFlag::LEAVE_INFO is not set in flags, then the binding of the SubProc instance to the child process is released and running() will return false. Further wait() calls will not be allowed in that case.

WaitFlag::NO_HANG is not allowed to be passed to this function, otherwise a UsageError is thrown. To test for child state changes without blocking, use waitTimed() with a zero wait time.

Definition at line 27 of file SubProc.cxx.

                                             {
 
        if (flags[WaitFlag::NO_HANG]) {
                cosmos_throw (UsageError("cannot use NO_HANG with SubProc, use waitTimed() instead"));
        }
 
        try {
                auto child = proc::wait(m_child_fd, flags);
                if (!flags[WaitFlag::LEAVE_INFO] && (child->exited() || child->signaled())) {
                        reset();
                }
                return *child;
        } catch (const ApiError &err) {
                // for some reason the child was already collected, invalidate
                // our state to prevent infinite loops / uncleanable SubProc
                // objects
                if (err.errnum() == Errno::NO_CHILD) {
                        try {
                                reset();
                        } catch(...) {
                                // FileDescriptor will be invalidated already in this case
                        }
                }
 
                throw;
        }
}

waitTimed()

std::optional< ChildData > cosmos::SubProc::waitTimed	(	const IntervalTime	max,
		const WaitFlags	flags = WaitFlags{WaitFlag::WAIT_FOR_EXITED} )

Wait for sub process exit within a timeout in milliseconds.

Returns

The exit status if the child exited. Nothing if the timeout occurred.

See also

wait()

Definition at line 55 of file SubProc.cxx.

                                                                                       {
        Poller poller(8);
 
        poller.addFD(m_child_fd, {Poller::MonitorFlag::INPUT});
 
        if (poller.wait(max).empty()) {
                return std::nullopt;
        }
 
        return wait(flags);
}

Friends And Related Symbol Documentation

ChildCloner

friend class ChildCloner

friend

Definition at line 109 of file SubProc.hxx.

Member Data Documentation

m_child_fd

PidFD cosmos::SubProc::m_child_fd

protected

Pidfd referring to the active child, if any.

Definition at line 124 of file SubProc.hxx.

m_pid

ProcessID cosmos::SubProc::m_pid = ProcessID::INVALID

protected

The pid of the child process, if any.

Definition at line 121 of file SubProc.hxx.

---

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

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