xentara::utils::ipc::NamedPipe Class Reference

A named pipe for communication with other processes. More...

#include <xentara/utils/ipc/NamedPipe.hpp>

Inheritance diagram for xentara::utils::ipc::NamedPipe:

Public Member Functions
	NamedPipe () noexcept=default
	Default constructor.
	NamedPipe (std::reference_wrapper< const io::StopSource > stopSource) noexcept
	Constructor that associates a stop source with the named pipe.
	~NamedPipe () noexcept=default
	Noexcept Destructor.
internal	operator bool () const noexcept
	Checks whether the object contains a valid named pipe.
auto	setStopSource (std::reference_wrapper< const io::StopSource > stopSource) -> void
	Associates a stop source with the named pipe.
auto	removeStopSource () -> void
	Removes any associated stop source from the named pipe.
auto	connect (std::string_view pipeName) -> void
	Connects the pipe to a specific named pipe instance.
auto	close () noexcept -> void
	Closes the named pipe, if one is open.
Public Member Functions inherited from xentara::utils::io::InputDevice
virtual	~InputDevice () noexcept(false)=0
	Virtual, throwing destructor.
auto	read (std::size_t size) -> core::RawDataBlock
	Reads a block of data of a specific size.
auto	readByte () -> std::byte
	Reads a single byte.
auto	tryReadByte () -> std::optional< std::byte >
	Tries to read a single byte from a device.
auto	readAll () -> core::RawDataBlock
	Reads all remaining data.
auto	readAll (std::size_t maxSize) -> core::RawDataBlock
	Reads all remaining data up to a maximum size.
auto	readChunk () -> core::RawDataBlock
	Reads a single chunk of data.
auto	readChunk (std::size_t maxSize) -> core::RawDataBlock
	Reads a single chunk of data up to a maximum size.
auto	readAvailable () -> std::pair< core::RawDataBlock, bool >
	Reads all immediately available data.
auto	readAvailable (std::size_t maxSize) -> std::pair< core::RawDataBlock, bool >
	Reads immediately available data up to a maximum size.
template<std::size_t kArraySize>
auto	read (std::byte(&array)[kArraySize]) -> void
	Read a block of data into an array.
template<std::size_t kArraySize>
auto	read (std::array< std::byte, kArraySize > &array) -> void
	Read a block of data into an array.
template<std::size_t kArraySize>
auto	readChunk (std::byte(&array)[kArraySize]) -> core::RawDataBlock
	Reads a single chunk of data into an array.
template<std::size_t kArraySize>
auto	readChunk (std::array< std::byte, kArraySize > &array) -> core::RawDataBlock
	Reads a single chunk of data into an array.
template<std::size_t kArraySize>
auto	readAvailable (std::byte(&array)[kArraySize]) -> std::pair< std::size_t, bool >
	Reads immediately available data into an array.
template<std::size_t kArraySize>
auto	readAvailable (std::array< std::byte, kArraySize > &array) -> std::pair< std::size_t, bool >
	Reads immediately available data into an array.
template<std::contiguous_iterator Iterator, std::sized_sentinel_for< Iterator > Sentinel> requires std::same_as<std::remove_volatile_t<std::iter_value_t<Iterator>>, std::byte>
auto	read (Iterator first, Sentinel last) -> void
	Read data to fill an iterator range.
template<std::contiguous_iterator Iterator, std::sized_sentinel_for< Iterator > Sentinel> requires std::same_as<std::iter_value_t<Iterator>, std::byte>
auto	readChunk (Iterator first, Sentinel last) -> Iterator
	Reads a single chunk of data data into an iterator range.
template<std::contiguous_iterator Iterator, std::sized_sentinel_for< Iterator > Sentinel> requires std::same_as<std::iter_value_t<Iterator>, std::byte>
auto	readAvailable (Iterator first, Sentinel last) -> std::pair< Iterator, bool >
	Reads immediately available data into an iterator range.
auto	read (std::byte *buffer, std::size_t size) -> void
	Read a block of data into a buffer.
auto	readChunk (std::byte *buffer, std::size_t size) -> std::size_t
	Reads a single chunk of data into a buffer.
auto	readAvailable (std::byte *buffer, std::size_t size) -> std::pair< std::size_t, bool >
	Reads immediately available data into a buffer.
auto	availableReadSize () const -> std::optional< std::size_t >
	Get the number of bytes for reading without blocking.
auto	remainingReadSize () const -> std::optional< std::size_t >
	Get the number of bytes remaining before the end of the device.
auto	readPosition () const -> std::optional< std::size_t >
	Gets the current read position within the device.
auto	setReadPosition (std::size_t position) -> std::optional< std::size_t >
	Sets the current read position within the device.
auto	moveReadPosition (std::ptrdiff_t offset, std::ios_base::seekdir origin=std::ios_base::cur) -> std::optional< std::size_t >
	Advances or retreats the current read position within the device.
auto	advanceReadPosition (std::size_t offset) -> std::optional< std::size_t >
	Advance the current read position within the device.
auto	rewind () -> bool
	Sets the current read position to the beginning of the device.
auto	waitForData () -> void
	Waits for more read data to become available.
auto	waitForData (std::optional< std::chrono::nanoseconds > timeout) -> bool
	Waits for more read data to become available within a certain time.
auto	readTimeout () const noexcept -> std::chrono::nanoseconds
	Returns the read timeout for communication devices.
auto	throwEndOfStreamError () const -> void
	Throws an error denoting the end of the stream.
Public Member Functions inherited from xentara::utils::io::DeviceBase
virtual	~DeviceBase () noexcept(false)=0
	Virtual, throwing destructor.
auto	deviceDescription () const -> std::string
	Get a description of the device.
Public Member Functions inherited from xentara::utils::io::OutputDevice
virtual	~OutputDevice () noexcept(false)=0
	Virtual, throwing destructor.
template<std::ranges::contiguous_range Data> requires std::same_as<std::remove_cv_t<std::ranges::range_value_t<Data>>, std::byte>
auto	write (const Data &data) -> void
	Writes a block of data.
auto	writeByte (std::byte byte) -> void
	Write a single byte.
template<std::ranges::contiguous_range Data> requires std::same_as<std::remove_cv_t<std::ranges::range_value_t<Data>>, std::byte>
auto	writeChunk (const Data &data) -> std::ranges::range_size_t< Data >
	Writes a single chunk of data contained in an iterator range.
template<std::ranges::contiguous_range Data> requires std::same_as<std::remove_cv_t<std::ranges::range_value_t<Data>>, std::byte>
auto	tryWrite (const Data &data) -> std::ranges::range_size_t< Data >
	Write as much of a data block as is possible without blocking.
auto	tryWriteByte (std::byte byte) -> bool
	Write a single byte, if this can be done without blocking.
template<std::contiguous_iterator Iterator, std::sized_sentinel_for< Iterator > Sentinel> requires std::same_as<std::remove_cv_t<std::iter_value_t<Iterator>>, std::byte>
auto	write (Iterator first, Sentinel last) -> void
	Writes the data contained in an iterator range.
template<std::contiguous_iterator Iterator, std::sized_sentinel_for< Iterator > Sentinel> requires std::same_as<std::remove_cv_t<std::iter_value_t<Iterator>>, std::byte>
auto	writeChunk (Iterator first, Sentinel last) -> Iterator
	Writes a single chunk of data from an an iterator range.
template<std::contiguous_iterator Iterator, std::sized_sentinel_for< Iterator > Sentinel> requires std::same_as<std::iter_value_t<Iterator>, std::byte>
auto	tryWrite (Iterator first, Sentinel last) -> Iterator
	Write as much of the data contained in an iterator range as is possible without blocking.
auto	write (const std::byte *data, std::size_t size) -> void
	Write a block of data.
auto	writeChunk (const std::byte *data, std::size_t size) -> std::size_t
	Writes a single chunk of data.
auto	tryWrite (const std::byte *data, std::size_t size) -> std::size_t
	Write as much of a data block as is possible without blocking.
auto	writePosition () const -> std::optional< std::size_t >
	Gets the current write position within the device.
auto	setWritePosition (std::size_t position) -> std::optional< std::size_t >
	Sets the current write position within the device.
auto	moveWritePosition (std::ptrdiff_t offset, std::ios_base::seekdir origin=std::ios_base::cur) -> std::optional< std::size_t >
	Advances or retreats the current write position within the device.
auto	waitUntilWritable (std::chrono::nanoseconds timeout) -> bool
	Waits for the device to be able to accept more write data within a certain time.
auto	writeTimeout () const noexcept -> std::chrono::nanoseconds
	Returns the write timeout for communication devices.

Static Public Member Functions
static auto	connectedPipe (std::string_view pipeName) -> NamedPipe
	Creates a new pipe connected to a specific named pipe instance.
static auto	connectedPipe (std::string_view pipeName, std::reference_wrapper< const io::StopSource > stopSource) -> NamedPipe
	Creates a new pipe connected to a specific named pipe instance.
static auto	enumerateNamedPipes (std::string_view pattern) -> std::vector< std::string >
	Create a list of all existing named pipes that match a certain pattern.

Additional Inherited Members
Protected Member Functions inherited from xentara::utils::io::InputDevice
virtual auto	doRead (std::byte *buffer, std::size_t size) -> std::optional< std::size_t >=0
	Called by the framework to read available data into a buffer up to a maximum size.
virtual auto	doThrowEndOfStreamError () const -> void
	Called by the framework to throw an error denoting the end of the stream.
virtual auto	doGetAvailableReadSize () const -> std::optional< std::size_t >
	Called by the framework to get the number of bytes that will be read by the next call to doRead().
virtual auto	doGetRemainingReadSize () const -> std::optional< std::size_t >
	Called by the framework to get the number of bytes remaining before the end of the device.
virtual auto	doWaitForData (std::optional< std::chrono::nanoseconds > timeout) -> bool
	Called by the framework to wait for more read data to become available.
virtual auto	doWaitForDataAndRead (std::byte *buffer, std::size_t size, std::chrono::nanoseconds timeout) -> std::optional< std::size_t >
	Called by the framework to wait for read data to become available, and then read it.
virtual auto	doGetReadTimeout () const noexcept -> std::chrono::nanoseconds
	Called by the framework to get the read timeout.
virtual auto	doGetReadPosition () const -> std::optional< std::size_t >
	Called by the framework to get the current read position within the device.
virtual auto	doSetReadPosition (std::size_t position) -> std::optional< std::size_t >
	Called by the framework to set the current read position within the device.
virtual auto	doMoveReadPosition (std::ptrdiff_t offset, std::ios_base::seekdir origin=std::ios_base::cur) -> std::optional< std::size_t >
	Called by the framework to advance or retreat the current read position within the device.
virtual auto	doAdvanceReadPosition (std::size_t offset) -> std::optional< std::size_t >
	Called by the framework to advance the current read position within the device.
Protected Member Functions inherited from xentara::utils::io::DeviceBase
virtual auto	doGetDeviceDescription () const -> std::string=0
	Called by the framework to get a description of the device.
Protected Member Functions inherited from xentara::utils::io::OutputDevice
virtual auto	doWrite (const std::byte *data, std::size_t size) -> std::size_t=0
	Called by the framework to write data up to a maximum size.
virtual auto	doWaitUntilWritable (std::optional< std::chrono::nanoseconds > timeout) -> bool
	Called by the framework to wait for the device to be able to accept more write data with an optional timeout.
virtual auto	doWaitUntilWritableAndWrite (const std::byte *data, std::size_t size, std::chrono::nanoseconds timeout) -> std::size_t
	Called by the framework to wait for the device to be able to accept more write data, and then write to it.
virtual auto	doGetWriteTimeout () const noexcept -> std::chrono::nanoseconds
	Called by the framework to get the write timeout.
virtual auto	doGetWritePosition () const -> std::optional< std::size_t >
	Called by the framework to get the current write position within the device.
virtual auto	doSetWritePosition (std::size_t position) -> std::optional< std::size_t >
	Called by the framework to set the current write position within the device.
virtual auto	doMoveWritePosition (std::ptrdiff_t offset, std::ios_base::seekdir origin=std::ios_base::cur) -> std::optional< std::size_t >
	Called by the framework to advance or retreat the current write position within the device.

Detailed Description

A named pipe for communication with other processes.

Constructor & Destructor Documentation

NamedPipe() [1/2]

xentara::utils::ipc::NamedPipe::NamedPipe ( )

defaultnoexcept

Default constructor.

This constructor creates an invalid object that must be connected using connect() or assigned a valid pipe returned by NamedPipeServer::accept().

NamedPipe() [2/2]

xentara::utils::ipc::NamedPipe::NamedPipe ( std::reference_wrapper< const io::StopSource >  stopSource )

explicitnoexcept

Constructor that associates a stop source with the named pipe.

This constructor creates an invalid object that must be connected using connect() or assigned a valid pipe returned by NamedPipeServer::accept().

Attention

The stop source will be overwritten if you assign a pipe returned by NamedPipeServer::accept() to this object.

Parameters

stopSource

The stop source to associate with the named pipe

~NamedPipe()

xentara::utils::ipc::NamedPipe::~NamedPipe ( )

defaultnoexcept

Noexcept Destructor.

This class's constructor never throws an exception

Member Function Documentation

close()

auto xentara::utils::ipc::NamedPipe::close ( ) -> void

noexcept

Closes the named pipe, if one is open.

connect()

auto xentara::utils::ipc::NamedPipe::connect

(

std::string_view

pipeName

)

-> void

Connects the pipe to a specific named pipe instance.

Parameters

pipeName

The name of the named pipe instance to connect to

Exceptions

std::runtime_error

An error occurred connecting to the pipe

connectedPipe() [1/2]

static auto xentara::utils::ipc::NamedPipe::connectedPipe ( std::string_view  pipeName ) -> NamedPipe

static

Creates a new pipe connected to a specific named pipe instance.

Parameters

pipeName

The name of the named pipe instance to connect to

Returns

A named pipe connected to the given address.

Exceptions

std::runtime_error

An error occurred connecting to the pipe

connectedPipe() [2/2]

static auto xentara::utils::ipc::NamedPipe::connectedPipe ( std::string_view  pipeName, std::reference_wrapper< const io::StopSource >  stopSource  ) -> NamedPipe

static

Creates a new pipe connected to a specific named pipe instance.

Parameters

pipeName	The name of the named pipe instance to connect to
stopSource	The stop source to associate with the returned pipe

Returns

A named pipe connected to the given address.

Exceptions

std::runtime_error

An error occurred connecting to the pipe

enumerateNamedPipes()

static auto xentara::utils::ipc::NamedPipe::enumerateNamedPipes ( std::string_view  pattern ) -> std::vector< std::string >

static

Create a list of all existing named pipes that match a certain pattern.

Parameters

pattern

An ECMAScript regular expression pattern used to find the names

Returns

the names of all existing named pipes that match the pattern

operator bool()

internal xentara::utils::ipc::NamedPipe::operator bool ( ) const

explicitnoexcept

Checks whether the object contains a valid named pipe.

Returns

Returns true if the object contains a valid named pipe, or false if the object is default constructed, has been moved away using std::move() etc.

removeStopSource()

auto xentara::utils::ipc::NamedPipe::removeStopSource

(

)

-> void

Removes any associated stop source from the named pipe.

setStopSource()

auto xentara::utils::ipc::NamedPipe::setStopSource

(

std::reference_wrapper< const io::StopSource >

stopSource

)

-> void

Associates a stop source with the named pipe.

If you set a stop source, any read or write operations will throw an exception of type io::StopRequested if a stop is requested on the stop source.

Parameters

stopSource

The stop source to associate with the named pipe