Endpoint Library Documentation: DataBlock Classes

DataBlock is an abstraction for "a block of data". Each subclass of DataBlock has a kind of "personality," because each has different semantics that are useful in different situations. Each subclass was designed with specific uses in mind, and together they cover the common cases well.

DataBlock

The DataBlock base class is just a smart structure holding a pointer to a raw block of memory and an integer holding the size of that memory. It only performs shallow copies and does not allocate or deallocate memory. It is mainly useful as a temporary alias to another DataBlock, especially one of its subclasses.

The religiously-object-oriented among you will notice that DataBlock has public data members. This was done on purpose, because the classes were designed that way. Let me clarify that: the data members of these classes won't change, because their current form is part of the design, not an implementation detail. Incidentally, the DataBlock family once did hide everything behind Get*() and Set*() functions. However, of necessity GetData() returned a non-const pointer, which pretty much threw any data hiding out the window.

FixedDataBlock

A FixedDataBlock is a fixed-size data block that is allocated once on normal and copy creation, and never reallocated, even when assigned or copied from a larger DataBlock. (If the source data block is larger than itself, FixedDataBlock just copies as much data as it can.) It is a convenient way of creating a block of memory on the heap that will go away when the FixedDataBlock object goes away. It also has the nice property that it always creates its own memory, rather than taking ownership of memory someone else created, so double-delete bugs are impossible with FixedDataBlocks.

ManagedDataBlock

The ManagedDataBlock implements a reference-counted data block. That is, it creates a given block of memory only once, and then each copy of that object simply refers to the original block of memory. When the last copy goes away, so does the data. In brief, it performs shallow copies on normal creation, shallow copies on copy creation and assignment from ManagedDataBlocks, and deep copies when copying or assigning from other kinds of DataBlocks. (It can also allocate an empty block of memory with the (int) constructor.) It always owns the memory it encapsulates, and therefore always deallocates it when the reference counter reaches 0.

SelfishDataBlock

The SelfishDataBlock is just as it sounds: a completely selfish owner of memory. This is because SelfishDataBlock always performs shallow copies and always deletes the memory it encapsulates. Copy creation and assignment from other SelfishDataBlocks is explicitly disallowed, because it can only result in a double-delete. I haven't found much use for it, but it does come in handy when someone is giving you ownership of a piece of memory.