mirror of https://github.com/OpenTTD/OpenTTD.git
(svn r7255) -Comments added for CBlobBaseSimple, CBlobT classes
This commit is contained in:
KUDr
parent
1955d1acd6
commit
f1a7a34f6e
|
|
@ -3,6 +3,10 @@
|
|||
#ifndef BLOB_HPP
|
||||
#define BLOB_HPP
|
||||
|
||||
/** Type-safe version of memcpy().
|
||||
* @param d destination buffer
|
||||
* @param s source buffer
|
||||
* @param num_items number of items to be copied (!not number of bytes!) */
|
||||
template <class Titem_>
|
||||
FORCEINLINE void MemCpyT(Titem_* d, const Titem_* s, int num_items = 1)
|
||||
{
|
||||
|
|
@ -18,51 +22,94 @@ FORCEINLINE void MemCpyT(Titem_* d, const Titem_* s, int num_items = 1)
|
|||
* 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 */
|
||||
* - no thread synchronization at all
|
||||
*
|
||||
* Internal member layout:
|
||||
* 1. The only class member is pointer to the first item (see union ptr_u).
|
||||
* 2. Allocated block contains the blob header (see CHdr) followed by the raw byte data.
|
||||
* Always, when it allocates memory the allocated size is:
|
||||
* sizeof(CHdr) + <data capacity>
|
||||
* 3. Two 'virtual' members (m_size and m_max_size) are stored in the CHdr at beginning
|
||||
* of the alloated block.
|
||||
* 4. The pointer (in ptr_u) points behind the header (to the first data byte).
|
||||
* When memory block is allocated, the sizeof(CHdr) 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 pointer to the alocated block is adjusted by sizeof(CHdr) before
|
||||
* it is stored can lead to several confusions:
|
||||
* - it is not common pattern so the implementation code is bit harder to read
|
||||
* - valgrind can generate warning that allocated block is lost (not accessible)
|
||||
* */
|
||||
class CBlobBaseSimple {
|
||||
protected:
|
||||
/** header of the allocated memory block */
|
||||
struct CHdr {
|
||||
int m_size; // actual blob size in bytes
|
||||
int m_max_size; // maximum (allocated) size in bytes
|
||||
int m_size; ///< actual blob size in bytes
|
||||
int m_max_size; ///< maximum (allocated) size in bytes
|
||||
};
|
||||
|
||||
/** type used as class member */
|
||||
union {
|
||||
int8 *m_pData;
|
||||
CHdr *m_pHdr_1;
|
||||
int8 *m_pData; ///< pointer to the first byte of data
|
||||
CHdr *m_pHdr_1; ///< pointer just after the CHdr holding m_size and m_max_size
|
||||
} ptr_u;
|
||||
|
||||
public:
|
||||
static const int Ttail_reserve = 4; // four extra bytes will be always allocated and zeroed at the end
|
||||
static const int Ttail_reserve = 4; ///< four extra bytes will be always allocated and zeroed at the end
|
||||
|
||||
/** default constructor - initializes empty blob */
|
||||
FORCEINLINE CBlobBaseSimple() { InitEmpty(); }
|
||||
/** copy constructor */
|
||||
FORCEINLINE CBlobBaseSimple(const CBlobBaseSimple& src)
|
||||
{
|
||||
InitEmpty();
|
||||
AppendRaw(src);
|
||||
}
|
||||
/** destructor */
|
||||
FORCEINLINE ~CBlobBaseSimple() { Free(); }
|
||||
protected:
|
||||
/** initialize the empty blob by setting the ptr_u.m_pHdr_1 pointer to the static CHdr with
|
||||
* both m_size and m_max_size containing zero */
|
||||
FORCEINLINE void InitEmpty() { static CHdr hdrEmpty[] = {{0, 0}, {0, 0}}; ptr_u.m_pHdr_1 = &hdrEmpty[1]; }
|
||||
/** initialize blob by attaching it to the given header followed by data */
|
||||
FORCEINLINE void Init(CHdr* hdr) { ptr_u.m_pHdr_1 = &hdr[1]; }
|
||||
/** blob header accessor - use it rather than using the pointer arithmetics directly - non-const version */
|
||||
FORCEINLINE CHdr& Hdr() { return ptr_u.m_pHdr_1[-1]; }
|
||||
/** blob header accessor - use it rather than using the pointer arithmetics directly - const version */
|
||||
FORCEINLINE const CHdr& Hdr() const { return ptr_u.m_pHdr_1[-1]; }
|
||||
/** return reference to the actual blob size - used when the size needs to be modified */
|
||||
FORCEINLINE int& RawSizeRef() { return Hdr().m_size; };
|
||||
|
||||
public:
|
||||
/** return true if blob doesn't contain valid data */
|
||||
FORCEINLINE bool IsEmpty() const { return RawSize() == 0; }
|
||||
/** return the number of valid data bytes in the blob */
|
||||
FORCEINLINE int RawSize() const { return Hdr().m_size; };
|
||||
/** return the current blob capacity in bytes */
|
||||
FORCEINLINE int MaxRawSize() const { return Hdr().m_max_size; };
|
||||
/** return pointer to the first byte of data - non-const version */
|
||||
FORCEINLINE int8* RawData() { return ptr_u.m_pData; }
|
||||
/** return pointer to the first byte of data - const version */
|
||||
FORCEINLINE const int8* RawData() const { return ptr_u.m_pData; }
|
||||
#if 0 // reenable when needed
|
||||
/** return the 32 bit CRC of valid data in the blob */
|
||||
FORCEINLINE uint32 Crc32() const {return CCrc32::Calc(RawData(), RawSize());}
|
||||
#endif //0
|
||||
/** invalidate blob's data - doesn't free buffer */
|
||||
FORCEINLINE void Clear() { RawSizeRef() = 0; }
|
||||
/** free the blob's memory */
|
||||
FORCEINLINE void Free() { if (MaxRawSize() > 0) {RawFree(&Hdr()); InitEmpty();} }
|
||||
/** copy data from another blob - replaces any existing blob's data */
|
||||
FORCEINLINE void CopyFrom(const CBlobBaseSimple& src) { Clear(); AppendRaw(src); }
|
||||
/** overtake ownership of data buffer from the source blob - source blob will become empty */
|
||||
FORCEINLINE void MoveFrom(CBlobBaseSimple& src) { Free(); ptr_u.m_pData = src.ptr_u.m_pData; src.InitEmpty(); }
|
||||
/** swap buffers (with data) between two blobs (this and source blob) */
|
||||
FORCEINLINE void Swap(CBlobBaseSimple& src) { int8 *tmp = ptr_u.m_pData; ptr_u.m_pData = src.ptr_u.m_pData; src.ptr_u.m_pData = tmp; }
|
||||
|
||||
/** append new bytes at the end of existing data bytes - reallocates if necessary */
|
||||
FORCEINLINE void AppendRaw(int8 *p, int num_bytes)
|
||||
{
|
||||
assert(p != NULL);
|
||||
|
|
@ -73,6 +120,7 @@ public:
|
|||
}
|
||||
}
|
||||
|
||||
/** append bytes from given source blob to the end of existing data bytes - reallocates if necessary */
|
||||
FORCEINLINE void AppendRaw(const CBlobBaseSimple& src)
|
||||
{
|
||||
if (!src.IsEmpty())
|
||||
|
|
@ -164,6 +212,13 @@ public:
|
|||
}
|
||||
};
|
||||
|
||||
/** Blob - simple dynamic Titem_ array. Titem_ (template argument) is a placeholder for any type.
|
||||
* Titem_ can be any integral type, pointer, or structure. Using Blob instead of just plain C array
|
||||
* simplifies the resource management in several ways:
|
||||
* 1. When adding new item(s) it automatically grows capacity if needed.
|
||||
* 2. When variable of type Blob comes out of scope it automatically frees the data buffer.
|
||||
* 3. Takes care about the actual data size (number of used items).
|
||||
* 4. Dynamically constructs only used items (as opposite of static array which constructs all items) */
|
||||
template <class Titem_, class Tbase_ = CBlobBaseSimple>
|
||||
class CBlobT : public CBlobBaseSimple {
|
||||
// make template arguments public:
|
||||
|
|
@ -173,15 +228,25 @@ public:
|
|||
|
||||
static const int Titem_size = sizeof(Titem);
|
||||
|
||||
/** Default constructor - makes new Blob ready to accept any data */
|
||||
FORCEINLINE CBlobT() : Tbase() {}
|
||||
/** Copy constructor - make new blob to become copy of the original (source) blob */
|
||||
FORCEINLINE CBlobT(const Tbase& src) : Tbase(src) {assert((RawSize() % Titem_size) == 0);}
|
||||
/** Destructor - ensures that allocated memory (if any) is freed */
|
||||
FORCEINLINE ~CBlobT() { Free(); }
|
||||
/** Check the validity of item index (only in debug mode) */
|
||||
FORCEINLINE void CheckIdx(int idx) { assert(idx >= 0); assert(idx < Size()); }
|
||||
/** Return pointer to the first data item - non-const version */
|
||||
FORCEINLINE Titem* Data() { return (Titem*)RawData(); }
|
||||
/** Return pointer to the first data item - const version */
|
||||
FORCEINLINE const Titem* Data() const { return (const Titem*)RawData(); }
|
||||
/** Return pointer to the idx-th data item - non-const version */
|
||||
FORCEINLINE Titem* Data(int idx) { CheckIdx(idx); return (Data() + idx); }
|
||||
/** Return pointer to the idx-th data item - const version */
|
||||
FORCEINLINE const Titem* Data(int idx) const { CheckIdx(idx); return (Data() + idx); }
|
||||
/** Return number of items in the Blob */
|
||||
FORCEINLINE int Size() const { return (RawSize() / Titem_size); }
|
||||
/** Free the memory occupied by Blob destroying all items */
|
||||
FORCEINLINE void Free()
|
||||
{
|
||||
assert((RawSize() % Titem_size) == 0);
|
||||
|
|
@ -193,12 +258,15 @@ public:
|
|||
}
|
||||
Tbase::Free();
|
||||
}
|
||||
/** Grow number of data items in Blob by given number - doesn't construct items */
|
||||
FORCEINLINE Titem* GrowSizeNC(int num_items) { return (Titem*)GrowRawSize(num_items * Titem_size); }
|
||||
/** Grow number of data items in Blob by given number - constructs new items (using Titem_'s default constructor) */
|
||||
FORCEINLINE Titem* GrowSizeC(int num_items)
|
||||
{
|
||||
Titem* pI = GrowSizeNC(num_items);
|
||||
for (int i = num_items; i > 0; i--, pI++) new (pI) Titem();
|
||||
}
|
||||
/** Destroy given number of items and reduce the Blob's data size */
|
||||
FORCEINLINE void ReduceSize(int num_items)
|
||||
{
|
||||
assert((RawSize() % Titem_size) == 0);
|
||||
|
|
@ -211,18 +279,21 @@ public:
|
|||
// remove them
|
||||
ReduceRawSize(num_items * Titem_size);
|
||||
}
|
||||
/** Append one data item at the end (calls Titem_'s default constructor) */
|
||||
FORCEINLINE Titem* AppendNew()
|
||||
{
|
||||
Titem& dst = *GrowSizeNC(1);
|
||||
Titem* pNewItem = new (&dst) Titem();
|
||||
Titem& dst = *GrowSizeNC(1); // Grow size by one item
|
||||
Titem* pNewItem = new (&dst) Titem(); // construct the new item by calling in-place new operator
|
||||
return pNewItem;
|
||||
}
|
||||
/** Append the copy of given item at the end of Blob (using copy constructor) */
|
||||
FORCEINLINE Titem* Append(const Titem& src)
|
||||
{
|
||||
Titem& dst = *GrowSizeNC(1);
|
||||
Titem* pNewItem = new (&dst) Titem(src);
|
||||
Titem& dst = *GrowSizeNC(1); // Grow size by one item
|
||||
Titem* pNewItem = new (&dst) Titem(src); // construct the new item by calling in-place new operator with copy ctor()
|
||||
return pNewItem;
|
||||
}
|
||||
/** Add given items (ptr + number of items) at the end of blob */
|
||||
FORCEINLINE Titem* Append(const Titem* pSrc, int num_items)
|
||||
{
|
||||
Titem* pDst = GrowSizeNC(num_items);
|
||||
|
|
@ -231,6 +302,7 @@ public:
|
|||
while (pDst < pDstEnd) new (pDst++) Titem(*(pSrc++));
|
||||
return pDstOrg;
|
||||
}
|
||||
/** Remove item with the given index by replacing it by the last item and reducing the size by one */
|
||||
FORCEINLINE void RemoveBySwap(int idx)
|
||||
{
|
||||
CheckIdx(idx);
|
||||
|
|
@ -238,6 +310,7 @@ public:
|
|||
Titem* pRemoved = Data(idx);
|
||||
RemoveBySwap(pRemoved);
|
||||
}
|
||||
/** Remove item given by pointer replacing it by the last item and reducing the size by one */
|
||||
FORCEINLINE void RemoveBySwap(Titem* pItem)
|
||||
{
|
||||
Titem* pLast = Data(Size() - 1);
|
||||
|
|
@ -252,6 +325,8 @@ public:
|
|||
// and reduce the raw blob size
|
||||
ReduceRawSize(Titem_size);
|
||||
}
|
||||
/** Ensures that given number of items can be added to the end of Blob. Returns pointer to the
|
||||
* first free (unused) item */
|
||||
FORCEINLINE Titem* MakeFreeSpace(int num_items) { return (Titem*)MakeRawFreeSpace(num_items * Titem_size); }
|
||||
};
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue