AMPS C/C++ Client Class Reference AMPS C/C++ Client Version 5.3.5.1

Classes | Public Types | Public Member Functions | List of all members
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
enum | Constants : amps_uint32_t
| Default constant values for BlockStore.

## 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...
Block * | front () const
| Get the first used block in the store. More...
Block * | back () 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...
Block * | get (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...
Block * | resizeBuffer (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...
Buffer * | getBuffer ()
| 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

## ◆ BlockStore()

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

## ◆ acquireRead()

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().

## ◆ addBlocks()

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.

## ◆ back()

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.

## ◆ front()

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.

## ◆ get()

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.

## ◆ getBuffer()

Buffer* AMPS::BlockStore::getBuffer | ( |  | ) |
| inline

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

Returns
  The wrapped buffer.

## ◆ getDefaultResizeBlocks()

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.

## ◆ getDefaultResizeSize()

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.

## ◆ init()

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.

## ◆ put() [1/2]

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.

## ◆ put() [2/2]

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.

## ◆ putAll()

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.

## ◆ resize()

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.

## ◆ resizeBuffer()

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.

## ◆ setBlockHeaderSize()

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.

## ◆ setBlockSize()

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.

## ◆ setEndOfUsedList()

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.

## ◆ setFreeList()

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.

## ◆ setResizeHandler()

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.

## ◆ setUsedList()

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.

## ◆ wait()

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:

- include/amps/BlockStore.hpp