cFileRingBuffer< ADDITIONAL_DATA, ALIGNMENT >

File-based ring buffer. More...

Classes
class	IDropCallback
	Callback interface for dropped items. More...
struct	tItem
	This struct store information about an item in the buffer. More...
struct	tItemPiece
	Helper struct to store an item that is made up by multiple data buffers. More...

Public Types
typedef std::deque< tItem >	tItems
	Typedef for convienient access.
typedef tItems::const_iterator	const_iterator
	An const iterator in the buffer.

Public Member Functions
	cFileRingBuffer (cFile *pFile, tFilePos nStartOffset=0, tFileSize nMaxSize=0, IDropCallback *pDropCallback=nullptr)
	Constructor. More...
const tFileSize &	GetCurrentSize ()
	Returns the current size of the buffer. More...
tResult	StartWrappingAround ()
	Limits the size of the buffer by the current size. More...
tResult	StartAppending (tItem *pRearDataItem=NULL, tItem *pLastDataItem=NULL)
	After a call to this method, data will be appended after the ring buffer. More...
tResult	AppendItem (const tVoid *pData, tSize nDataSize, const ADDITIONAL_DATA &xAdditional, tFilePos *pFilePos=nullptr)
	Adds a new item at the end of the buffer. More...
tResult	AppendItem (const tItemPiece *pPieces, tSize nCount, const ADDITIONAL_DATA &xAdditional, tFilePos *pFilePos=nullptr)
	Adds a new item that is made up by multiple data buffers at the end of the buffer. More...
const_iterator	begin () const
	Retunrs an iterator to the beginning of the buffer. More...
const_iterator	end () const
	Retuns an iterator to the end of the buffer. More...

Protected Member Functions
tResult	FillForAlignment ()
	Writes data to the file until a field position is reached that satisfies the alignment requirement. More...
tResult	PopFront ()
	Removes the first item in the buffer. More...

Private Attributes
tItems	m_oItems
cFile *	m_pFile
tFilePos	m_nStartOffset
tFilePos	m_nCurrentPos
tFileSize	m_nCurrentSize
tFileSize	m_nMaxSize
tBool	m_bBookkeeping
IDropCallback *	m_pCallback
cMemoryBlock	m_oAlignmentBuffer
tItem	m_sRearItem

Detailed Description

template<typename ADDITIONAL_DATA = tUInt8, tUInt8 ALIGNMENT = 1>
class A_UTILS_NS::cFileRingBuffer< ADDITIONAL_DATA, ALIGNMENT >

File-based ring buffer.

A ring buffer implementation that supports variable sized elements and stores the actual data in a file. Mind that bookkeeping data is still kept in memory.

Use the template argument to store any additional data that you need in the drop callback which is called whenever an item is removed from the head of the buffer.

Start by calling the constructor with an already opend file. Then append items using the AppendItem() method. When you want to start wrapping around, call StartWrappingAround(). This will limit the ring buffer size by the current size. When you want to continue writing past the end of the ringbuffer, call StartAppending() and the file will then grow indefinitly.

Definition at line 28 of file fileringbuffer.h.

Constructor & Destructor Documentation

cFileRingBuffer()

cFileRingBuffer ( cFile *  pFile, tFilePos  nStartOffset = 0, tFileSize  nMaxSize = 0, IDropCallback *  pDropCallback = nullptr  )

inline

Constructor.

Parameters

[in]	pFile	A pointer to an open file.
[in]	nStartOffset	The offset where the ring buffer should start.
[in]	nMaxSize	An optional size after which wrapping around will start. automatically, if zero, use StartWrappingAround.
[in]	pDropCallback	A callback that will inform about dropped items.

Definition at line 93 of file fileringbuffer.h.

References cMemoryBlock::Alloc(), cFileRingBuffer< ADDITIONAL_DATA, ALIGNMENT >::FillForAlignment(), cFile::FP_Begin, cMemoryBlock::GetPtr(), cMemoryBlock::GetSize(), cMemoryBlock::MemZero(), and cFile::SetFilePos().

Member Function Documentation

AppendItem() [1/2]

tResult AppendItem ( const tItemPiece *  pPieces, tSize  nCount, const ADDITIONAL_DATA &  xAdditional, tFilePos *  pFilePos = nullptr  )

inline

Adds a new item that is made up by multiple data buffers at the end of the buffer.

Parameters

[in]	pPieces	An array of item pieces.
[in]	nCount	The amount of pieces in the array.
[in]	xAdditional	Additional bookkeeping data.
[out]	pFilePos	The postion where the item was stored.

Returns

Standard result.

Definition at line 209 of file fileringbuffer.h.

References cFileRingBuffer< ADDITIONAL_DATA, ALIGNMENT >::FillForAlignment(), cFile::FP_Begin, cFileRingBuffer< ADDITIONAL_DATA, ALIGNMENT >::tItemPiece::nDataSize, cFileRingBuffer< ADDITIONAL_DATA, ALIGNMENT >::tItem::nFilePos, cFileRingBuffer< ADDITIONAL_DATA, ALIGNMENT >::tItem::nSize, cFileRingBuffer< ADDITIONAL_DATA, ALIGNMENT >::tItemPiece::pData, cFileRingBuffer< ADDITIONAL_DATA, ALIGNMENT >::PopFront(), RETURN_ERROR, RETURN_IF_FAILED, RETURN_NOERROR, cFile::SetFilePos(), cFile::Truncate(), cFile::WriteAll(), and cFileRingBuffer< ADDITIONAL_DATA, ALIGNMENT >::tItem::xAdditional.

AppendItem() [2/2]

tResult AppendItem ( const tVoid *  pData, tSize  nDataSize, const ADDITIONAL_DATA &  xAdditional, tFilePos *  pFilePos = nullptr  )

inline

Adds a new item at the end of the buffer.

Parameters

[in]	pData	The data of the item.
[in]	nDataSize	The size of the data.
[in]	xAdditional	Additional bookkeeping data.
[out]	pFilePos	The postion where the item was stored.

Returns

Standard result.

Definition at line 192 of file fileringbuffer.h.

References cFileRingBuffer< ADDITIONAL_DATA, ALIGNMENT >::tItemPiece::nDataSize, and cFileRingBuffer< ADDITIONAL_DATA, ALIGNMENT >::tItemPiece::pData.

begin()

const_iterator begin ( ) const

inline

Retunrs an iterator to the beginning of the buffer.

Returns

An iterator to the beginning of the buffer.

Definition at line 306 of file fileringbuffer.h.

end()

const_iterator end ( ) const

inline

Retuns an iterator to the end of the buffer.

Returns

An iterator to the end of the buffer.

Definition at line 315 of file fileringbuffer.h.

FillForAlignment()

tResult FillForAlignment ( )

inlineprotected

Writes data to the file until a field position is reached that satisfies the alignment requirement.

Returns

Standard result.

Definition at line 326 of file fileringbuffer.h.

References cMemoryBlock::GetPtr(), RETURN_IF_FAILED, RETURN_NOERROR, and cFile::WriteAll().

Referenced by cFileRingBuffer< ADDITIONAL_DATA, ALIGNMENT >::cFileRingBuffer(), and cFileRingBuffer< ADDITIONAL_DATA, ALIGNMENT >::AppendItem().

GetCurrentSize()

const tFileSize& GetCurrentSize ( )

inline

Returns the current size of the buffer.

Returns

The current size of the buffer.

Definition at line 118 of file fileringbuffer.h.

PopFront()

tResult PopFront ( )

inlineprotected

Removes the first item in the buffer.

Returns

Standard result.

Definition at line 344 of file fileringbuffer.h.

References cFileRingBuffer< ADDITIONAL_DATA, ALIGNMENT >::IDropCallback::OnDrop(), RETURN_IF_FAILED, and RETURN_NOERROR.

Referenced by cFileRingBuffer< ADDITIONAL_DATA, ALIGNMENT >::AppendItem().

StartAppending()

tResult StartAppending ( tItem *  pRearDataItem = NULL, tItem *  pLastDataItem = NULL  )

inline

After a call to this method, data will be appended after the ring buffer.

Parameters

[out]	pRearDataItem	A pointer that will bes set to point to the rear item in the buffer (the position where the buffer wraps around).
[out]	pLastDataItem	A pointer that will bes set to point to the last item in the buffer.

Returns

Standard result.

Definition at line 146 of file fileringbuffer.h.

References cFile::FP_End, cFile::GetFilePos(), cFileRingBuffer< ADDITIONAL_DATA, ALIGNMENT >::tItem::nFilePos, RETURN_ERROR, RETURN_NOERROR, cFile::SetFilePos(), and tFalse.

StartWrappingAround()

tResult StartWrappingAround ( )

inline

Limits the size of the buffer by the current size.

Returns

Standard result.

Definition at line 127 of file fileringbuffer.h.

References RETURN_ERROR, and RETURN_NOERROR.