StormByte::System::Process Class Reference

Runs an external program with piped stdin/stdout/stderr. More...

#include <StormByte/system/process.hxx>

Public Types
enum class	Error {   Success = 0 , ExecutableNotFound , CreationFailed , Permission ,   NotRunning , AlreadyExited , TimedOut , BrokenPipe ,   Canceled }
	Child-process enumerators. More...
enum class	Status : unsigned short { RUNNING , SUSPENDED , TERMINATED }
	Process lifecycle. More...

Public Member Functions
	Process (const std::filesystem::path &prog, const std::vector< StormByte::String::String > &args={}) noexcept
	Construct and start.
	Process (std::filesystem::path &&prog, std::vector< StormByte::String::String > &&args={}) noexcept
	Construct and start (moved).
	Process (const Process &proc)=delete
	Process (Process &&proc) noexcept
	Move constructor (invalidates the source).
Process &	operator= (const Process &proc)=delete
Process &	operator= (Process &&proc) noexcept
	Move assignment (invalidates the source).
virtual	~Process () noexcept
	Destructor (waits if still owning a child, then frees pipes).
	operator bool () const noexcept
	Whether a child is live.
StormByte::Error::Fault	Fault () const noexcept
	Last Process error.
int	Wait () noexcept
	Block until the process exits (no timeout).
int	Wait (std::chrono::milliseconds timeout) noexcept
	Wait for the process to exit up to timeout.
pid_t	Pid () noexcept
	Child PID.
void	Suspend ()
	Suspend the child process.
void	Resume ()
	Resume a suspended child process.
Process &	operator>> (Process &proc)
	Forward this process stdout to proc stdin (background thread).
std::string &	operator>> (std::string &str) const
	Read remaining stdout into a caller-owned string.
StormByte::String::String &	operator>> (StormByte::String::String &str) const
	Read remaining stdout into owned text.
std::string &	Stderr (std::string &str) const
	Read remaining stderr into a caller-owned string.
StormByte::String::String &	Stderr (StormByte::String::String &str) const
	Read remaining stderr into owned text.
Process &	operator<< (std::string_view str)
	Write UTF-8 text to process stdin.
Process &	operator<< (const StormByte::String::String &str)
	Write owned UTF-8 text to process stdin.
Process &	operator<< (const StormByte::CString &str)
	Write a CString to process stdin.
void	operator<< (const System::_EoF &eof)
	Close process stdin (write end).

Friends
std::ostream &	operator<< (std::ostream &ostream, const Process &proc)
	Stream process stdout to an ostream.

Detailed Description

Runs an external program with piped stdin/stdout/stderr.

Starts immediately on construction. Move-only. Construction does not throw. operator bool is true only while a child is live (running or suspended). A finished, moved-from or failed spawn is false. Inspect Fault for the reason.

Supports chaining (p1 >> p2), writing stdin, reading stdout/stderr, Suspend/Resume.

Member Enumeration Documentation

Error

enum class StormByte::System::Process::Error

strong

Child-process enumerators.

Domain tag StormByte.System.Process. Zero is success.

Enumerator
Success	No error.
ExecutableNotFound	The program path or name could not be resolved.
CreationFailed	The child could not be created (fork, pipe, CreateProcess)
Permission	The caller may not create or signal this child.
NotRunning	There is no live child for this operation.
AlreadyExited	The child has already exited.
TimedOut	A timed wait expired.
BrokenPipe	stdin/stdout/stderr pipe is closed or unusable
Canceled	The operation was canceled.

Status

enum class StormByte::System::Process::Status : unsigned short

strong

Process lifecycle.

Enumerator
RUNNING	Running.
SUSPENDED	Suspended.
TERMINATED	Finished / cleaned up.

Constructor & Destructor Documentation

Process() [1/4]

StormByte::System::Process::Process ( const std::filesystem::path &  prog, const std::vector< StormByte::String::String > &  args = {}  )

noexcept

Construct and start.

Parameters

prog	Executable path or name.
args	Argument list (not including argv[0]).

Process() [2/4]

StormByte::System::Process::Process ( std::filesystem::path &&  prog, std::vector< StormByte::String::String > &&  args = {}  )

noexcept

Construct and start (moved).

Parameters

prog	Executable path or name (moved).
args	Argument list (moved).

Process() [3/4]

StormByte::System::Process::Process ( const Process &  proc )

delete

Process() [4/4]

StormByte::System::Process::Process ( Process &&  proc )

noexcept

Move constructor (invalidates the source).

~Process()

virtual StormByte::System::Process::~Process ( )

virtualnoexcept

Destructor (waits if still owning a child, then frees pipes).

Member Function Documentation

Fault()

StormByte::Error::Fault StormByte::System::Process::Fault ( ) const

noexcept

Last Process error.

Returns

Success, or a Error code.

operator bool()

StormByte::System::Process::operator bool ( ) const

explicitnoexcept

Whether a child is live.

Returns

true if the status is running or suspended.

operator<<() [1/4]

Process & StormByte::System::Process::operator<<

(

const StormByte::CString &

str

)

Write a CString to process stdin.

Parameters

str

Data.

Returns

*this.

operator<<() [2/4]

Process & StormByte::System::Process::operator<<

(

const StormByte::String::String &

str

)

Write owned UTF-8 text to process stdin.

Parameters

str

Data.

Returns

*this.

operator<<() [3/4]

void StormByte::System::Process::operator<<

(

const System::_EoF &

eof

)

Close process stdin (write end).

Parameters

eof	EoF sentinel.

operator<<() [4/4]

Process & StormByte::System::Process::operator<<

(

std::string_view

str

)

Write UTF-8 text to process stdin.

Parameters

str

Data.

Returns

*this.

operator=() [1/2]

Process & StormByte::System::Process::operator= ( const Process &  proc )

delete

operator=() [2/2]

Process & StormByte::System::Process::operator= ( Process &&  proc )

noexcept

Move assignment (invalidates the source).

operator>>() [1/3]

Process & StormByte::System::Process::operator>>

(

Process &

proc

)

Forward this process stdout to proc stdin (background thread).

Parameters

proc	Target process.

Returns

Reference to proc.

operator>>() [2/3]

std::string & StormByte::System::Process::operator>>

(

std::string &

str

)

const

Read remaining stdout into a caller-owned string.

Parameters

str	Destination.

Returns

Reference to str.

operator>>() [3/3]

StormByte::String::String & StormByte::System::Process::operator>>

(

StormByte::String::String &

str

)

const

Read remaining stdout into owned text.

Parameters

str	Destination.

Returns

Reference to str.

Pid()

pid_t StormByte::System::Process::Pid ( )

noexcept

Child PID.

Returns

PID, or -1 if not owning a process.

Resume()

void StormByte::System::Process::Resume

(

)

Resume a suspended child process.

Stderr() [1/2]

std::string & StormByte::System::Process::Stderr

(

std::string &

str

)

const

Read remaining stderr into a caller-owned string.

Parameters

str	Destination.

Returns

Reference to str.

Stderr() [2/2]

StormByte::String::String & StormByte::System::Process::Stderr

(

StormByte::String::String &

str

)

const

Read remaining stderr into owned text.

Parameters

str	Destination.

Returns

Reference to str.

Suspend()

void StormByte::System::Process::Suspend

(

)

Suspend the child process.

Wait() [1/2]

int StormByte::System::Process::Wait ( )

noexcept

Block until the process exits (no timeout).

Returns

Exit code, or -1 on failure, signal termination, or already reaped.

Wait() [2/2]

int StormByte::System::Process::Wait ( std::chrono::milliseconds  timeout )

noexcept

Wait for the process to exit up to timeout.

Parameters

timeout

Maximum wait duration.

Returns

Exit code, or -1 on timeout, failure, or already reaped.

Friends And Related Symbol Documentation

operator<<

std::ostream & operator<< ( std::ostream &  ostream, const Process &  proc  )

friend

Stream process stdout to an ostream.

Parameters

ostream	Destination.
proc	Process.

Returns

ostream.

---

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

• lib/public/StormByte/system/process.hxx