Spawns a child process and exposes its stdin/stdout/stderr as async handles. More...

#include <pipe.hpp>

Public Member Functions
template<typename TPoller>
	TPipe (TPoller &poller, const std::string &exe, const std::vector< std::string > &args, bool stderrToStdout=false)
	Spawns exe with args and wires up async I/O handles.
int	Pid () const
	Returns the child's process ID.
void	CloseRead ()
	Closes the read end of the child's stdout pipe.
void	CloseWrite ()
	Closes the write end of the child's stdin pipe, sending EOF to the child.
void	CloseErr ()
	Closes the read end of the child's stderr pipe.
int	Wait ()
	Waits for the child process to exit and returns its exit status.
TFuture< int >	AsyncWait ()
	Waits for the child process to exit without blocking the event loop.
TFuture< ssize_t >	ReadSome (void *buffer, size_t size)
	Reads up to size bytes from the child's stdout.
TFuture< ssize_t >	ReadSomeErr (void *buffer, size_t size)
	Reads up to size bytes from the child's stderr.
TFuture< ssize_t >	WriteSome (const void *buffer, size_t size)
	Writes up to size bytes to the child's stdin.

Detailed Description

Spawns a child process and exposes its stdin/stdout/stderr as async handles.

Linux/macOS only (#ifndef _WIN32). The constructor forks immediately; the child runs exe with args. The parent side owns three async file handles:

WriteSome → child's stdin
ReadSome → child's stdout
ReadSomeErr → child's stderr (unless stderrToStdout = true)

Call CloseWrite() to send EOF to the child, then AsyncWait() to reap it. The Close*() calls take effect in the poller's next iteration, so call the blocking Wait() only once the child's output was read to EOF.

TPipe pipe(poller, "/bin/cat", {});
co_await pipe.WriteSome("hello\n", 6);
pipe.CloseWrite();
 
char buf[64];
ssize_t n = co_await pipe.ReadSome(buf, sizeof(buf));
int exit_code = co_await pipe.AsyncWait();

Constructor & Destructor Documentation

◆ TPipe()

template<typename TPoller>

NNet::TPipe::TPipe	(	TPoller &	poller,
		const std::string &	exe,
		const std::vector< std::string > &	args,
		bool	stderrToStdout = false )

inline

Spawns exe with args and wires up async I/O handles.

Parameters

poller	Event-loop poller used for async I/O on the pipe fds.
exe	Absolute path to the executable.
args	Arguments passed to the executable (argv[1..]).
stderrToStdout	If true, child stderr is redirected into stdout (ReadSomeErr becomes unavailable).

Member Function Documentation

◆ AsyncWait()

TFuture< int > NNet::TPipe::AsyncWait ( )

Waits for the child process to exit without blocking the event loop.

Polls waitpid(WNOHANG) and sleeps on the poller between attempts with a backoff growing from 1 ms to 32 ms, so it works with every poller backend. Once it completes the child is reaped and Pid() returns -1.

The returned future refers to this TPipe, so the pipe must outlive the future: destroying it while the future is suspended is a use-after-free.

Returns: The child's exit code, or -1 if it did not exit normally or was already reaped.

◆ ReadSome()

TFuture< ssize_t > NNet::TPipe::ReadSome	(	void *	buffer,
		size_t	size )

Reads up to size bytes from the child's stdout.

Returns bytes read (>0), 0 on EOF (child closed stdout), or a negative retry hint on transient errors.

◆ ReadSomeErr()

TFuture< ssize_t > NNet::TPipe::ReadSomeErr	(	void *	buffer,
		size_t	size )

Reads up to size bytes from the child's stderr.

Only valid when stderrToStdout = false. Returns bytes read (>0), 0 on EOF, or a negative retry hint.

◆ Wait()

int NNet::TPipe::Wait ( )

Waits for the child process to exit and returns its exit status.

Blocks the calling thread (via waitpid) without running the loop. Call after the child has finished or after sending it a signal; see the class description.

Once it returns the child is reaped and Pid() returns -1.

Returns: The child's exit code, or -1 if it did not exit normally or was already reaped.

◆ WriteSome()

TFuture< ssize_t > NNet::TPipe::WriteSome	(	const void *	buffer,
		size_t	size )

Writes up to size bytes to the child's stdin.

Returns bytes written (>0), 0 if the child closed stdin, or a negative retry hint on transient errors.

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

coroio/pipe/pipe.hpp
coroio/pipe/pipe.cpp

Public Member Functions