Queue BasicReader class. More...

#include <reader.hpp>

Public Member Functions
Accessors
char const *	TopicName () const noexcept
	Get queue topic name.

constexpr bool	IsClosed () const noexcept
	Query whether queue is closed or not.

constexpr size_t	Capacity () const noexcept
	Query queue capacity, which is the number of elements the queue can hold.

constexpr size_t	Size () const noexcept
	Query number of elements in the queue.

constexpr size_t	NumAvailable () const noexcept
	Query number of elements that is currently available for reading.

Read operations
template<class Operation, class Rep, class Period>
std::pair< std::error_code, size_t >	Read (Operation &&op, size_t count, std::chrono::duration< Rep, Period > timeout) noexcept(std::is_nothrow_invocable_v< Operation, T const & >)
	Reads available data if any, or waits for notification from writer, and then reads available data from queue.

template<class Rep, class Period>
std::pair< std::error_code, size_t >	Skip (size_t count, std::chrono::duration< Rep, Period > timeout) noexcept
	Skip up to `count` elements from queue.

Modifiers
constexpr void	Synchronize () noexcept
	Synchronizes internal state from shared memory.

std::error_code	Reset (std::size_t keep=0u) noexcept
	Reset internal reader state to synchronize with writer and recover from ipcq::Error::InconsistentState.

Construction
	BasicReader (char const *topic_name)
	Create and connect reader to existing queue.

template<class Rep, class Period>
static BasicReader	MakeReader (char const *topic_name, std::chrono::duration< Rep, Period > timeout)
	Factory function that retries to create a reader until success or timeout.

Detailed Description

template<class T, class ConditionPolicy, class ShmTraits = detail::BoostInterprocessTraits>
class ipcq::BasicReader< T, ConditionPolicy, ShmTraits >

Queue BasicReader class.

Template Parameters

T	Type of elements in queue.
ConditionPolicy	Policy used to determine how readers are notified when queue has new elements appeneded to it.
ShmTraits	Implementation details. Leave default.

Basic Usage:

struct MyTopicType {
   ...
};
// Create reader for the topic "topicname" with type MyTopicType.
// If the Writer is not yet created, this function will retry until it gives up
// after the given timeout.
auto reader = ipcq::Reader<MyTopicType>::MakeReader("topicname", 30s);

while (true) {
    MyTopicType sample;
    // Read sample or timeout after 2s
    auto err = reader.Read(ipcq::OutputIteratorAdapter(&sample), 2s);
    if (err) {
        // Handle error
        break;
    }
    // Process sample
    ...
}

Definition at line 73 of file reader.hpp.

Constructor & Destructor Documentation

◆ BasicReader()

template<class T, class ConditionPolicy, class ShmTraits = detail::BoostInterprocessTraits>

ipcq::BasicReader< T, ConditionPolicy, ShmTraits >::BasicReader ( char const * topic_name )

inlineexplicit

Create and connect reader to existing queue.

Parameters

topic_name Name of topic to associate reader with.

Exceptions

boost::interprocess::interprocess_exception	if attaching to shared memory fails.
std::system_error	with ipcq::Error::TypeMismatch if T or ConditionPolicy does not match types in queue. ipcq::Error::Closed if queue is closed, not yet ready or writer process does not exist.

See also: BasicReader::MakeReader

Definition at line 181 of file reader.hpp.

Member Function Documentation

◆ Capacity()

template<class T, class ConditionPolicy, class ShmTraits = detail::BoostInterprocessTraits>

size_t ipcq::BasicReader< T, ConditionPolicy, ShmTraits >::Capacity ( ) const

inlinenodiscardconstexprnoexcept

Query queue capacity, which is the number of elements the queue can hold.

Returns: queue capacity in number of elements.

Definition at line 232 of file reader.hpp.

◆ IsClosed()

template<class T, class ConditionPolicy, class ShmTraits = detail::BoostInterprocessTraits>

bool ipcq::BasicReader< T, ConditionPolicy, ShmTraits >::IsClosed ( ) const

inlinenodiscardconstexprnoexcept

Query whether queue is closed or not.

Returns: true if queue is closed, false otherwise.

Definition at line 223 of file reader.hpp.

◆ MakeReader()

template<class T, class ConditionPolicy, class ShmTraits = detail::BoostInterprocessTraits>

template<class Rep, class Period>

static BasicReader ipcq::BasicReader< T, ConditionPolicy, ShmTraits >::MakeReader	(	char const *	topic_name,
		std::chrono::duration< Rep, Period >	timeout )

inlinestaticnodiscard

Factory function that retries to create a reader until success or timeout.

Definition at line 190 of file reader.hpp.

◆ NumAvailable()

template<class T, class ConditionPolicy, class ShmTraits = detail::BoostInterprocessTraits>

size_t ipcq::BasicReader< T, ConditionPolicy, ShmTraits >::NumAvailable ( ) const

inlinenodiscardconstexprnoexcept

Query number of elements that is currently available for reading.

In other words it's the number of unread elements.

Note: This does not synchronize with shared memory.

This can e.g. be used to calculate how near the reader is to be overwritten as the following approaches zero:

reader.Size() - reader.NumAvailable()

Returns: number of currently available elements.

Definition at line 261 of file reader.hpp.

◆ Read()

template<class T, class ConditionPolicy, class ShmTraits = detail::BoostInterprocessTraits>

template<class Operation, class Rep, class Period>

std::pair< std::error_code, size_t > ipcq::BasicReader< T, ConditionPolicy, ShmTraits >::Read	(	Operation &&	op,
		size_t	count,
		std::chrono::duration< Rep, Period >	timeout )

inlinenodiscardnoexcept

Reads available data if any, or waits for notification from writer, and then reads available data from queue.

Note: Method is not guaranteed to read all the requested count elements.

Reads a maximum of count elements from the queue synchronously by invoking the provided Operation op once with each element. The reader advances the next element to read automatically.

If any data is already available then no waiting will occur. If no data is available then it will wait for writer notification and then read a maximum of count elements. If no notification occurs before specified timeout duration no reads will occur and ipcq::Error::Timeout is returned.

Warning: Data read from the queue must be considered invalid until the return value error code is verified to be 0.

Synchronization: Synchronizes with SHM using acquire semantics.

Parameters

op	Operation function used to operate on read element. Is invoked once for each element. Adapters to standard containers can be used as operation c.f. `ipcq::OutputIteratorAdapter` and `ipcq::BackInserter`.
count	Maximum number of elements to read from queue.
timeout	Maximum time to wait for any data, if no data is not already available to read. Value range and precision is guaranteed to 1 microsecond in range 1 microsecond to 256 hours.

Template Parameters

Operation callable with requirements: `std::is_invocable_v<Operation, T const&>, e.g. a callable with signature @cvoid Operation(T const& element). or @cvoid Operation(T const& element) noexcept`.

Returns: a pair with error code and number of read elements.; Error::InconsistentState if memory consistency errors occurred (see Reset() for how to recover).; Error::Timeout if no data became available before timing out.

Exceptions

Exceptions originating from op. Function provides strong exception guarantee for side-effects in the class itself but not in provided read-operation `op`. User may attempt to read the same elements again by issuing a new call to Read..

See also: ipcq::OutputIteratorAdapter ipcq::BackInserter ipcq::BasicReader::Reset

Definition at line 321 of file reader.hpp.

◆ Reset()

template<class T, class ConditionPolicy, class ShmTraits = detail::BoostInterprocessTraits>

std::error_code ipcq::BasicReader< T, ConditionPolicy, ShmTraits >::Reset ( std::size_t keep = 0u )

inlinenodiscardnoexcept

Reset internal reader state to synchronize with writer and recover from ipcq::Error::InconsistentState.

To reset successfully the queue cannot be empty, as the reader must get state information from the queue to know what to expect next. In this case it returns ipcq::error::WouldBlock instead of waiting for data. Caller can then make the choice to assume the queue is in its initial state. If it was not the next read operation will fail with ipcq::Error::InconsistentState.

Postcondition: On success the next element to read will be the next element to be written.

Synchronization: Synchronizes with SHM using acquire semantics.

Parameters

keep	Number of samples to keep as unread. Default is to keep 0 which is to say the next element to read is the next written. `keep` is automatically truncated to number of available elements.

Returns: 0 On success.; ipcq::Error::Closed if queue is closed and keep is 0 (i.e. reading will not be possible after Reset()).; ipcq::Error::WouldBlock if queue is empty.

Definition at line 388 of file reader.hpp.

◆ Size()

template<class T, class ConditionPolicy, class ShmTraits = detail::BoostInterprocessTraits>

size_t ipcq::BasicReader< T, ConditionPolicy, ShmTraits >::Size ( ) const

inlinenodiscardconstexprnoexcept

Query number of elements in the queue.

Returns: queue size in number of elements.

See also: BasicReader::Synchronize

Definition at line 243 of file reader.hpp.

◆ Skip()

template<class T, class ConditionPolicy, class ShmTraits = detail::BoostInterprocessTraits>

template<class Rep, class Period>

std::pair< std::error_code, size_t > ipcq::BasicReader< T, ConditionPolicy, ShmTraits >::Skip	(	size_t	count,
		std::chrono::duration< Rep, Period >	timeout )

inlinenodiscardnoexcept

Skip up to count elements from queue.

Note: It is functionally equivalent as Read with a no-op op.

Synchronization: Synchronizes with SHM using acquire semantics.

Returns: error, count pair where count is the number of elements skipped.

See also: BasicReader::Read

Definition at line 338 of file reader.hpp.

◆ Synchronize()

template<class T, class ConditionPolicy, class ShmTraits = detail::BoostInterprocessTraits>

void ipcq::BasicReader< T, ConditionPolicy, ShmTraits >::Synchronize ( )

inlineconstexprnoexcept

Synchronizes internal state from shared memory.

This is mainly useful to explicitly synchronize state to update non-synchronizing methods like:

BasicReader::Size()
BasicReader::NumAvailable()

Note: Synchronize should not be invoked for BasicReader::Read as it performs synchronization as a side-effect of reading.

Synchronization: Synchronizes with SHM using acquire semantics.

Definition at line 361 of file reader.hpp.

◆ TopicName()

template<class T, class ConditionPolicy, class ShmTraits = detail::BoostInterprocessTraits>

char const * ipcq::BasicReader< T, ConditionPolicy, ShmTraits >::TopicName ( ) const

inlinenodiscardnoexcept

Get queue topic name.

Returns: topic name in queue.

Definition at line 214 of file reader.hpp.

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

ipcq/src/include/ipcq/reader.hpp

Public Member Functions

Construction

Detailed Description

Constructor & Destructor Documentation

◆ BasicReader()

Member Function Documentation

◆ Capacity()

◆ IsClosed()

◆ MakeReader()

◆ NumAvailable()

◆ Read()

◆ Reset()

◆ Size()

◆ Skip()

◆ Synchronize()

◆ TopicName()