Fork a process and create a pipe to its standard input, seen as a C++ std::basic_ostream<char>. More...

#include <tsForkPipeOutputStream.h>

Inheritance diagram for ts::ForkPipeOutputStream:

[legend]

Collaboration diagram for ts::ForkPipeOutputStream:

[legend]

Public Types
enum	InputMode { STDIN_PARENT , STDIN_PIPE , STDIN_NONE }
	How to standard input in the created process. More...

enum	OutputMode { KEEP_BOTH , STDOUT_ONLY , STDERR_ONLY , STDOUT_PIPE , STDOUTERR_PIPE }
	How to merge standard output and standard error in the created process. More...

using	SuperClass = std::basic_ostream< char >
	Explicit reference to the public superclass.

enum	WaitMode { ASYNCHRONOUS , SYNCHRONOUS , EXIT_PROCESS }
	How to wait for the created process when close() is invoked. More...

Public Member Functions
	ForkPipeOutputStream (Report *report)
	Constructor.

	ForkPipeOutputStream (ReporterBase *delegate)
	Constructor.

virtual	~ForkPipeOutputStream () override
	Destructor.

void	abortPipeReadWrite ()
	Abort any currenly input/output operation in the pipe.

virtual bool	asyncCompletedStream (IOSB *iosb) override
	Update the status of an asynchronous readStream() or writeStream() after it completed.

virtual bool	close (bool silent=false) override
	Close the pipe.

virtual bool	endOfStream () override
	Check if the end of stream was reached while reading.

SysHandleType	getHandle () const
	Get the underlying file descriptor or device handle.

bool	getIgnoreAbort () const
	Get "ignore abort".

SysHandleType	getProcessHandle () const
	Get the created process handle.

SysProcessIdType	getProcessId () const
	Get the created process id.

virtual SysHandleType	getReadHandle () const override
	Get the underlying file descriptor or device handle for read operations.

SysSocketType	getReadSocket () const
	Get the underlying file descriptor or device handle as a system socket handle for read operations.

SysSocketType	getSocket () const
	Get the underlying file descriptor or device handle as a system socket handle.

virtual SysHandleType	getWriteHandle () const override
	Get the underlying file descriptor or device handle for write operations.

SysSocketType	getWriteSocket () const
	Get the underlying file descriptor or device handle as a system socket handle for write operations.

bool	isBroken () const
	Check if the pipe was broken.

bool	isNonBlocking () const
	Check if the device is in non-blocking mode.

bool	isOpen () const
	Check if the process is running and the pipe is open (when used).

virtual bool	isReadStream () override
	Check if the stream is open for read.

bool	isSupportedByReactor (bool recheck=false)
	Check if the device is supported by a reactor for non-blocking or asynchronous I/O.

bool	isSynchronous () const
	Check if synchronous mode is active (ie.

virtual bool	isWriteStream () override
	Check if the stream is open for write.

bool	muteReport (bool mute)
	Temporarily mute the associated report.

bool	open (const UString &command, WaitMode wait_mode, size_t buffer_size, OutputMode out_mode, InputMode in_mode)
	Create the process, open the optional pipes.

virtual bool	readStream (void addr, size_t max_size, size_t &ret_size, const AbortInterface abort=nullptr, IOSB *iosb=nullptr) override
	Read some data from the stream.

virtual bool	readStream (void addr, size_t size, const AbortInterface abort=nullptr) override
	Read complete data from the stream.

virtual Report &	report () const override
	Access the Report which is associated with this object.

void	setIgnoreAbort (bool on)
	Set "ignore abort".

bool	setNonBlocking (bool non_blocking)
	Set the device in non-blocking mode.

Report *	setReport (Report *report)
	Associate this object with another Report to log errors.

ReporterBase *	setReport (ReporterBase *delegate)
	Associate this object with another ReporterBase to log errors.

virtual bool	writeStream (const void addr, size_t size, IOSB iosb=nullptr) override
	Write data to the stream.

virtual bool	writeStream (const void addr, size_t size, size_t &written_size, IOSB iosb=nullptr) override
	Write some data to the stream.

Static Public Member Functions
static bool	GetOutput (UString &output, const UString &command, Report &report, bool include_stderr=false)
	This static method launches a command and gets its output as text.

static bool	IsPendingStatus (int error_code)
	This static method checks if a system error code means "I/O in progress" (asynchronous I/O) or "I/O would block" (non-blocking I/O).

static bool	Launch (const UString &command, Report &report, OutputMode out_mode=KEEP_BOTH, InputMode in_mode=STDIN_PARENT, WaitMode wait_mode=ASYNCHRONOUS)
	This static method launches a command, without pipe, optionally without waiting for the completion of the command process.

static int	SilentLevel (bool silent, int default_severity=Severity::Error)
	Compute a log severity level from a "silent" parameter.

Static Public Attributes
static constexpr size_t	DEFAULT_STREAM_BUFFER_SIZE = 1024
	Default stream buffer size in bytes.

Protected Member Functions
virtual bool	allowSetNonBlocking () const override
	Check that the non-blocking mode can be set.

bool	checkNonBlocking (bool non_blocking, const UChar *opname)
	Check the blocking mode of a device.

bool	checkNonBlocking (IOSB iosb, const UChar opname)
	Check the blocking mode of a device.

int	genericSystemRead (void addr, size_t max_size, size_t &ret_size, const AbortInterface abort, NonBlockingDevice::IOSB *iosb, uint64_t position)
	Generic system read operation.

int	genericSystemWrite (const void addr, size_t size, size_t &written_size, NonBlockingDevice::IOSB iosb, uint64_t position)
	Generic system write operation.

bool	setSystemNonBlocking (bool non_blocking)
	Low-level method to set the system file or socket descriptor in non-blocking mode.

virtual bool	writeStreamBuffer (const void *addr, size_t size) override
	Write buffered data to underlying output devicen whatever it is.

Static Protected Member Functions
template<class T > requires std::derived_from<T, StreamInterface>
static bool	ReadStreamHelper (T obj, void addr, size_t size, const AbortInterface *abort)
	Implementation helper for fixed-size version of readStream().

template<class T > requires std::derived_from<T, StreamInterface>
static bool	WriteStreamHelper (T obj, const void addr, size_t size, NonBlockingDevice::IOSB *iosb)
	Implementation helper for fixed-size version of writeStream().

Detailed Description

Fork a process and create a pipe to its standard input, seen as a C++ std::basic_ostream<char>.

Member Enumeration Documentation

◆ WaitMode

enum ts::ForkPipe::WaitMode

inherited

How to wait for the created process when close() is invoked.

No pipe can be used with EXIT_PROCESS because there would be nobody on the other end of the pipe.

Enumerator
ASYNCHRONOUS	Don't wait, close() will return immediately.
SYNCHRONOUS	Wait for process completion during close().
EXIT_PROCESS	Exit parent process during open(). UNIX: call exec(), Windows: call exit() after process creation.

◆ InputMode

enum ts::ForkPipe::InputMode

inherited

How to standard input in the created process.

Enumerator
STDIN_PARENT	Keep same stdin as current (parent) process.
STDIN_PIPE	Use a pipe as stdin.
STDIN_NONE	No standard input (the null device in fact).

◆ OutputMode

enum ts::ForkPipe::OutputMode

inherited

How to merge standard output and standard error in the created process.

Enumerator
KEEP_BOTH	Keep same stdout and stderr as current (parent) process.
STDOUT_ONLY	Merge stderr into current stdout.
STDERR_ONLY	Merge stdout into current stderr.
STDOUT_PIPE	Use a pipe to receive stdout, keep same stderr as current (parent) process.
STDOUTERR_PIPE	Use a pipe to receive a merge of stdout and stderr.

Constructor & Destructor Documentation

◆ ForkPipeOutputStream() [1/2]

ts::ForkPipeOutputStream::ForkPipeOutputStream ( Report * report )

explicit

Constructor.

Parameters

[in] report Where to report errors. The report object must remain valid as long as this object exists or setReport() is used with another Report object. If report is null, log messages are discarded.

◆ ForkPipeOutputStream() [2/2]

ts::ForkPipeOutputStream::ForkPipeOutputStream ( ReporterBase * delegate )

explicit

Constructor.

Parameters

[in] delegate Use the report of another ReporterBase. If delegate is null, log messages are discarded.

Member Function Documentation

◆ close()

virtual bool ts::ForkPipeOutputStream::close ( bool silent = false )

overridevirtual

Close the pipe.

Optionally wait for process termination if wait_mode was SYNCHRONOUS on open().

Parameters

[in] silent If true, do not report errors. This is typically useful when the object is in some error condition and closing it is necessary although it may generate additional meaningless errors.

Returns: True on success, false on error.

Reimplemented from ts::ForkPipe.

◆ writeStreamBuffer()

virtual bool ts::ForkPipeOutputStream::writeStreamBuffer	(	const void *	addr,
		size_t	size
	)

overrideprotectedvirtual

Write buffered data to underlying output devicen whatever it is.

Must be implemented by subclasses.

Parameters

[in]	addr	Buffered data address.
[in]	size	Buffered data size in bytes.

Returns: True on success, false on error.

Implements ts::AbstractStandardOutputStream.

◆ open()

bool ts::ForkPipe::open	(	const UString &	command,
		WaitMode	wait_mode,
		size_t	buffer_size,
		OutputMode	out_mode,
		InputMode	in_mode
	)

inherited

Create the process, open the optional pipes.

Parameters

[in]	command	The command to execute.
[in]	wait_mode	How to wait for process termination in close().
[in]	buffer_size	The pipes buffer size in bytes. Used on Windows only. Zero means default.
[in]	out_mode	How to handle stdout and stderr.
[in]	in_mode	How to handle stdin.

Returns: True on success, false on error. Do not return on success when wait_mode is EXIT_PROCESS.

◆ isOpen()

bool ts::ForkPipe::isOpen ( ) const

inlineinherited

Check if the process is running and the pipe is open (when used).

Returns: True if the process is running and the pipe is open.

◆ isBroken()

bool ts::ForkPipe::isBroken ( ) const

inlineinherited

Check if the pipe was broken.

Returns: True if was broken (unexpected process termination for instance).

◆ isSynchronous()

bool ts::ForkPipe::isSynchronous ( ) const

inlineinherited

Check if synchronous mode is active (ie.

will wait for process termination).

Returns: True if synchronous mode is active.

◆ getProcessId()

SysProcessIdType ts::ForkPipe::getProcessId ( ) const

inlineinherited

Get the created process id.

Returns: The process id or SYS_PROCESS_ID_INVALID in case of error.

◆ getProcessHandle()

SysHandleType ts::ForkPipe::getProcessHandle ( ) const

inlineinherited

Get the created process handle.

The concept of process handle exists on Windows only.

Returns: The process id or SYS_HANDLE_INVALID in case of error or when process handles are not supported.

◆ setIgnoreAbort()

void ts::ForkPipe::setIgnoreAbort ( bool on )

inlineinherited

Set "ignore abort".

Parameters

[in] on If true and the process aborts, do not report error when writing data. when writing data.

◆ getIgnoreAbort()

bool ts::ForkPipe::getIgnoreAbort ( ) const

inlineinherited

Get "ignore abort".

Returns: True if, when the process aborts, do not report error when writing data.

◆ abortPipeReadWrite()

void ts::ForkPipe::abortPipeReadWrite ( )

inherited

Abort any currenly input/output operation in the pipe.

The pipe is left in a broken state and can be only closed.

◆ Launch()

static bool ts::ForkPipe::Launch	(	const UString &	command,
		Report &	report,
		OutputMode	out_mode = `KEEP_BOTH`,
		InputMode	in_mode = `STDIN_PARENT`,
		WaitMode	wait_mode = `ASYNCHRONOUS`
	)

staticinherited

This static method launches a command, without pipe, optionally without waiting for the completion of the command process.

Parameters

[in]	command	The command to execute.
[in,out]	report	Where to report errors.
[in]	out_mode	How to handle stdout and stderr. Must be KEEP_BOTH (default), STDOUT_ONLY or STDERR_ONLY. Output modes using pipes are forbidden.
[in]	in_mode	How to handle stdin. Must be STDIN_PARENT (default) or STDIN_NONE. Input modes using pipes are forbidden.
[in]	wait_mode	How to wait for the command process. Must be ASYNCHRONOUS (default) or SYNCHRONOUS.

Returns: True on success, false on error.

◆ GetOutput()

static bool ts::ForkPipe::GetOutput	(	UString &	output,
		const UString &	command,
		Report &	report,
		bool	include_stderr = `false`
	)

staticinherited

This static method launches a command and gets its output as text.

Parameters

[in]	output	The output of the command.
[in]	command	The command to execute.
[in,out]	report	Where to report errors.
[in]	include_stderr	If false, the standard error of the command is the same as the parent process. If true, the standard error is merged with the standard output in output.

Returns: True on success, false on error.

◆ getReadHandle()

virtual SysHandleType ts::ForkPipe::getReadHandle ( ) const

overridevirtualinherited

Get the underlying file descriptor or device handle for read operations.

Subclasses should override this method.

Returns: The underlying file descriptor for read operations or SYS_HANDLE_INVALID if the device is not open for read.

See also: getHandle()

Reimplemented from ts::NonBlockingDevice.

◆ getWriteHandle()

virtual SysHandleType ts::ForkPipe::getWriteHandle ( ) const

overridevirtualinherited

Get the underlying file descriptor or device handle for write operations.

Subclasses should override this method.

Returns: The underlying file descriptor for write operations or SYS_HANDLE_INVALID if the device is not open for write.

See also: getHandle()

Reimplemented from ts::NonBlockingDevice.

◆ readStream() [1/2]

virtual bool ts::ForkPipe::readStream	(	void *	addr,
		size_t	size,
		const AbortInterface *	abort = `nullptr`
	)

overridevirtualinherited

Read complete data from the stream.

Read exactly size bytes, waiting if necessary.

Synchronization: There is no iosb parameter because this method uses blocking I/O by design. An error is returned if the instance of the class which implements StreamInterface is in non-blocking mode.

Parameters

[out]	addr	Address of the buffer for the incoming data.
[in]	size	Size in bytes of the buffer.
[in]	abort	If non-zero, invoked when I/O is interrupted (in case of user-interrupt, return, otherwise retry).

Returns: True on success, false on error or it less than size bytes could be read.

Implements ts::StreamInterface.

◆ readStream() [2/2]

virtual bool ts::ForkPipe::readStream	(	void *	addr,
		size_t	max_size,
		size_t &	ret_size,
		const AbortInterface *	abort = `nullptr`,
		IOSB *	iosb = `nullptr`
	)

overridevirtualinherited

Read some data from the stream.

Wait and read at least one byte. Don't try to read exactly max_size bytes. If ret_size is less than max_bytes, it is possible to read more.

Parameters

[out]	addr	Address of the buffer for the incoming data.
[in]	max_size	Maximum size in bytes of the buffer.
[out]	ret_size	Returned input size in bytes. If zero, end of file has been reached or an error occurred.
[in]	abort	If non-zero, invoked when I/O is interrupted (in case of user-interrupt, return, otherwise retry).
[in,out]	iosb	Address of an IOSB structure. If non-null, the stream must be in non-blocking mode. When null, the stream must be in blocking mode (the default). See the description of ts::NonBlockingDevice::IOSB. Important: The parameter iosb should not be used by applications. It should be used only by "reactive classes", which work in combination with a Reactor.

Returns: True on success, false on error. In case of non-blocking mode, if the I/O is successfully started but still pending, iosb->pending is set to true and the method returns true.

Implements ts::StreamInterface.

◆ writeStream() [1/2]

virtual bool ts::ForkPipe::writeStream	(	const void *	addr,
		size_t	size,
		IOSB *	iosb = `nullptr`
	)

overridevirtualinherited

Write data to the stream.

All bytes are written to the stream, blocking or retrying when necessary when the stream is in blocking mode. The base implementation of writeStream() uses the virtual version with a written_size output parameter.

Parameters

[in]	addr	Address of the data to write.
[in]	size	Size in bytes of the data to write.
[in,out]	iosb	Address of an IOSB structure. If non-null, the stream must be in non-blocking mode. When null, the stream must be in blocking mode (the default). See the description of ts::NonBlockingDevice::IOSB. Important: The parameter iosb should not be used by applications. It should be used only by "reactive classes", which work in combination with a Reactor.

Returns: True on success, false on error or it less than size bytes could be written. In case of non-blocking mode, if the I/O is successfully started but still pending, iosb->pending is set to true and the method returns true.

Implements ts::StreamInterface.

◆ writeStream() [2/2]

virtual bool ts::ForkPipe::writeStream	(	const void *	addr,
		size_t	size,
		size_t &	written_size,
		IOSB *	iosb = `nullptr`
	)

overridevirtualinherited

Write some data to the stream.

All bytes are written to the stream, blocking or retrying when necessary when the stream is in blocking mode. Return the number of actually written bytes if some error occurred before writing everything.

Parameters

[in]	addr	Address of the data to write.
[in]	size	Size in bytes of the data to write.
[out]	written_size	Actually written size in bytes. Can be less than size in case of error in the middle of the write.
[in,out]	iosb	Address of an IOSB structure. If non-null, the stream must be in non-blocking mode. When null, the stream must be in blocking mode (the default). See the description of ts::NonBlockingDevice::IOSB. Important: The parameter iosb should not be used by applications. It should be used only by "reactive classes", which work in combination with a Reactor.

Returns: True on success, false on error. In case of non-blocking mode, if the I/O is successfully started but still pending, iosb->pending is set to true and the method returns true.

Implements ts::StreamInterface.

◆ asyncCompletedStream()

virtual bool ts::ForkPipe::asyncCompletedStream ( IOSB * iosb )

overridevirtualinherited

Update the status of an asynchronous readStream() or writeStream() after it completed.

This method applies to asynchronous I/O only (Windows), not non-blocking I/O (UNIX).

Parameters

[in,out] iosb Address of the IOSB structure which was used when readStream() or writeStream() was called.

Returns: True on success, false on error.

Implements ts::StreamInterface.

◆ isReadStream()

virtual bool ts::ForkPipe::isReadStream ( )

overridevirtualinherited

Check if the stream is open for read.

Returns: True if readStream() is possible, false otherwise (write-only, closed, or disconnected stream).

Implements ts::StreamInterface.

◆ isWriteStream()

virtual bool ts::ForkPipe::isWriteStream ( )

overridevirtualinherited

Check if the stream is open for write.

Returns: True if writeStream() is possible, false otherwise (read-only, closed, or disconnected stream).

Implements ts::StreamInterface.

◆ endOfStream()

virtual bool ts::ForkPipe::endOfStream ( )

overridevirtualinherited

Check if the end of stream was reached while reading.

Returns: True on end of stream, false otherwise.

Implements ts::StreamInterface.

◆ allowSetNonBlocking()

virtual bool ts::ForkPipe::allowSetNonBlocking ( ) const

overrideprotectedvirtualinherited

Check that the non-blocking mode can be set.

Must be implemented by subclasses which do not support setting the non-blocking in certain states, such as after being opened. The default implementation always allows setting the non-blocking mode.

Returns: True if setting the non-blocking mode is allowed, false otherwise.

Reimplemented from ts::NonBlockingDevice.

◆ setNonBlocking()

bool ts::NonBlockingDevice::setNonBlocking ( bool non_blocking )

inherited

Set the device in non-blocking mode.

Important: Usually, this method must be called before opening the device, whatever it means. Otherwise it is ignored and the device blocking mode is unchanged.

Parameters

[in] non_blocking It true, the device is set in non-blocking mode.

Returns: True on success, false if the device is already open and the non-blocking mode is unchanged.

◆ isNonBlocking()

bool ts::NonBlockingDevice::isNonBlocking ( ) const

inlineinherited

Check if the device is in non-blocking mode.

Returns: True if the device is in non-blocking mode, false otherwise.

See also: setNonBlocking()

◆ isSupportedByReactor()

bool ts::NonBlockingDevice::isSupportedByReactor ( bool recheck = false )

inherited

Check if the device is supported by a reactor for non-blocking or asynchronous I/O.

Parameters

[in] recheck If true, force a recheck. If false and the device was previously checked, return the previous cached value.

Returns: True if the device is supported by a reactor for non-blocking or asynchronous I/O, false otherwise.

◆ IsPendingStatus()

static bool ts::NonBlockingDevice::IsPendingStatus ( int error_code )

inlinestaticinherited

This static method checks if a system error code means "I/O in progress" (asynchronous I/O) or "I/O would block" (non-blocking I/O).

Parameters

[in] error_code System error code.

Returns: True if error_code is an in-progress/would-block one.

◆ getHandle()

SysHandleType ts::NonBlockingDevice::getHandle ( ) const

inherited

Get the underlying file descriptor or device handle.

This method is reserved for low-level operations and should not be used by normal applications.

On UNIX systems, sockets are standard file descriptors. On Windows systems, sockets and devices handles are two distinct types (SOCKET, an integer type, and HANDLE, a pointer type). However, SOCKET and HANDLE have the same size and can be converted between each other. In practice, all Windows device handles are pointers. When Microsoft decided to implement the BSD socket API, they needed to represent sockets as integers. The integer is simply a cast of the HANDLE pointer.

In practice, the methods getHandle() and getSocket() return the same value, represented as two different portable types, SysHandleType and SysSocketType. Note that this types are defined as their real representation. On UNIX systems, both are defined as int and are compatible. However, on Windows systems, they are defined as HANDLE and SOCKET and are not compatible. So, accidentally mixing the two compiles on UNIX but not on Windows. Be careful to use the right type for the right usage.

There is one important difference between getHandle() and getSocket(): the error values, SYS_HANDLE_INVALID and SYS_SOCKET_INVALID. Be careful, these constants have distinct binary values on Windows. This is the only case were it is not possible to cast between a SysHandleType value and a SysSocketType value. This is why it is recommended to always use getHandle() when a SysHandleType is required and getSocket() when a SysSocketType is required.

A subclass which uses file descriptors or device handles for read, write, or both, must override the methods getReadHandle(), getWriteHandle(), or both. If the two types of operations use the same file descriptor, the two methods must return the same value.

An application should call getReadHandle() for read operations and getWriteHandle() for write operations. The method getHandle() returns getReadHandle() if its returns a valid value, and getWriteHandle() otherwise.

Returns: The underlying file descriptor or device handler. Return SYS_HANDLE_INVALID if the socket is not open.

◆ getSocket()

SysSocketType ts::NonBlockingDevice::getSocket ( ) const

inherited

Get the underlying file descriptor or device handle as a system socket handle.

Returns: The underlying socket descriptor. Return SYS_SOCKET_INVALID if the socket is not open.

See also: getHandle()

◆ getReadSocket()

SysSocketType ts::NonBlockingDevice::getReadSocket ( ) const

inherited

Get the underlying file descriptor or device handle as a system socket handle for read operations.

Returns: The underlying file descriptor for read operations or SYS_SOCKET_INVALID if the socket is not open for read.

See also: getHandle()

◆ getWriteSocket()

SysSocketType ts::NonBlockingDevice::getWriteSocket ( ) const

inherited

Get the underlying file descriptor or device handle as a system socket handle for write operations.

Returns: The underlying file descriptor for read operations or SYS_SOCKET_INVALID if the socket is not open for write.

See also: getHandle()

◆ checkNonBlocking() [1/2]

bool ts::NonBlockingDevice::checkNonBlocking	(	bool	non_blocking,
		const UChar *	opname
	)

protectedinherited

Check the blocking mode of a device.

Called by subclass methods which are explicitly called in blocking or non-blocking mode.

Parameters

[in]	non_blocking	The required non-blocking mode.
[in]	opname	Name of the operation, for the error message.

Returns: True on success, false on error.

◆ checkNonBlocking() [2/2]

bool ts::NonBlockingDevice::checkNonBlocking	(	IOSB *	iosb,
		const UChar *	opname
	)

protectedinherited

Check the blocking mode of a device.

Called by subclass methods which are explicitly called in blocking or non-blocking mode.

Parameters

[in,out]	iosb	Address of an IOSB structure. If non-null, we are in non-blocking mode. When null, we are in blocking mode. When non-null, pending is reset to false and overlap is zeroed.
[in]	opname	Name of the operation, for the error message.

Returns: True on success, false on error.

◆ setSystemNonBlocking()

bool ts::NonBlockingDevice::setSystemNonBlocking ( bool non_blocking )

protectedinherited

Low-level method to set the system file or socket descriptor in non-blocking mode.

Parameters

[in] non_blocking It true, the device is set in non-blocking mode.

Returns: True on success, false on error.

Summary: Do not use this method unless you exactly know what you are doing.

UNIX: Depending on the way a file descriptor is created, it may be possible to specify the non-blocking mode from the beginning. Or it can be somehow inherited. However, this is not portable.

Examples:

On Linux and FreeBSD, a socket can be directly created in non-blocking mode using the flag SOCK_NONBLOCK in the 'type' parameter of the socket() system call. However, it does not work on macOS.
On macOS (and maybe FreeBSD), when a server socket is in non-blocking mode, all client session sockets which are created by accept() are also in non-blocking mode. However, on Linux, they are in blocking mode.

In all cases, it is possible to set a file descriptor in non-blocking mode at any time using the method setSystemNonBlocking(). This method uses fcntl(F_SETFL) to alter the file descriptor's flags.

Windows: The natural way of not being blocked on I/O on Windows is asynchronous I/O. To increase the general confusion, there is some form of non-blocking mode on Windows sockets, and only sockets, not other forms of file handles. This mode is activated using "ioctlsocket(fd, FIONBIO, &mode)". When this mode is active, socket I/O become similar to UNIX: they immediately either succeed or fail, but never block. However, there is no way to get notified when the I/O becomes possible. There is no equivalent to epoll (Linux) or kqueue (macOS and BSD). The Windows I/O Completion Ports can only work on asynchronous I/O, using OVERLAPPED structures. Because this form of non-blocking mode is mostly useless in practice, we do not use it and the method setSystemNonBlocking() does nothing on Windows.

See also: https://learn.microsoft.com/en-us/archive/blogs/csliu/io-concept-blockingnon-blocking-vs-syncasync

◆ genericSystemWrite()

int ts::NonBlockingDevice::genericSystemWrite	(	const void *	addr,
		size_t	size,
		size_t &	written_size,
		NonBlockingDevice::IOSB *	iosb,
		uint64_t	position
	)

protectedinherited

Generic system write operation.

This is a convenience method which can be used (or not) by subclasses when the system calls write() (UNIX) or WriteFile() (Windows) are appropriate.

Parameters

[in]	addr	Address of the data to write.
[in]	size	Size in bytes of the data to write.
[out]	written_size	Actually written size in bytes. Can be less than size in case of error in the middle of the write.
[in,out]	iosb	Address of an IOSB structure. If non-null, the stream must be in non-blocking mode. When null, the stream must be in blocking mode (the default). See the description of ts::NonBlockingDevice::IOSB.
[in]	position	This value is only used on Windows with asynchronous I/O on disk file. On Windows, when asynchronous I/O are used on random access files, the file position is not maintained. Each read or write operation is performed at the specified absolute position.

Returns: Error code. When the I/O is non-blocking/asynchronous and pending, return SYS_SUCCESS and iosb->pending is true. Return SYS_EOF when it is no longer possible to write (e.g. broken pipe).

◆ genericSystemRead()

int ts::NonBlockingDevice::genericSystemRead	(	void *	addr,
		size_t	max_size,
		size_t &	ret_size,
		const AbortInterface *	abort,
		NonBlockingDevice::IOSB *	iosb,
		uint64_t	position
	)

protectedinherited

Generic system read operation.

This is a convenience method which can be used (or not) by subclasses when the system calls read() (UNIX) or ReadFile() (Windows) are appropriate.

Parameters

[out]	addr	Address of the buffer for the incoming data.
[in]	max_size	Maximum size in bytes of the buffer.
[out]	ret_size	Returned input size in bytes. If zero, end of file has been reached or an error occurred.
[in]	abort	If non-zero, invoked when I/O is interrupted (in case of user-interrupt, return, otherwise retry).
[in,out]	iosb	Address of an IOSB structure. If non-null, the stream must be in non-blocking mode. When null, the stream must be in blocking mode (the default). See the description of ts::NonBlockingDevice::IOSB.
[in]	position	This value is only used on Windows with asynchronous I/O on disk file. On Windows, when asynchronous I/O are used on random access files, the file position is not maintained. Each read or write operation is performed at the specified absolute position.

Returns: Error code. When the I/O is non-blocking/asynchronous and pending, return SYS_SUCCESS and iosb->pending is true. Return SYS_EOF when it is no longer possible to read.

◆ report()

virtual Report & ts::ReporterBase::report ( ) const

overridevirtualinherited

Access the Report which is associated with this object.

Can be called from another thread only if the Report object is thread-safe.

Returns: A reference to the associated report.

Implements ts::ReporterInterface.

◆ setReport() [1/2]

Report * ts::ReporterBase::setReport ( Report * report )

inherited

Associate this object with another Report to log errors.

Parameters

[in] report Where to report errors. The report object must remain valid as long as this object exists or setReport() is used with another Report object. If report is null, log messages are discarded.

Returns: The address of the previous Report object or a null pointer if there was none.

◆ setReport() [2/2]

ReporterBase * ts::ReporterBase::setReport ( ReporterBase * delegate )

inherited

Associate this object with another ReporterBase to log errors.

Parameters

[in] delegate Use the report of another ReporterBase. If delegate is null, the previous explicit Report is used..

Returns: The address of the previous ReporterBase object or a null pointer if there was none.

◆ muteReport()

bool ts::ReporterBase::muteReport ( bool mute )

inherited

Temporarily mute the associated report.

Parameters

[in] mute It true, report() will return a null report (log messages are discarded), until muteReport() is invoked again with mute set to false.

Returns: Previous state of the mute field.

◆ SilentLevel()

static int ts::ReporterBase::SilentLevel	(	bool	silent,
		int	default_severity = `Severity::Error`
	)

inlinestaticinherited

Compute a log severity level from a "silent" parameter.

Some subclass methods have a "silent" parameter to avoid reporting errors which may be insignificant, typically when closing a device after an error, in which case the close operation may produce other errors if the previous error left the device in an inconsistent state. While those errors should not be displayed as errors, we still display them at debug level.

Parameters

[in]	silent	If true, do not report errors, report debug messages instead.
[in]	default_severity	Default severity, in non-silent mode (error by default).

Returns: Error when silent is false, Debug otherwise.

◆ WriteStreamHelper()

template<class T >
requires std::derived_from<T, StreamInterface>

static bool ts::StreamInterface::WriteStreamHelper	(	T *	obj,
		const void *	addr,
		size_t	size,
		NonBlockingDevice::IOSB *	iosb
	)

inlinestaticprotectedinherited

Implementation helper for fixed-size version of writeStream().

Often, the fixed-size version can be implemented using the variable-size version. However, this works well at a given derivation stage only.

Assume that:

We implement the fixed-size version inside StreamInterface, using the virtual variable-size version.
Class A implements StreamInterface and implements the variable-size version only. The base fixed-size version StreamInterface::writeStream() uses the virtual variable-size version A::writeStream() and it works well.
Class B derives from A. It is an encrypted version of A (think A=TCP, B=TLS). If the implementation of B wants to write raw data (after encryption) calling the fixed-size version A::writeStream(), then this will end up calling the virtual variable-size version B::writeStream(), which will try to encrypt already encrypted data. This is why it is important that each layer of inheritance calls its own version of writeStream().

Template Parameters

T	A subclass of StreamInterface. Write data to the stream. All bytes are written to the stream, blocking or retrying when necessary when the stream is in blocking mode. The base implementation of writeStream() uses the virtual version with a written_size output parameter.

Parameters

[in,out]	obj	Object of class T.
[in]	addr	Address of the data to write.
[in]	size	Size in bytes of the data to write.
[in,out]	iosb	Address of an IOSB structure. If non-null, the stream must be in non-blocking mode. When null, the stream must be in blocking mode (the default). See the description of ts::NonBlockingDevice::IOSB. Important: The parameter iosb should not be used by applications. It should be used only by "reactive classes", which work in combination with a Reactor.

Returns: True on success, false on error or it less than size bytes could be written. In case of non-blocking mode, if the I/O is successfully started but still pending, iosb->pending is set to true and the method returns true.

◆ ReadStreamHelper()

template<class T >
requires std::derived_from<T, StreamInterface>

static bool ts::StreamInterface::ReadStreamHelper	(	T *	obj,
		void *	addr,
		size_t	size,
		const AbortInterface *	abort
	)

inlinestaticprotectedinherited

Implementation helper for fixed-size version of readStream().

See writeStreamHelper() for a rationale.

Template Parameters

T	A subclass of StreamInterface.

Parameters

[in,out]	obj	Object of class T.
[out]	addr	Address of the buffer for the incoming data.
[in]	size	Size in bytes of the buffer.
[in]	abort	If non-zero, invoked when I/O is interrupted (in case of user-interrupt, return, otherwise retry).

Returns: True on success, false on error or it less than size bytes could be read.

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

tsForkPipeOutputStream.h

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ WaitMode

◆ InputMode

◆ OutputMode

Constructor & Destructor Documentation

◆ ForkPipeOutputStream() [1/2]

◆ ForkPipeOutputStream() [2/2]

Member Function Documentation

◆ close()

◆ writeStreamBuffer()

◆ open()

◆ isOpen()

◆ isBroken()

◆ isSynchronous()

◆ getProcessId()

◆ getProcessHandle()

◆ setIgnoreAbort()

◆ getIgnoreAbort()

◆ abortPipeReadWrite()

◆ Launch()

◆ GetOutput()

◆ getReadHandle()

◆ getWriteHandle()

◆ readStream() [1/2]

◆ readStream() [2/2]

◆ writeStream() [1/2]

◆ writeStream() [2/2]

◆ asyncCompletedStream()

◆ isReadStream()

◆ isWriteStream()

◆ endOfStream()

◆ allowSetNonBlocking()

◆ setNonBlocking()

◆ isNonBlocking()

◆ isSupportedByReactor()

◆ IsPendingStatus()

◆ getHandle()

◆ getSocket()

◆ getReadSocket()

◆ getWriteSocket()

◆ checkNonBlocking() [1/2]

◆ checkNonBlocking() [2/2]

◆ setSystemNonBlocking()

◆ genericSystemWrite()

◆ genericSystemRead()

◆ report()

◆ setReport() [1/2]

◆ setReport() [2/2]

◆ muteReport()

◆ SilentLevel()

◆ WriteStreamHelper()

◆ ReadStreamHelper()