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

#include <BufferLayout.h>

Classes
struct	Header

Public Member Functions
	BufferLayout (std::shared_ptr< Buffer > buffer)
	~BufferLayout ()
	The destructor ensures the BufferLayout is detach()es from the Buffer. More...
Header *	getHeader () const
AtomicBool *	getReaderEnabledArray () const
AtomicIndex *	getReaderCursorArray () const
AtomicIndex *	getReaderCloseIndexArray () const
Index	getDataSize () const
uint8_t *	getData (Index at=0) const
bool	init (size_t wordSize, size_t maxReaders, size_t maxEphemeralReaders)
bool	attach ()
void	detach ()
bool	isReaderEnabled (size_t id) const
void	enableReaderLocked (size_t id)
void	disableReaderLocked (size_t id)
Index	wordsUntilWrap (Index after) const
void	updateOldestUnconsumedCursor ()
	This function calls updateOldestUnconsumedCursorLocked() while holding Header::backwardSeekMutex. More...
void	updateOldestUnconsumedCursorLocked ()

Static Public Member Functions
static size_t	calculateDataOffset (size_t wordSize, size_t maxReaders)

Static Public Attributes
static const uint32_t	MAGIC_NUMBER = 0x53445348
	Magic number used to identify a valid Header in memory. More...
static const uint32_t	VERSION = 2
	Version of this header layout. More...

Detailed Description

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

This is a nested class inside SharedDatastream which defines the layout of a Buffer for use with a SharedDataStream. This layout begins with a fixed Header structure, followed by two arrays of Reader Indexes, with the remainder allocated to data. All four of these sections are aligned on a 64-bit boundary.

Constructor & Destructor Documentation

BufferLayout()

template<typename T >

alexaClientSDK::avsCommon::utils::sds::SharedDataStream::BufferLayout< T >::BufferLayout

(

std::shared_ptr< Buffer >

buffer

)

The constructor only initializes a shared pointer to the provided buffer. Attaching and/or initializing is performed by the init()/attach() functions.

Parameters

buffer

The raw buffer which holds (or will hold) the header, arrays, and circular data buffer.

~BufferLayout()

template<typename T >

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

(

)

The destructor ensures the BufferLayout is detach()es from the Buffer.

Member Function Documentation

attach()

template<typename T >

bool alexaClientSDK::avsCommon::utils::sds::SharedDataStream::BufferLayout< T >::attach

(

)

This function tries to attach this BufferLayout to a Buffer which was already initialized by another BufferLayout. This function will verify that the Buffer contains a valid header which is compatible with this Buffer's traits. This function can be safely called from multiple threads or processes after another another BufferLayout which is managing the same Buffer has completed a call to init().

Returns

true if successfully attached (Buffer contains a valid and compatible header), else false.

calculateDataOffset()

template<typename T >

size_t alexaClientSDK::avsCommon::utils::sds::SharedDataStream::BufferLayout< T >::calculateDataOffset ( size_t  wordSize, size_t  maxReaders  )

static

This function calculates the offset (in bytes) from the start of a Buffer to the start of the circular data.

Parameters

wordSize	The size (in bytes) of words in the stream. All SharedDataStream operations that work with data or position in the stream are quantified in words.
maxReaders	The maximum number of readers the stream will support.

Returns

The offset (in bytes) from the start of a Buffer to the start of the circular data.

detach()

template<typename T >

void alexaClientSDK::avsCommon::utils::sds::SharedDataStream::BufferLayout< T >::detach

(

)

This function detaches from the Buffer which it is managing. If this is the last BufferLayout attached to the Buffer, it will also call the destructors on the objects in the Buffer.

disableReaderLocked()

template<typename T >

void alexaClientSDK::avsCommon::utils::sds::SharedDataStream::BufferLayout< T >::disableReaderLocked

(

size_t

id

)

This function disables the specified reader. The caller must be holding Header::readerEnableMutex when calling this function.

Parameters

id	The id of the reader to disable.

enableReaderLocked()

template<typename T >

void alexaClientSDK::avsCommon::utils::sds::SharedDataStream::BufferLayout< T >::enableReaderLocked

(

size_t

id

)

This function enables the specified reader. The caller must be holding Header::readerEnableMutex when calling this function.

Parameters

id	The id of the reader to enable.

getData()

template<typename T >

uint8_t * alexaClientSDK::avsCommon::utils::sds::SharedDataStream::BufferLayout< T >::getData

(

Index

at = 0

)

const

This function provides access to the data (non-Header) portion of buffer.

The data comes next in m_buffer after the getReaderCloseIndexArray() array listed above.

Parameters

at

An optional word Index to get a data pointer for. This function will calculate where at would fall in the circular buffer and return a pointer to it, but note that this function does not check whether the specified Index currently resides in the buffer. This parameter defaults to 0, which will return a pointer to the base of the circular data buffer.

Returns

A pointer to the data which would hold the specified Index.

getDataSize()

template<typename T >

SharedDataStream< T >::Index alexaClientSDK::avsCommon::utils::sds::SharedDataStream::BufferLayout< T >::getDataSize

(

)

const

This function returns the size (in words) of the data (non-Header) portion of buffer. The data comes next in m_buffer after the getReaderCloseIndexarray() listed above.

Returns

The maximum number of words the stream can store.

getHeader()

template<typename T >

SharedDataStream< T >::BufferLayout::Header * alexaClientSDK::avsCommon::utils::sds::SharedDataStream::BufferLayout< T >::getHeader

(

)

const

This function provides access to the Header structure stored at the start of the Buffer.

Returns

A pointer to the Header structure inside the Buffer.

getReaderCloseIndexArray()

template<typename T >

SharedDataStream< T >::AtomicIndex * alexaClientSDK::avsCommon::utils::sds::SharedDataStream::BufferLayout< T >::getReaderCloseIndexArray

(

)

const

This function provides access to the array of indices which specify the Index where each Reader will stop reading. When a Reader's close Index is set to zero, this indicates that the Reader is disabled. When a Reader's close Index is less than or equal to the Reader's cursor, this indicates that the Reader has reached the end of its stream, and subsequent calls to Reader::read() will return 0. When a Reader's close Index is greater than the Reader's cursor, the Reader will continue to return data as it becomes available in the stream up to the point when it reaches the close Index.

Note

An enabled Reader will initially have its close Index set to std::numeric_limits_max<AtomicIndex>, meaning it can effectively continue to read indefinitely, until the Writer closes. If a call to Reader::close() occurs, it will move the Reader's close Index to the current write start cursor, which will cause the read stream to end when the Reader finishes consuming the data that was in the buffer at the time Reader::close() was called.

This array of close Index indices comes next in m_buffer after the getReaderCursorArray() listed above.

Returns

A pointer to the array of maxReaders close Indexes.

getReaderCursorArray()

template<typename T >

SharedDataStream< T >::AtomicIndex * alexaClientSDK::avsCommon::utils::sds::SharedDataStream::BufferLayout< T >::getReaderCursorArray

(

)

const

This function provides access to the array of indices which specify the location each Reader will read from.

This array of cursor indices comes next in m_buffer after the getReaderEnabledArray() listed above.

Returns

A pointer to the array of maxReaders cursor Indexes.

getReaderEnabledArray()

template<typename T >

SharedDataStream< T >::AtomicBool * alexaClientSDK::avsCommon::utils::sds::SharedDataStream::BufferLayout< T >::getReaderEnabledArray

(

)

const

This function provides access to the array of booleans which specify whether a particular reader is enabled.

This array of enabled booleans comes next in m_buffer after the Header.

Returns

A pointer to the array of maxReaders cursor Indexes.

init()

template<typename T >

bool alexaClientSDK::avsCommon::utils::sds::SharedDataStream::BufferLayout< T >::init	(	size_t	wordSize,
		size_t	maxReaders,
		size_t	maxEphemeralReaders
	)

This function initalizes the Header and arrays in the Buffer managed by this BufferLayout. This function must not be called on a BufferLayout which is managing a Buffer which has already been initialized. This function must return before attempting to attach() another BufferLayout to the Buffer being initialized here. This function must not be called if the Buffer it would initialized has other BufferLayouts attached to it.

Parameters

wordSize	The size (in bytes) of words in the stream. All SharedDataStream operations that work with data or position in the stream are quantified in words.
maxReaders	The maximum number of readers the stream will support.
maxEphemeralReaders	The maximum number of readers that can be created without specifying a reader id.

Returns

false if wordSize or maxReaders are too large to be stored, else true.

isReaderEnabled()

template<typename T >

bool alexaClientSDK::avsCommon::utils::sds::SharedDataStream::BufferLayout< T >::isReaderEnabled

(

size_t

id

)

const

This function checks whether the specified reader is enabled.

Note

This function does not require the caller to hold Header::readerEnableMutex. Reading the enabled flag is an atomic operation in and of itself. It is up to the caller to determine whether there are subsequent operations which depend on the enabled state that might require holding the mutex to avoid a race condition.

Parameters

id	The id of the reader to check the enabled status of.

Returns

true if the specified reader is enabled, else false.

updateOldestUnconsumedCursor()

template<typename T >

void alexaClientSDK::avsCommon::utils::sds::SharedDataStream::BufferLayout< T >::updateOldestUnconsumedCursor

(

)

This function calls updateOldestUnconsumedCursorLocked() while holding Header::backwardSeekMutex.

updateOldestUnconsumedCursorLocked()

template<typename T >

void alexaClientSDK::avsCommon::utils::sds::SharedDataStream::BufferLayout< T >::updateOldestUnconsumedCursorLocked

(

)

This function scans through the array of Reader cursors, finds the oldest enabled cursor, and records it in oldestUnconsumedCursor. This function should be called whenever a Reader moves its cursor. This function needs to guarantee that no Reader cursors are older than oldestUnconsumedCursor when it completes, so it holds backwardSeekMutex to prevent race conditions. This function must be called while holding Header::backwardSeekMutex.

Note

Without mutexes, any Reader::read() or Reader::seek() call could move a read cursor while this function is iterating through the list of Readers. The Reader::read() calls will always move their cursors to a newer location, so no mutex is needed (if this function looks at a particular Reader and updates oldestUnconsumedCursor, and the Reader later Reader::read()s before this function finishes, oldestUnconsumedCursor will still be older than that Reader, so there is no problem). Similarly, Reader::seek() calls which move the cursor to a newer location are not a problem, but Reader::seek() calls which move a cursor backwards pose a risk of a race condition. If this function looks at a particular Reader, and the Reader does a backwards Reader::seek() after it has been examined, this function could end up with oldestUnconsumedCursor at an Index which is ahead of the Reader that performed the backwards Reader::seek(). To prevent this race condition, this function takes the backwardSeekMutex, which prevents backwards Reader::seek()s while oldestUnconsumedCursor is being updated.

As an optimization, we could skip this function if Writer policy is nonblockable (ACSDK-251).

wordsUntilWrap()

template<typename T >

SharedDataStream< T >::Index alexaClientSDK::avsCommon::utils::sds::SharedDataStream::BufferLayout< T >::wordsUntilWrap

(

Index

after

)

const

This function returns a count of the number of words after the specified Index before the circular data will wrap.

param after The Index to count from. return The count of words after after until the circular data will wrap.

Member Data Documentation

MAGIC_NUMBER

template<typename T >

const uint32_t alexaClientSDK::avsCommon::utils::sds::SharedDataStream::BufferLayout< T >::MAGIC_NUMBER = 0x53445348

static

Magic number used to identify a valid Header in memory.

VERSION

template<typename T >

const uint32_t alexaClientSDK::avsCommon::utils::sds::SharedDataStream::BufferLayout< T >::VERSION = 2

static

Version of this header layout.

---

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

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