Encapsulate a system pipe, UNIX or Windows. More...

#include <tsSysPipe.h>

Inheritance diagram for ts::SysPipe:

[legend]

Collaboration diagram for ts::SysPipe:

[legend]

Public Types
enum	Flags { NONE = 0x0000 , READ_ASYNC = 0x0001 , WRITE_ASYNC = 0x0002 , READ_CLOEXEC = 0x0004 , WRITE_CLOEXEC = 0x0008 , READ_INHERIT = 0x0010 , WRITE_INHERIT = 0x0020 }
	Pipe creation flags. More...

Public Member Functions
	SysPipe (Report *report)
	Constructor.

	SysPipe (ReporterBase *delegate)
	Constructor.

virtual	~SysPipe () override
	Virtual destructor.

bool	close (bool silent=false)
	Close the pipe file descriptors which are not "fetched".

bool	create (Flags flags=NONE, size_t buffer_size=0)
	Create the pipe and open the two file descriptors.

SysHandleType	fetchRead ()
	"Fetch" the read file descriptor of the pipe.

SysHandleType	fetchWrite ()
	"Fetch" the write file descriptor of the pipe.

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

SysHandleType	peekRead ()
	"Peek" the read file descriptor of the pipe.

SysHandleType	peekWrite ()
	"Peek" the write file descriptor of the pipe.

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

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.

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

Detailed Description

Encapsulate a system pipe, UNIX or Windows.

A pipe has two file descriptors / system handles, one for the write end, one for the read end. This class is useful to create pipes, fetch "useful" file descriptors (e.g. to pass to a child process), and let the unused file descriptors be closed in the destructor. This is a safe way to never forget to close unused file descriptors, regardless of error patch.

Once open, the file descriptors / system handles can be either "fetched" or "peeked".

When the application "fetches" a file descriptor, the responsibility of the file descriptor is passed to the application. The SysPipe object no longer knows it and it won't be closed by the SysPipe object. This is typically what should be done when an end of the pipe shall be transmitted to a child process.
When the application "peeks" a file descriptor, its value is returned but it remains under the responsibility of the SysPipe object and will be closed with the SysPipe object.

Windows specificities

On Windows, asynchronous I/O are not supported in anonymous pipes (as created by CreatePipe).

https://learn.microsoft.com/en-us/windows/win32/ipc/anonymous-pipe-operations
https://stackoverflow.com/a/419736 Overlapped I/O can be used on named pipes only.
https://learn.microsoft.com/en-us/windows/win32/ipc/named-pipe-server-using-overlapped-i-o
https://learn.microsoft.com/en-us/windows/win32/ipc/named-pipe-client

Member Enumeration Documentation

◆ Flags

enum ts::SysPipe::Flags

Pipe creation flags.

Enumerator
NONE	No creation flag, use all default.
READ_ASYNC	Set the read end in non-blocking / asynchronous mode.
WRITE_ASYNC	Set the write end in non-blocking / asynchronous mode.
READ_CLOEXEC	Set the flag "close on exe" on the read end (UNIX only).
WRITE_CLOEXEC	Set the flag "close on exe" on the write end (UNIX only).
READ_INHERIT	The read end must be inherited in children processes (Windows only).
WRITE_INHERIT	The write end must be inherited in children processes (Windows only).

Constructor & Destructor Documentation

◆ SysPipe() [1/2]

ts::SysPipe::SysPipe ( Report * report )

inlineexplicit

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.

◆ SysPipe() [2/2]

ts::SysPipe::SysPipe ( ReporterBase * delegate )

inlineexplicit

Constructor.

Parameters

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

◆ ~SysPipe()

virtual ts::SysPipe::~SysPipe ( )

overridevirtual

Virtual destructor.

The file descriptor which were not "fetched" are closed.

Member Function Documentation

◆ create()

bool ts::SysPipe::create	(	Flags	flags = `NONE`,
		size_t	buffer_size = `0`
	)

Create the pipe and open the two file descriptors.

Parameters

[in]	flags	Creation flags.
[in]	buffer_size	The pipe buffer size in bytes, on Windows. Zero means default. Ignored on UNIX.

Returns: True on success, false on error.

◆ close()

bool ts::SysPipe::close ( bool silent = false )

Close the pipe file descriptors which are not "fetched".

Parameters

[in] silent If true, do not report errors.

Returns: True on success, false on error.

◆ peekRead()

SysHandleType ts::SysPipe::peekRead ( )

inline

"Peek" the read file descriptor of the pipe.

The file descriptor remains in this object and will be closed when this object is closed.

Returns: The read file descriptor of the pipe or SYS_HANDLE_INVALID if there is none.

◆ peekWrite()

SysHandleType ts::SysPipe::peekWrite ( )

inline

"Peek" the write file descriptor of the pipe.

The file descriptor remains in this object and will be closed when this object is closed.

Returns: The write file descriptor of the pipe or SYS_HANDLE_INVALID if there is none.

◆ fetchRead()

SysHandleType ts::SysPipe::fetchRead ( )

"Fetch" the read file descriptor of the pipe.

The file descriptor is then removed from this object and will not be closed when this object is closed. This is typically used when we need the file descriptor to keep it open for later usage. When there is no read file descriptor in this object, an error is reported.

Returns: The read file descriptor of the pipe or SYS_HANDLE_INVALID if there is none.

◆ fetchWrite()

SysHandleType ts::SysPipe::fetchWrite ( )

"Fetch" the write file descriptor of the pipe.

The file descriptor is then removed from this object and will not be closed when this object is closed. This is typically used when we need the file descriptor to keep it open for later usage. When there is no write file descriptor in this object, an error is reported.

Returns: The write file descriptor of the pipe or SYS_HANDLE_INVALID if there is none.

◆ 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.

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

tsSysPipe.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Windows specificities

Member Enumeration Documentation

◆ Flags

Constructor & Destructor Documentation

◆ SysPipe() [1/2]

◆ SysPipe() [2/2]

◆ ~SysPipe()

Member Function Documentation

◆ create()

◆ close()

◆ peekRead()

◆ peekWrite()

◆ fetchRead()

◆ fetchWrite()

◆ report()

◆ setReport() [1/2]

◆ setReport() [2/2]

◆ muteReport()

◆ SilentLevel()