xentara-utils v1.2.1
Xentara utilities library
Loading...
Searching...
No Matches
xentara::utils::ipc::NamedPipeStream< Element > Class Template Reference

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

#include <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
stopSourceThe 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
pipeThe 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
pipeNameThe name of the named pipe instance to connect to
Exceptions
std::runtime_errorAn 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
pipeNameThe name of the named pipe instance to connect to
Returns
A named pipe connected to the given address.
Exceptions
std::runtime_errorAn 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
pipeNameThe name of the named pipe instance to connect to
stopSourceThe stop source to associates with the returned pipe
Returns
A named pipe connected to the given address.
Exceptions
std::runtime_errorAn 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
pipeThe 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
stopSourceThe stop source to associates with the named pipe