![]() |
AlexaClientSDK
3.0.0
A cross-platform, modular SDK for interacting with the Alexa Voice Service
|
#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) |
This is a nested class in SharedDataStream which provides an interface for reading (consuming) data from a stream.
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. 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.
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. 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. |
using alexaClientSDK::avsCommon::utils::sds::SharedDataStream::Reader< T >::Policy = ReaderPolicy |
Specifies the policy to use for reading from the stream.
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.
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 . |
alexaClientSDK::avsCommon::utils::sds::SharedDataStream::Reader< T >::~Reader | ( | ) |
This destructor detaches the Reader
from a BufferLayout
.
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
.
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. |
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.
|
static |
Returns the text of an error code.
size_t alexaClientSDK::avsCommon::utils::sds::SharedDataStream::Reader< T >::getId | ( | ) | const |
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.
Reader's
SharedDataStream
. 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.
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. |
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.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
. 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.
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. |
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.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
. 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.
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. |
true
if the specified position points at unconsumed data, else false
. 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.
reference | The position in the stream the return value is measured against. |
Reader's
position (in wordSize
words) in the stream relative to reference
.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. AlexaClientSDK 3.0.0 - Copyright 2016-2022 Amazon.com, Inc. or its affiliates. All Rights Reserved. Licensed under the Apache License, Version 2.0