alexaClientSDK::avsCommon::utils::sds::SharedDataStream::Reader< T > Class Template Reference

#include <Reader.h>

Classes
struct	Error

Public Types
using	Policy = ReaderPolicy
	Specifies the policy to use for reading from the stream. More...
using	OutputFunction = std::function< bool(void *buf, size_t nWords)>

Public Member Functions
	Reader (Policy policy, std::shared_ptr< BufferLayout > bufferLayout, size_t id)
	~Reader ()
	This destructor detaches the Reader from a BufferLayout. More...
ssize_t	read (OutputFunction function, size_t maxWordsCanRead, std::chrono::milliseconds timeout=std::chrono::milliseconds(0))
ssize_t	read (void *buf, size_t nWords, std::chrono::milliseconds timeout=std::chrono::milliseconds(0))
bool	seek (Index offset, Reference reference=Reference::ABSOLUTE)
Index	tell (Reference reference=Reference::ABSOLUTE) const
void	close (Index offset=0, Reference reference=Reference::AFTER_READER)
size_t	getId () const
size_t	getWordSize () const

Static Public Member Functions
static std::string	errorToString (Error error)

Detailed Description

template<typename T>
class alexaClientSDK::avsCommon::utils::sds::SharedDataStream::Reader< T >

This is a nested class in SharedDataStream which provides an interface for reading (consuming) data from a stream.

Note

This class is primarily intended to be used from a single thread. The Reader as a whole is thread-safe in the sense that Writer and Readers can all live in different threads, but individual member functions of a Reader instance should not be called from multiple threads except where specifically noted in function documentation below.

Member Typedef Documentation

OutputFunction

template<typename T >

using alexaClientSDK::avsCommon::utils::sds::SharedDataStream::Reader< T >::OutputFunction = std::function<bool(void* buf, size_t nWords)>

This function is passed in a read call to allow reading directly from the raw buffer. This allows you to avoid an intermediate copy while using a reader. It is passed into a Reader below in with a read call and no reference to the lambda will be saved after the read function has returned. Implementations are not required to be thread safe, callbacks will return before the next one is called.

Since nWords is bound by nWords in the read function it is assumed that the caller will consume the entire buffer in every callback.

Note

This function can be called multiple times per call to read depending on the implementation of SharedDataStream and how much data was requested and it is up to the caller to handle multiple calls and the offsets into the caller's buffer.

Parameters

buf	The pointer to read from. Note that this pointer is only valid for this read and there are no guarantees on it after the read is complete.
nWords	The number of wordSize words that are safe to read from buf.

Returns

true if all words consumed, false otherwise. Returning false will cause the read function to fail and not consume any words from the Reader.

Policy

template<typename T >

using alexaClientSDK::avsCommon::utils::sds::SharedDataStream::Reader< T >::Policy = ReaderPolicy

Specifies the policy to use for reading from the stream.

Constructor & Destructor Documentation

Reader()

template<typename T >

alexaClientSDK::avsCommon::utils::sds::SharedDataStream::Reader< T >::Reader	(	Policy	policy,
		std::shared_ptr< BufferLayout >	bufferLayout,
		size_t	id
	)

Constructs a new Reader which consumes data from the provided SharedDataStream. The caller must hold Header::readerEnableMutex when constructing new Readers.

Parameters

policy	The policy to use for reading from the stream.
bufferLayout	The BufferLayout to use for reading stream data.
id	The id of the reader, assigned by the SharedDataStream.

~Reader()

template<typename T >

alexaClientSDK::avsCommon::utils::sds::SharedDataStream::Reader< T >::~Reader

(

)

This destructor detaches the Reader from a BufferLayout.

Member Function Documentation

close()

template<typename T >

void alexaClientSDK::avsCommon::utils::sds::SharedDataStream::Reader< T >::close	(	Index	offset = 0,
		Reference	reference = Reference::AFTER_READER
	)

This function sets the point at which the Reader's stream will close. With the default parameters, this function will close the stream immediately, without reading any additional data. To schedule the stream to close once all the data which is currently in the buffer has been read, call close(0, Reference::BEFORE_WRITER). If another close point is desired, it can be specified using a different offset and/or reference.

Parameters

offset	The position (in wordSize words) in the stream, relative to reference, to close at.
reference	The position in the stream the close point is measured against.

Note

This function can be called from any thread or process, and it will schedule the Reader to close, however it will not wake up a BLOCKING Reader which is already blocked waiting for data. In the case of a blocked read(), that read() will return when it wakes up - either due to a timeout, or due to a Writer adding data to the stream.

errorToString()

template<typename T >

std::string alexaClientSDK::avsCommon::utils::sds::SharedDataStream::Reader< T >::errorToString ( Error  error )

static

Returns the text of an error code.

Returns

Text of the specified error.

getId()

template<typename T >

size_t alexaClientSDK::avsCommon::utils::sds::SharedDataStream::Reader< T >::getId

(

)

const

This function returns the id assigned to this Reader. If a Reader instance is not destroyed cleanly (e.g. a Reader from another process that crashes), its id can be passed to SharedDataStream::reset() to free up its resources.

Returns

The id assigned to this Reader.

getWordSize()

template<typename T >

size_t alexaClientSDK::avsCommon::utils::sds::SharedDataStream::Reader< T >::getWordSize

(

)

const

This function returns the word size (in bytes). All SharedDataStream operations that work with data or position in the stream are quantified in words.

Returns

The size (in bytes) of words for this Reader's SharedDataStream.

read() [1/2]

template<typename T >

ssize_t alexaClientSDK::avsCommon::utils::sds::SharedDataStream::Reader< T >::read	(	OutputFunction	function,
		size_t	maxWordsCanRead,
		std::chrono::milliseconds	timeout = std::chrono::milliseconds(0)
	)

This function consumes data from the stream and passes it into the read function to avoid intermediate copies of the data.

Parameters

function	The read function that will take a read pointer and the number of words that it's expected to handle. The read function's parameter nWords will be equal to or less than maxWordsCanRead. This may be called twice on account of the circular buffer however the sum of nWords in both calls will be less than maxWordsCanRead.
maxWordsCanRead	The maximum number of wordSize words to copy.
timeout	The maximum time to wait (if policy is BLOCKING) for data. If this parameter is zero, there is no timeout and blocking reads will wait forever. If policy is NONBLOCKING, this parameter is ignored. In the case of a timeout function will not be called.

Returns

The number of wordSize words copied if data was consumed, or zero if the stream has closed, or a negative Error code if the stream is still open, but no data could be consumed.

Note

A stream is closed for the Reader if Reader::close() has been called on it, or if Writer::close() has been called and the Reader has consumed all remaining data left in the stream when the Writer closed. In the special case of a new stream, where no Writer has been created, the stream is not considered to be closed for the Reader; attempts to read() will either block or return WOULDBLOCK, depending on the Policy.

read() [2/2]

template<typename T >

ssize_t alexaClientSDK::avsCommon::utils::sds::SharedDataStream::Reader< T >::read	(	void *	buf,
		size_t	nWords,
		std::chrono::milliseconds	timeout = std::chrono::milliseconds(0)
	)

This function consumes data from the stream and copies it to the provided buffer.

Parameters

buf	A buffer to copy the consumed data to. This buffer must be large enough to hold nWords (nWords * wordSize bytes).
nWords	The maximum number of wordSize words to copy.
timeout	The maximum time to wait (if policy is BLOCKING) for data. If this parameter is zero, there is no timeout and blocking reads will wait forever. If policy is NONBLOCKING, this parameter is ignored.

Returns

The number of wordSize words copied if data was consumed, or zero if the stream has closed, or a negative Error code if the stream is still open, but no data could be consumed.

Note

A stream is closed for the Reader if Reader::close() has been called on it, or if Writer::close() has been called and the Reader has consumed all remaining data left in the stream when the Writer closed. In the special case of a new stream, where no Writer has been created, the stream is not considered to be closed for the Reader; attempts to read() will either block or return WOULDBLOCK, depending on the Policy.

seek()

template<typename T >

bool alexaClientSDK::avsCommon::utils::sds::SharedDataStream::Reader< T >::seek	(	Index	offset,
		Reference	reference = Reference::ABSOLUTE
	)

This function moves the Reader to the specified location in the stream. If successful, subsequent calls to read() will start from the new location. For this function to succeed, the specified location must point at data which has not been pushed out of the buffer; if the specified location points at old data which has already been overwritten, the seek() call will fail. If the specified location points at future data which does not yet exist in the buffer, the seek() call will succeed. If the seek() call fails, the Reader position will remain unchanged.

Parameters

offset	The position (in wordSize words) in the stream, relative to reference, to move the Reader to.
reference	The position in the stream offset is applied to.

Returns

true if the specified position points at unconsumed data, else false.

tell()

template<typename T >

SharedDataStream< T >::Index alexaClientSDK::avsCommon::utils::sds::SharedDataStream::Reader< T >::tell

(

Reference

reference = Reference::ABSOLUTE

)

const

This function reports the current position of the Reader in the stream.

Parameters

reference

The position in the stream the return value is measured against.

Returns

The Reader's position (in wordSize words) in the stream relative to reference.

Note

For Reference::BEFORE_WRITER, if the read cursor points at a location in the future (after the writer), then the reader is not before the writer, so this function will return 0.

---

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

• /workplace/avs-device-sdk/AVSCommon/Utils/include/AVSCommon/Utils/SDS/Reader.h