OpenTTD
Data Structures | Public Member Functions | Static Public Attributes | Protected Member Functions | Static Protected Member Functions | Protected Attributes | Static Private Attributes
ByteBlob Class Reference

Base class for simple binary blobs. More...

#include <blob.hpp>

Inheritance diagram for ByteBlob:
CBlobT< T > CBlobT< char > CStrA

Data Structures

struct  BlobHeader
 header of the allocated memory block More...

Public Member Functions

 ByteBlob ()
 default constructor - initializes empty blob
 ByteBlob (const ByteBlob &src)
 copy constructor
 ByteBlob (BlobHeader *const &src)
 move constructor - take ownership of blob data
 ~ByteBlob ()
 destructor
bool IsEmpty () const
 return true if blob doesn't contain valid data
size_t Length () const
 return the number of valid data bytes in the blob
size_t Capacity () const
 return the current blob capacity in bytes
byte * Begin ()
 return pointer to the first byte of data - non-const version
const byte * Begin () const
 return pointer to the first byte of data - const version
void Clear ()
 invalidate blob's data - doesn't free buffer
void Free ()
 free the blob's memory
void AppendRaw (const void *p, size_t num_bytes)
 append new bytes at the end of existing data bytes - reallocates if necessary
void AppendRaw (const ByteBlob &src)
 append bytes from given source blob to the end of existing data bytes - reallocates if necessary
byte * Prepare (size_t num_bytes)
 Reallocate if there is no free space for num_bytes bytes.
byte * Append (size_t num_bytes)
 Increase Length() by num_bytes.
void SmartAlloc (size_t new_size)
 reallocate blob data if needed
void FixTail () const
 fixing the four bytes at the end of blob data - useful when blob is used to hold string

Static Public Attributes

static const size_t tail_reserve = 4
 four extra bytes will be always allocated and zeroed at the end
static const size_t header_size = sizeof(BlobHeader)

Protected Member Functions

void InitEmpty ()
 initialize the empty blob
void Init (BlobHeader *src)
 initialize blob by attaching it to the given header followed by data
BlobHeaderHdr ()
 blob header accessor - use it rather than using the pointer arithmetics directly - non-const version
const BlobHeaderHdr () const
 blob header accessor - use it rather than using the pointer arithmetics directly - const version
size_t & LengthRef ()
 return reference to the actual blob size - used when the size needs to be modified

Static Protected Member Functions

static BlobHeaderRawAlloc (size_t num_bytes)
 all allocation should happen here
static BlobHeaderZero ()
 Return header pointer to the static BlobHeader with both items and capacity containing zero.
static size_t AllocPolicy (size_t min_alloc)
 simple allocation policy - can be optimized later
static void RawFree (BlobHeader *p)
 all deallocations should happen here

Protected Attributes

union {
   byte *   data
 ptr to the first byte of data
   BlobHeader *   header
 ptr just after the BlobHeader holding items and capacity
}; 
 type used as class member

Static Private Attributes

static BlobHeader hdrEmpty [] = {{0, 0}, {0, 0}}
 Just to silence an unsilencable GCC 4.4+ warning Note: This cannot be 'const' as we do a lot of 'hdrEmpty[0]->items += 0;' and 'hdrEmpty[0]->capacity += 0;' after const_casting.

Detailed Description

Base class for simple binary blobs.

Item is byte. The word 'simple' means:

Internal member layout:

  1. The only class member is pointer to the first item (see union).
  2. Allocated block contains the blob header (see BlobHeader) followed by the raw byte data. Always, when it allocates memory the allocated size is: sizeof(BlobHeader) + <data capacity>="">
  3. Two 'virtual' members (items and capacity) are stored in the BlobHeader at beginning of the allocated block.
  4. The pointer of the union pobsize_ts behind the header (to the first data byte). When memory block is allocated, the sizeof(BlobHeader) it added to it.
  5. Benefits of this layout:
    • items are accessed in the simplest possible way - just dereferencing the pointer, which is good for performance (assuming that data are accessed most often).
    • sizeof(blob) is the same as the size of any other pointer
  6. Drawbacks of this layout:
    • the fact that a pointer to the allocated block is adjusted by sizeof(BlobHeader) before it is stored can lead to several confusions:
      • it is not a common pattern so the implementation code is bit harder to read.
      • valgrind may generate a warning that the allocated block is lost (not accessible).

Definition at line 47 of file blob.hpp.

Member Function Documentation

byte* ByteBlob::Append ( size_t  num_bytes)
inline

Increase Length() by num_bytes.

Returns
pointer to the new data added

Definition at line 253 of file blob.hpp.

References LengthRef(), and Prepare().

Referenced by AppendRaw(), and CBlobT< char >::GrowSizeNC().

byte* ByteBlob::Prepare ( size_t  num_bytes)
inline

Reallocate if there is no free space for num_bytes bytes.

Returns
pointer to the new data to be added

Definition at line 242 of file blob.hpp.

References Capacity(), data, Length(), and SmartAlloc().

Referenced by Append(), and CBlobT< char >::MakeFreeSpace().

Field Documentation

ByteBlob::BlobHeader ByteBlob::hdrEmpty = {{0, 0}, {0, 0}}
staticprivate

Just to silence an unsilencable GCC 4.4+ warning Note: This cannot be 'const' as we do a lot of 'hdrEmpty[0]->items += 0;' and 'hdrEmpty[0]->capacity += 0;' after const_casting.

Just to silence an unsilencable GCC 4.4+ warning.

Definition at line 67 of file blob.hpp.

Referenced by RawFree(), and Zero().


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