OpenTTD: ByteBlob Class Reference

OpenTTD

- Main Page
- Related Pages
- Modules
- Namespaces
- Data Structures
- Files

- Data Structures
- Class Hierarchy
- Data Fields

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:

## 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
BlobHeader & | Hdr ()
| blob header accessor - use it rather than using the pointer arithmetics directly - non-const version
const BlobHeader & | Hdr () 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 BlobHeader * | RawAlloc (size_t num_bytes)
| all allocation should happen here
static BlobHeader * | Zero ()
| 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:

- no configurable allocator type (always made from heap)
- no smart deallocation - deallocation must be called from the same module (DLL) where the blob was allocated
- no configurable allocation policy (how big blocks should be allocated)
- no extra ownership policy (i.e. 'copy on write') when blob is copied
- no thread synchronization at all

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 250 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 239 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:

- src/misc/blob.hpp
- src/misc/dbg_helpers.cpp