FARGOS/VISTA Object Management Environment Core  ..
FARGOS/VISTA Object Management Environment Core Table of Contents
BufferRegion Class Referenceabstract

Interface to a buffer region. This is an abstract class. More...

#include <circular_bfr.hpp>

+ Inheritance diagram for BufferRegion:

Public Types

enum  OwnershipState { NOT_OWNER = 0, OWN_BLOCK = 1, OWN_MAP = 2, OWN_RECORD = 3 }
 
typedef uint_fast8_t BufferRegion_Overhead_t
 

Public Member Functions

 BufferRegion (unsigned char *ptr, size_t len, size_t blk_size, OwnershipState ownedBy=NOT_OWNER)
 
virtual ~BufferRegion ()
 Destructor for a BufferRegion. More...
 
void replaceRegion (unsigned char *ptr, size_t len, size_t blk_size, OwnershipState ownedBy=NOT_OWNER)
 Reconstruct the buffer using a new region. More...
 
void setOwnership (OwnershipState newOwnership)
 Change administrative ownership of region. More...
 
OwnershipState getOwnership () const
 Return the administrative ownership state of the region. More...
 
size_t getRegionLength () const OME_ALWAYS_INLINE
 Return the number of bytes in the region. More...
 
size_t getBlockSize () const OME_ALWAYS_INLINE
 Return the block size set for the region. More...
 
unsigned char * getBufferBase () const OME_ALWAYS_INLINE
 Return the address of the buffer region. More...
 
virtual SharedBufferAllocRecordgetActiveListHead ()
 Return first active allocation record. More...
 
virtual SharedBufferAllocRecordgetFreeListHead ()
 Return first free allocation record. More...
 
virtual SharedBufferAllocRecordtraverseNextBlock (SharedBufferAllocRecord *record)
 Traverse to next allocation record on current chain. More...
 
virtual unsigned char * blockAddress (const SharedBufferAllocRecord *record)
 
virtual SharedBufferAllocRecordallocateBlock (size_t len)=0
 
virtual void returnBlock (SharedBufferAllocRecord *record)=0
 
virtual BufferRegion_Overhead_t getBlockOverhead () const =0
 Interface to return the per-block overhead associated with an allocator. More...
 
int checkLists (int displayFlag)
 Debug routine used to verify integrity of block lists. More...
 

Protected Attributes

unsigned char * region
 
size_t regionLength
 
size_t blockSize
 
size_t availableBlocks
 
OwnershipState ownership
 

Detailed Description

Interface to a buffer region. This is an abstract class.

A BufferRegion object manages a portion of address space which is typically a shared memory segment. In contrast to conventional memory allocation routines, a BufferRegion works with SharedBufferAllocRecord objects that use only offsets from the base of the region and thus are able to be correctly interpreted if the region is mapped at a different address by a different process or the file is processed offline.

Member Typedef Documentation

◆ BufferRegion_Overhead_t

Member Enumeration Documentation

◆ OwnershipState

Enumerator
NOT_OWNER 

indicates region is not owned by this BufferRegion

OWN_BLOCK 

indicates region is owned by the BufferRegion and should be recovered when deleted.

OWN_MAP 

indicates region is a memory map owned by the BufferRegion and should be unmapped when deleted.

OWN_RECORD 

Constructor & Destructor Documentation

◆ BufferRegion()

BufferRegion::BufferRegion ( unsigned char *  ptr,
size_t  len,
size_t  blk_size,
BufferRegion::OwnershipState  ownedBy = NOT_OWNER 
)

◆ ~BufferRegion()

BufferRegion::~BufferRegion ( )
virtual

Destructor for a BufferRegion.

See the discussion in the BufferRegion constructor as to the effect of the administrative ownership state.

References OWN_BLOCK, OWN_MAP, ownership, region, and regionLength.

Member Function Documentation

◆ allocateBlock()

virtual SharedBufferAllocRecord* BufferRegion::allocateBlock ( size_t  len)
pure virtual

Interface to allocate a block of storage from the buffer region.

Parameters
lenspecifies the number of bytes needed for the block.
Return values
nullptrindicates a block could not be allocated.

Implemented in FixedBufferManager, and CircularBufferManager.

Referenced by LogManager::allocateBuffer(), LogManager::copyAndWriteData(), IO_Processor::doConsumeLoop(), and HTTPstatusLog::emitLineAsHTTPevent().

◆ blockAddress()

virtual unsigned char* BufferRegion::blockAddress ( const SharedBufferAllocRecord record)
inlinevirtual

Convert a buffer allocation record into a physical address in the context of the local process' address space.

Parameters
recordpoints to a SharedBufferAllocRecord that should be translated in the context of this buffer region.

References SharedBufferAllocRecord_32::offset_block, and region.

Referenced by CircularBufferManager::allocateBlock(), FixedBufferManager::allocateBlock(), IO_Processor::bufferAddress(), LogManager::bufferAddress(), IO_Processor::bufferHeaderAddress(), LogManager::copyAndWriteDataToBuffer(), ReadMappedCircularBuffer::processBlock(), CircularBufferManager::returnBlock(), and FixedBufferManager::returnBlock().

◆ checkLists()

int BufferRegion::checkLists ( int  displayFlag)

Debug routine used to verify integrity of block lists.

Parameters
displayFlagspecifies the amount of verbosity. A value of 0 only reports corruption in the chain links. A value of 1 provides a summary of the number of free and active blocks and bytes. A value of 2 displays information about each active and free block.
Return values
0indicates no corruption was detected.
1indicates some corruption was detected.

References SharedBufferAllocRecord_32::blockLen, display(), getActiveListHead(), getFreeListHead(), SharedBufferAllocRecord_32::offset_allocRecord, SharedBufferAllocRecord_32::offset_block, SharedBufferAllocRecord_32::offset_nextInChain, region, traverseNextBlock(), and SharedBufferAllocRecord_32::usedLen.

Referenced by CircularBufferManager::allocateBlock(), and CircularBufferManager::returnBlock().

◆ getActiveListHead()

SharedBufferAllocRecord * BufferRegion::getActiveListHead ( )
virtual

◆ getBlockOverhead()

virtual BufferRegion_Overhead_t BufferRegion::getBlockOverhead ( ) const
pure virtual

Interface to return the per-block overhead associated with an allocator.

Implemented in FixedBufferManager, and CircularBufferManager.

◆ getBlockSize()

size_t BufferRegion::getBlockSize ( ) const
inline

Return the block size set for the region.

References blockSize.

Referenced by IO_Processor::IO_Processor().

◆ getBufferBase()

unsigned char* BufferRegion::getBufferBase ( ) const
inline

◆ getFreeListHead()

SharedBufferAllocRecord * BufferRegion::getFreeListHead ( )
virtual

Return first free allocation record.

References GET_VAL32, region, sharedBufferSegmentIsInNativeByteOrder(), and sharedBufferSegmentSizeIs64bit().

Referenced by checkLists().

◆ getOwnership()

OwnershipState BufferRegion::getOwnership ( ) const
inline

Return the administrative ownership state of the region.

References ownership.

◆ getRegionLength()

size_t BufferRegion::getRegionLength ( ) const
inline

◆ replaceRegion()

void BufferRegion::replaceRegion ( unsigned char *  ptr,
size_t  len,
size_t  blk_size,
BufferRegion::OwnershipState  ownedBy = NOT_OWNER 
)

Reconstruct the buffer using a new region.

Parameters
ptrpoints at the base of the region of memory to be used.
lenindicates the number of bytes available in the region.
blk_sizeindicates the maximum individual allocation unit.
ownedByspecifies the initial ownership of the block

NOTE: This function should be used with caution. Many usage cases would be surprised to have an existing region be invalidated and replaced with an alternate region, potentially of different size.

References blockSize, OWN_BLOCK, ownership, region, and regionLength.

◆ returnBlock()

virtual void BufferRegion::returnBlock ( SharedBufferAllocRecord record)
pure virtual

Interface to return a block of storage previously obtained by an allocateBlock() call.

Parameters
recordpoints to the SharedBufferAllocRecord representing the block to be returned.

NOTE: not all subclasses can do something useful with a returned block.

Implemented in FixedBufferManager, and CircularBufferManager.

Referenced by Extract_And_Process_Document_Stream::addIOblockThenProcess(), IO_Processor::doConsumeLoop(), IO_Processor::doProcessLoop(), LogManager::returnBuffer(), and IO_Processor::submitOrProcessBlock().

◆ setOwnership()

void BufferRegion::setOwnership ( OwnershipState  newOwnership)
inline

Change administrative ownership of region.

Parameters
newOwnershipspecifies the new ownership state.

References ownership.

Referenced by LogManager::LogManager().

◆ traverseNextBlock()

SharedBufferAllocRecord * BufferRegion::traverseNextBlock ( SharedBufferAllocRecord record)
virtual

Traverse to next allocation record on current chain.

Parameters
recordpoints to the current block. The first record of the active or free list is obtained by a call to getActiveListHead() or getFreeListHead(), respectively.
Return values
nullptrindicates the end of the chain has been reached.

References GET_VAL, region, sharedBufferSegmentIsInNativeByteOrder(), and sharedBufferSegmentSizeIs64bit().

Referenced by checkLists(), and ReadMappedCircularBuffer::traverseBlockChain().

Member Data Documentation

◆ availableBlocks

size_t BufferRegion::availableBlocks
protected

◆ blockSize

◆ ownership

OwnershipState BufferRegion::ownership
protected

◆ region

◆ regionLength


The documentation for this class was generated from the following files:
Generated: Fri Jul 31 2020 18:19:16
Support Information