xentara::utils::ipc::NamedPipeStream< Element > Class Template Reference

@ Class for named pipes read/write incorporating output and input device streams More...

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

Inheritance diagram for xentara::utils::ipc::NamedPipeStream< Element >:

Public Member Functions
	NamedPipeStream ()=default
	Default constructor.
	NamedPipeStream (std::reference_wrapper< const io::StopSource > stopSource) noexcept
	Constructor that associates a stop source with the named pipe.
	~NamedPipeStream () noexcept=default
	Destructor.
	NamedPipeStream (NamedPipe &&pipe)
	Constructor that takes ownership of an existing pipe.
internal auto	operator= (NamedPipe &&pipe) -> NamedPipeStream &
	Assignment operator that takes ownership of an existing pipe.
	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::AbstractBufferedInputStream< Element >
	AbstractBufferedInputStream ()=default
	Default constructor Creates a stream without a buffer.
Public Member Functions inherited from xentara::utils::io::InputStream< Element >
virtual	~InputStream () noexcept(false)=0
	Virtual, throwing destructor.
auto	readElement () -> Element
	Read a single element from the stream.
auto	tryReadElement () -> std::optional< Element >
	Tries to read a single element from a stream.
template<Element kNoMoreData>
auto	readElementOr () -> Element
	Tries to read a single element from a stream.
auto	peek () -> Element
	Look at the next element in the stream without actually reading it.
auto	tryPeek () -> std::optional< Element >
	Look at the next element in the stream without actually reading it.
template<Element kNoMoreData>
auto	peekOr () -> Element
	Look at the next element in the stream without actually reading it.
auto	readFromBuffer (std::size_t maxSize) -> std::span< const Element >
	Reads data from the buffer only.
auto	eof () -> bool
	Checks if the end of the stream has been reached.
template<Element... kAllowedElements>
auto	readElementIf () -> std::optional< Element >
	Read an element from the stream if it is one of a list of allowed elements.
template<std::predicate< Element > Predicate>
auto	readElementIf (Predicate predicate) -> std::optional< Element >
	Read an element from the stream if it fits a predicate.
template<Element kFallback, Element... kAllowedElements>
auto	readElementIfOr () -> Element
	Read an element from the stream if it is one of a list of allowed elements.
template<Element kFallback, std::predicate< Element > Predicate>
auto	readElementIfOr (Predicate predicate) -> Element
	Read an element from the stream if it fits a predicate.
template<tools::Allocator< Element > Allocator = std::allocator<Element>> requires (!tools::CharType<Element>)
auto	read (typename std::allocator_traits< Allocator >::size_type size, const Allocator &allocator=Allocator()) -> core::RawVector< Element, Allocator >
	Read a block of data of a specific size.
template<typename CharTraits = std::char_traits<Element>, tools::Allocator< Element > Allocator = std::allocator<Element>> requires tools::CharType<Element>
auto	read (typename std::allocator_traits< Allocator >::size_type size, const Allocator &allocator=Allocator()) -> std::basic_string< Element, CharTraits, Allocator >
	Read a block of text of a specific size.
template<std::size_t kArraySize>
auto	read (Element(&array)[kArraySize]) -> void
	Read a block of data into an array.
template<std::size_t kArraySize>
auto	read (std::array< Element, kArraySize > &array) -> void
	Read a block of 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>>, Element>
auto	read (Iterator first, Sentinel last) -> void
	Read a block of data into an iterator range.
auto	read (Element *buffer, std::size_t size) -> void
	Read a block of data into a buffer.
template<Element... kTerminations> requires (!tools::CharType<Element>)
auto	readUntil () -> core::RawVector< Element >
	Reads all elements until a termination is found.
template<tools::Allocator< Element > Allocator, Element... kTerminations> requires (!tools::CharType<Element>)
auto	readUntil (const Allocator &allocator=Allocator()) -> core::RawVector< Element, Allocator >
	Reads all elements until a termination is found.
template<tools::Allocator< Element > Allocator = std::allocator<Element>, std::predicate< Element > Predicate> requires (!tools::CharType<Element>)
auto	readUntil (Predicate predicate, const Allocator &allocator=Allocator()) -> core::RawVector< Element, Allocator >
	Skips all elements until a termination element that fits a predicate.
template<Element... kTerminations> requires tools::CharType<Element>
auto	readUntil () -> std::basic_string< Element >
	Reads all characters until a termination is found.
template<typename CharTraits , Element... kTerminations> requires tools::CharType<Element>
auto	readUntil () -> std::basic_string< Element, CharTraits >
	Reads all characters until a termination is found.
template<typename CharTraits , tools::Allocator< Element > Allocator, Element... kTerminations> requires tools::CharType<Element>
auto	readUntil (const Allocator &allocator=Allocator()) -> std::basic_string< Element, CharTraits, Allocator >
	Reads all characters until a termination is found.
template<typename CharTraits = std::char_traits<Element>, tools::Allocator< Element > Allocator = std::allocator<Element>, std::predicate< Element > Predicate> requires tools::CharType<Element>
auto	readUntil (Predicate predicate, const Allocator &allocator=Allocator()) -> std::basic_string< Element, CharTraits, Allocator >
	Skips all characters until a termination character that fits a predicate.
auto	skipElement () -> void
	Skips a single element from the stream.
auto	trySkipElement () -> bool
	Tries to skip a single element from a stream.
auto	skip (std::size_t size) -> void
	Skips a block of data.
template<Element... kSkippableElements>
auto	skipWhile () -> std::size_t
	Skips all elements than appear in a list of skippable elements.
template<std::predicate< Element > Predicate>
auto	skipWhile (Predicate predicate) -> std::size_t
	Skips all elements that fit a predicate.
auto	readPosition () const -> std::optional< ReadPosition >
	Gets the current read position within the stream.
auto	setReadPosition (ReadPosition position) -> void
	Sets the current read position within the device.
auto	rewind () -> void
	Sets the current read position to the beginning of the stream.
template<typename CharTraits = std::char_traits<Element>, tools::Allocator< Element > Allocator = std::allocator<Element>> requires tools::CharType<Element>
auto	readLine (const Allocator &allocator=Allocator()) -> std::basic_string< Element, CharTraits, Allocator >
	Reads a single line.
auto	skipLine () -> std::size_t
	Skips the rest of the line.
template<typename CharTraits = std::char_traits<Element>, tools::Allocator< Element > Allocator = std::allocator<Element>> requires tools::CharType<Element>
auto	readWord (const Allocator &allocator=Allocator()) -> std::basic_string< Element, CharTraits, Allocator >
	Reads a single whitespace-separated word.
auto	skipWord () -> std::size_t
	Skips the rest of a whitespace-separated word.
auto	skipLineEnding () -> bool
	Skips a single line termination.
auto	skipWhitespace () -> bool
	Skips all ASCII whitespace elements.
auto	readByte () -> Element
	Alternate name for readElement()
auto	tryReadByte () -> std::optional< Element >
	Alternate name for tryReadElement()
template<Element kNoMoreData> requires (!tools::CharType<Element>)
auto	readByteOr () -> Element
	Alternate name for readElementOr()
template<Element... kAllowedElements> requires (!tools::CharType<Element>)
auto	readByteIf () -> std::optional< Element >
	Alternate name for readElementIf()
template<std::predicate< Element > Predicate> requires (!tools::CharType<Element>)
auto	readByteIf (Predicate predicate) -> std::optional< Element >
	Alternate name for readElementIf().
template<Element kFallback, Element... kAllowedElements> requires (!tools::CharType<Element>)
auto	readByteIfOr () -> Element
	Alternate name for readElementIfOr()
template<Element kFallback, std::predicate< Element > Predicate> requires (!tools::CharType<Element>)
auto	readByteIfOr (Predicate predicate) -> Element
	Alternate name for readElementIfOr().
auto	skipByte () -> void
	Alternate name for skipElement()
auto	trySkipByte () -> bool
	Alternate name for trySkipElement() for character streams.
auto	readChar () -> Element
	Alternate name for readElement()
auto	tryReadChar () -> std::optional< Element >
	Alternate name for tryReadElement()
template<Element kNoMoreData> requires tools::CharType<Element>
auto	readCharOr () -> Element
	Alternate name for readElementOr()
template<Element... kAllowedElements> requires tools::CharType<Element>
auto	readCharIf () -> std::optional< Element >
	Alternate name for readElementIf()
template<std::predicate< Element > Predicate> requires tools::CharType<Element>
auto	readCharIf (Predicate predicate) -> std::optional< Element >
	Alternate name for readElementIf().
template<Element kFallback, Element... kAllowedElements> requires tools::CharType<Element>
auto	readCharIfOr () -> Element
	Alternate name for readElementIfOr()
template<Element kFallback, std::predicate< Element > Predicate> requires tools::CharType<Element>
auto	readCharIfOr (Predicate predicate) -> Element
	Alternate name for readElementIfOr().
auto	skipChar () -> void
	Alternate name for skipElement()
auto	trySkipChar () -> bool
	Alternate name for trySkipElement() for character streams.
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.
Public Member Functions inherited from xentara::utils::io::StreamBase
virtual	~StreamBase () noexcept(false)=0
	Virtual, throwing destructor.
auto	streamDescription () const -> std::string
	Get a description of the device.
Public Member Functions inherited from xentara::utils::io::AbstractBufferedOutputStream< Element >
	AbstractBufferedOutputStream ()=default
	Default constructor Creates a stream without a buffer.
Public Member Functions inherited from xentara::utils::io::OutputStream< Element >
virtual	~OutputStream () noexcept(false)=0
	Virtual, throwing destructor.
auto	write (Element element) -> void
	Write a single element to the stream.
template<std::ranges::contiguous_range Data> requires std::same_as<std::remove_cv_t<std::ranges::range_value_t<Data>>, Element>
auto	write (const Data &data) -> void
	Write a block of data.
template<std::size_t kDataSize>
auto	write (const Element(&data)[kDataSize]) -> void
	Write a block of data contained in an array.
template<std::contiguous_iterator Iterator, std::sized_sentinel_for< Iterator > Sentinel> requires std::same_as<std::remove_cv_t<std::iter_value_t<Iterator>>, Element>
auto	write (Iterator first, Sentinel last) -> void
	Write a block of data contained in an iterator range.
auto	write (const Element *data, std::size_t size) -> void
	Write a block of data contained in a region of memory.
auto	write (const Element *nullTerminatedString) -> void
	Write a NULL-teminated string.
auto	flush () -> void
	Flushes the buffer.

Static Public Member Functions
static auto	connectedPipe (std::string_view pipeName) -> NamedPipeStream
	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) -> NamedPipeStream
	Creates a new pipe connected to a specific named pipe instance.

Protected Member Functions
auto	doGetStreamDescription () const -> std::string final
	Implementation of InputStream::doGetStreamDescription()
Protected Member Functions inherited from xentara::utils::io::AbstractDeviceInputStream< Element >
virtual auto	inputDevice () noexcept -> InputDevice &=0
	Called by the framework to get the device.
auto	doRead (Element *buffer, std::size_t size, bool waitForData) -> std::optional< std::size_t > final
	Implementation of InputStream::doRead()
virtual auto	doThrowEndOfStreamError () const -> void final
	Implementation of InputStream::doRead()
auto	doWaitForData (std::optional< std::chrono::nanoseconds > timeout) -> bool final
	Implementation of InputStream::doWaitForData()
auto	doGetReadPosition () const -> std::optional< std::size_t > final
	Implementation of InputStream::doGetReadPosition()
auto	doSetReadPosition (std::size_t position) -> bool final
	Implementation of InputStream::doSetReadPosition()
auto	doAdvanceReadPosition (std::size_t offset) -> std::optional< std::size_t > final
	Implementation of InputStream::doAdvanceReadPosition()
Protected Member Functions inherited from xentara::utils::io::AbstractBufferedInputStream< Element >
auto	resetInputBuffer (std::size_t bufferSizeHint=kDefaultBufferSize) -> void
	Resets the buffer.
auto	destroyInputBuffer () -> void
	Destroys the buffer.
Protected Member Functions inherited from xentara::utils::io::InputStream< Element >
	InputStream () noexcept=default
	Default constructor.
	InputStream (Element *bufferBegin, Element *bufferEnd) noexcept
	Constructor that sets an initially empty buffer.
	InputStream (Element *bufferBegin, Element *bufferEnd, Element *dataBegin, Element *dataEnd) noexcept
	Constructor that sets a buffer that possibly already contains some data.
	InputStream (InputStream &&other) noexcept
	Move constructor.
auto	operator= (InputStream &&rhs) noexcept -> InputStream &
	Move assignemnt operator.
auto	setReadBuffer (Element *bufferBegin, Element *bufferEnd) noexcept -> void
	Sets a new empty buffer.
auto	setReadBuffer (Element *bufferBegin, Element *bufferEnd, Element *dataBegin, Element *dataEnd) noexcept -> void
	Sets the buffer.
auto	setReadData (Element *dataBegin, Element *dataEnd) noexcept -> void
	Sets the position of the data within the buffer.
auto	readBufferBegin () const -> Element *
	Reads back the buffer start position.
auto	readBufferEnd () const -> Element *
	Reads back the buffer end position.
auto	readBufferSize () const -> std::size_t
	Gets the buffer size.
auto	readDataBegin () const -> Element *
	Returns the beginning of the unconsumed data in the buffer.
auto	readDataEnd () const -> Element *
	Returns the end of the data in the buffer.
auto	readDataSize () const -> std::size_t
	Returns the size of the unconsumed data in the buffer.
virtual auto	doReplenishReadBuffer (bool waitForData) -> bool
	Called by the framework to place more data into the buffer when it is exhausted.
Protected Member Functions inherited from xentara::utils::io::AbstractDeviceOutputStream< Element >
virtual auto	outputDevice () noexcept -> OutputDevice &=0
	Called by the framework to get the device.
auto	doWrite (const Element *data, std::size_t size) -> std::size_t final
	Implementation of InputStream::doWrite()
Protected Member Functions inherited from xentara::utils::io::AbstractBufferedOutputStream< Element >
auto	resetOutputBuffer (std::size_t bufferSizeHint=kDefaultBufferSize) -> void
	Resets the buffer.
auto	destroyOutputBuffer () -> void
	Destroys the buffer.
Protected Member Functions inherited from xentara::utils::io::OutputStream< Element >
	OutputStream () noexcept=default
	Default constructor.
	OutputStream (Element *bufferBegin, Element *bufferEnd) noexcept
	Constructor that sets an initially empty buffer.
	OutputStream (Element *bufferBegin, Element *bufferEnd, Element *dataEnd) noexcept
	Constructor that sets a buffer that possibly already contains some data.
	OutputStream (OutputStream &&other) noexcept
	Move constructor.
auto	operator= (OutputStream &&rhs) noexcept -> OutputStream &
	Move assignemnt operator.
auto	setWriteBuffer (Element *bufferBegin, Element *bufferEnd) noexcept -> void
	Sets a new empty buffer.
auto	setWriteBuffer (Element *bufferBegin, Element *bufferEnd, Element *dataEnd) noexcept -> void
	Sets the buffer.
auto	setWriteDataEnd (Element *dataEnd) noexcept -> void
	Sets the end of the data within the buffer.
auto	writeBufferBegin () const -> Element *
	Writes back the buffer start position.
auto	writeBufferEnd () const -> Element *
	Writes back the buffer end position.
auto	writeBufferSize () const -> std::size_t
	Gets the buffer size.
auto	writeDataBegin () const -> Element *
	Returns the beginning of data in the buffer.
auto	writeDataEnd () const -> Element *
	Returns the end of the data in the buffer.
auto	writeDataSize () const -> std::size_t
	Returns the size of the unwritten data in the buffer.
auto	freeBufferBegin () const -> Element *
	Returns the beginning of the free region of the buffer.
auto	freeBufferSize () const -> std::size_t
	Returns the size of the unwritten data in the buffer.
virtual auto	doFlushWriteBuffer () -> void
	Called by the framework to write the buffered data to the underlying device once it is full.

Additional Inherited Members
Public Types inherited from xentara::utils::io::InputStream< Element >
using	element_type = Element
	The element type.
Public Types inherited from xentara::utils::io::OutputStream< Element >
using	element_type = Element
	The element type.
Static Protected Attributes inherited from xentara::utils::io::AbstractBufferedInputStream< Element >
static const std::size_t	kDefaultBufferSize
	The default buffer size.
Static Protected Attributes inherited from xentara::utils::io::AbstractBufferedOutputStream< Element >
static const std::size_t	kDefaultBufferSize
	The default buffer size.

Detailed Description

template<io::StreamElement Element>
requires (sizeof(Element) == sizeof(std::byte))
class xentara::utils::ipc::NamedPipeStream< Element >

@ Class for named pipes read/write incorporating output and input device streams

Constructor & Destructor Documentation

NamedPipeStream() [1/3]

template<io::StreamElement Element>

xentara::utils::ipc::NamedPipeStream< Element >::NamedPipeStream ( )

default

Default constructor.

NamedPipeStream() [2/3]

template<io::StreamElement Element>

xentara::utils::ipc::NamedPipeStream< Element >::NamedPipeStream ( 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 associates with the named pipe

~NamedPipeStream()

template<io::StreamElement Element>

xentara::utils::ipc::NamedPipeStream< Element >::~NamedPipeStream ( )

defaultnoexcept

Destructor.

NamedPipeStream() [3/3]

template<io::StreamElement Element>

xentara::utils::ipc::NamedPipeStream< Element >::NamedPipeStream

(

NamedPipe &&

pipe

)

Constructor that takes ownership of an existing pipe.

Parameters

pipe	The pipe to use

Member Function Documentation

close()

template<io::StreamElement Element>

auto xentara::utils::ipc::NamedPipeStream< Element >::close ( ) -> void

noexcept

Closes the named pipe, if one is open.

connect()

template<io::StreamElement Element>

auto xentara::utils::ipc::NamedPipeStream< Element >::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]

template<io::StreamElement Element>

static auto xentara::utils::ipc::NamedPipeStream< Element >::connectedPipe ( std::string_view  pipeName ) -> NamedPipeStream

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]

template<io::StreamElement Element>

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

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 associates with the returned pipe

Returns

A named pipe connected to the given address.

Exceptions

std::runtime_error

An error occurred connecting to the pipe

doGetStreamDescription()

template<io::StreamElement Element>

auto xentara::utils::ipc::NamedPipeStream< Element >::doGetStreamDescription ( ) const -> std::string

finalprotectedvirtual

Implementation of InputStream::doGetStreamDescription()

Reimplemented from xentara::utils::io::AbstractDeviceInputStream< Element >.

operator bool()

template<io::StreamElement Element>

xentara::utils::ipc::NamedPipeStream< Element >::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.

operator=()

template<io::StreamElement Element>

internal auto xentara::utils::ipc::NamedPipeStream< Element >::operator=

(

NamedPipe &&

pipe

)

-> NamedPipeStream &

Assignment operator that takes ownership of an existing pipe.

Parameters

pipe	The pipe to use

Returns

A reference to this object

removeStopSource()

template<io::StreamElement Element>

auto xentara::utils::ipc::NamedPipeStream< Element >::removeStopSource

(

)

-> void

Removes any associated stop source from the named pipe.

setStopSource()

template<io::StreamElement Element>

auto xentara::utils::ipc::NamedPipeStream< Element >::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 associates with the named pipe