AMPS C/C++ Client Class Reference
AMPS C/C++ Client Version 5.3.4.3
AMPS::BlockStore Class Reference

Used as a base class for other stores in the AMPS C++ client, this is an implementation that breaks a provided Buffer into uniform blocks for storing messages and tracks used and unused blocks. More...

#include <BlockStore.hpp>

Classes

class  Block
 Used as metadata for each block in a Buffer. More...
 

Public Types

Public Member Functions

 BlockStore (Buffer *buffer_, amps_uint32_t blocksPerRealloc_=DEFAULT_BLOCKS_PER_REALLOC, amps_uint32_t blockHeaderSize_=DEFAULT_BLOCK_HEADER_SIZE, amps_uint32_t blockSize_=DEFAULT_BLOCK_SIZE)
 Create a BlockStore using buffer_ and default block size, that grows by blocksPerRealloc_ blocks when it must grow. More...
 
 ~BlockStore ()
 Destructor that cleans up the buffer and other associated memory.
 
amps_uint32_t getBlockSize () const
 Get the size of each Block, as set in the constructor.
 
amps_uint32_t getBlockHeaderSize () const
 Get the size of a header within each Block, as set in the constructor.
 
void acquireRead () const
 Acquire the lock for this object. More...
 
void releaseRead () const
 Release the lock for this object. Used by RAII templates.
 
void signalAll ()
 Signal lock waiters.
 
void wait ()
 Wait for a signal.
 
bool wait (long timeout_)
 Wait timeout_ ms for a signal. More...
 
void setResizeHandler (ResizeHandler resizeHandler_, void *userData_)
 Set a resize handler that is called with the new total size of the Buffer. More...
 
Blockfront () const
 Get the first used block in the store. More...
 
Blockback () const
 Get the last used block in the store. More...
 
void setFreeList (Block *block_, amps_uint32_t freeCount_)
 Allow containing classes to initialize the free list in recovery. More...
 
void setUsedList (Block *block_)
 Allow containing classes to initialize the used list in recovery. More...
 
void setEndOfUsedList (Block *block_)
 Allow containing classes to initialize the used list in recovery. More...
 
void addBlocks (Block *blockArray_)
 Allow users to create Block arrays during recovery that are tracked for cleanup here with all other Block arrays. More...
 
Blockget (amps_uint32_t numBlocksInChain_)
 Get the requested number of Blocks as a chain from the free list. More...
 
void put (Block *block_)
 Return the given chain of Blocks to the free list for reuse. More...
 
AMPS_ATOMIC_BASE_TYPE put (amps_uint64_t sequence_)
 Return all Blocks with sequence <= sequence_ for reuse. More...
 
void putAll (Block *block_)
 Return all Blocks starting with the given Block to the free list. More...
 
void init ()
 Initialize, assuming that _buffer has no existing information. More...
 
size_t getDefaultResizeSize () const
 Return the default number of bytes for each resize. More...
 
amps_uint32_t getDefaultResizeBlocks () const
 Return the default number of blocks for each resize. More...
 
BlockresizeBuffer (size_t size_, amps_uint32_t *pNewBlocks_)
 Resize the buffer to the requested size, returning all new space. More...
 
void resize (size_t size_)
 Resize the buffer to the requested size, adding all new space as unused Blocks for the free list. More...
 
amps_uint32_t setBlockSize (amps_uint32_t blockSize_)
 Set the size to use for all Blocks. More...
 
amps_uint32_t setBlockHeaderSize (amps_uint32_t blockHeaderSize_)
 Set the size to use for the header for all Blocks. More...
 
BuffergetBuffer ()
 Return the buffer underlying the store for direct write/read. More...
 

Detailed Description

Used as a base class for other stores in the AMPS C++ client, this is an implementation that breaks a provided Buffer into uniform blocks for storing messages and tracks used and unused blocks.

Constructor & Destructor Documentation

AMPS::BlockStore::BlockStore ( Buffer buffer_,
amps_uint32_t  blocksPerRealloc_ = DEFAULT_BLOCKS_PER_REALLOC,
amps_uint32_t  blockHeaderSize_ = DEFAULT_BLOCK_HEADER_SIZE,
amps_uint32_t  blockSize_ = DEFAULT_BLOCK_SIZE 
)
inline

Create a BlockStore using buffer_ and default block size, that grows by blocksPerRealloc_ blocks when it must grow.

The initialization or recovery from the buffer_ is handled outside of this class by either calling init() to start new, or by recovering the Blocks and using setFreeList(), setUsedList(), setEndOfUsedList() and addBlocks().

Parameters
buffer_Pointer to an allocated Buffer implementation that will be used for storage. The store will delete buffer_ when it is destructed.
blocksPerRealloc_Number of blocks to add to when growing the size of the Buffer.
blockSize_The size to use for each block in the store.
blockHeaderSize_The size of the header section of each block, which is also the only memory that needs to be cleared in a block for it to skipped during recovery and be reusable.

Member Function Documentation

void AMPS::BlockStore::acquireRead ( ) const
inline

Acquire the lock for this object.

Used by RAII templates. The lock should be acquired before calling any other functions below and held while using the Buffer* returned by getBuffer().

void AMPS::BlockStore::addBlocks ( Block blockArray_)
inline

Allow users to create Block arrays during recovery that are tracked for cleanup here with all other Block arrays.

Parameters
blockArray_A pointer the beginning of the allocated array.
Block* AMPS::BlockStore::back ( ) const
inline

Get the last used block in the store.

Returns
A pointer to the last used block, which may be null if the store is empty, or the same as front() if there is only one block in use in the store.
Block* AMPS::BlockStore::front ( ) const
inline

Get the first used block in the store.

Returns
A pointer to the first used block, which may be null if the store is currently empty.
Block* AMPS::BlockStore::get ( amps_uint32_t  numBlocksInChain_)
inline

Get the requested number of Blocks as a chain from the free list.

Parameters
numBlocksInChain_The number of blocks needed.
Returns
A pointer to the first Block in the chain. Remaining Blocks are found at nextInChain.
Buffer* AMPS::BlockStore::getBuffer ( )
inline

Return the buffer underlying the store for direct write/read.

Returns
The wrapped buffer.
amps_uint32_t AMPS::BlockStore::getDefaultResizeBlocks ( ) const
inline

Return the default number of blocks for each resize.

Returns
The number of blocks by which the store resizes itself.
size_t AMPS::BlockStore::getDefaultResizeSize ( ) const
inline

Return the default number of bytes for each resize.

Returns
The number of bytes by which the store resizes itself.
void AMPS::BlockStore::init ( )
inline

Initialize, assuming that _buffer has no existing information.

Divide the _buffer in Blocks and put them all into the free list.

void AMPS::BlockStore::put ( Block block_)
inline

Return the given chain of Blocks to the free list for reuse.

Used when returning a Block out of order.

Parameters
block_The first Block in the chain.
AMPS_ATOMIC_BASE_TYPE AMPS::BlockStore::put ( amps_uint64_t  sequence_)
inline

Return all Blocks with sequence <= sequence_ for reuse.

Parameters
sequence_The highest sequence number to free.
Returns
The number of items removed.
void AMPS::BlockStore::putAll ( Block block_)
inline

Return all Blocks starting with the given Block to the free list.

Used if corruption was detected or to remove the end of what's stored.

Parameters
block_The beginning of list of Blocks to return.
void AMPS::BlockStore::resize ( size_t  size_)
inline

Resize the buffer to the requested size, adding all new space as unused Blocks for the free list.

Parameters
size_The new size for the _buffer.
Block* AMPS::BlockStore::resizeBuffer ( size_t  size_,
amps_uint32_t *  pNewBlocks_ 
)
inline

Resize the buffer to the requested size, returning all new space.

This is used during recovery when additional space is needed that isn't added immediately to the internal accounting. It's also used by the normal resize function, which takes care of the accounting.

Parameters
size_The new size for the _buffer.
pNewBlocks_A pointer where the number of new blocks created will be stored for the calling function.
amps_uint32_t AMPS::BlockStore::setBlockHeaderSize ( amps_uint32_t  blockHeaderSize_)
inline

Set the size to use for the header for all Blocks.

This should only be called before any Blocks have been created. Returns the old Block header size.

amps_uint32_t AMPS::BlockStore::setBlockSize ( amps_uint32_t  blockSize_)
inline

Set the size to use for all Blocks.

This should only be called before any Blocks have been created. Returns old Block size.

void AMPS::BlockStore::setEndOfUsedList ( Block block_)
inline

Allow containing classes to initialize the used list in recovery.

Parameters
block_A pointer to the last Block of the used list.
void AMPS::BlockStore::setFreeList ( Block block_,
amps_uint32_t  freeCount_ 
)
inline

Allow containing classes to initialize the free list in recovery.

Parameters
block_A pointer the first Block of the free list.
freeCount_The number of free blocks in the chain.
void AMPS::BlockStore::setResizeHandler ( ResizeHandler  resizeHandler_,
void *  userData_ 
)
inline

Set a resize handler that is called with the new total size of the Buffer.

The resize handler can return true to allow the resize or false to prevent it. If it returns false, some action should have been taken to create room or it will be called repeatedly in a loop.

Parameters
resizeHandler_A ResizeHandler function to be invoked for every resize attempt.
userData_A pointer to any data that should be passed to the ResizeHandler when invoked.
void AMPS::BlockStore::setUsedList ( Block block_)
inline

Allow containing classes to initialize the used list in recovery.

Parameters
block_A pointer the first Block of the used list.
bool AMPS::BlockStore::wait ( long  timeout_)
inline

Wait timeout_ ms for a signal.

Parameters
timeout_The maximum time to wait in milliseconds.
Returns
true for signal received, false for timeout.

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