1 /* $Id$ */

     2 

     3 #ifndef  BLOB_HPP

     4 #define  BLOB_HPP

     5 

     6 /** Type-safe version of memcpy().

     7  * @param d destination buffer

     8  * @param s source buffer

     9  * @param num_items number of items to be copied (!not number of bytes!) */

    10 template <class Titem_>

    11 FORCEINLINE void MemCpyT(Titem_* d, const Titem_* s, int num_items = 1)

    12 {

    13 	memcpy(d, s, num_items * sizeof(Titem_));

    14 }

    15 

    16 

    17 /** Base class for simple binary blobs.

    18  *  Item is byte.

    19  *  The word 'simple' means:

    20  *    - no configurable allocator type (always made from heap)

    21  *    - no smart deallocation - deallocation must be called from the same

    22  *        module (DLL) where the blob was allocated

    23  *    - no configurable allocation policy (how big blocks should be allocated)

    24  *    - no extra ownership policy (i.e. 'copy on write') when blob is copied

    25  *    - no thread synchronization at all

    26  *

    27  *  Internal member layout:

    28  *  1. The only class member is pointer to the first item (see union ptr_u).

    29  *  2. Allocated block contains the blob header (see CHdr) followed by the raw byte data.

    30  *     Always, when it allocates memory the allocated size is:

    31  *                                                      sizeof(CHdr) + <data capacity>

    32  *  3. Two 'virtual' members (m_size and m_max_size) are stored in the CHdr at beginning

    33  *     of the alloated block.

    34  *  4. The pointer (in ptr_u) points behind the header (to the first data byte).

    35  *     When memory block is allocated, the sizeof(CHdr) it added to it.

    36  *  5. Benefits of this layout:

    37  *     - items are accessed in the simplest possible way - just dereferencing the pointer,

    38  *       which is good for performance (assuming that data are accessed most often).

    39  *     - sizeof(blob) is the same as the size of any other pointer

    40  *  6. Drawbacks of this layout:

    41  *     - the fact, that pointer to the alocated block is adjusted by sizeof(CHdr) before

    42  *       it is stored can lead to several confusions:

    43  *         - it is not common pattern so the implementation code is bit harder to read

    44  *         - valgrind can generate warning that allocated block is lost (not accessible)

    45  * */

    46 class CBlobBaseSimple {

    47 protected:

    48 	/** header of the allocated memory block */

    49 	struct CHdr {

    50 		int    m_size;      ///< actual blob size in bytes

    51 		int    m_max_size;  ///< maximum (allocated) size in bytes

    52 	};

    53 

    54 	/** type used as class member */

    55 	union {

    56 		int8   *m_pData;    ///< pointer to the first byte of data

    57 		CHdr   *m_pHdr_1;   ///< pointer just after the CHdr holding m_size and m_max_size

    58 	} ptr_u;

    59 

    60 public:

    61 	static const int Ttail_reserve = 4; ///< four extra bytes will be always allocated and zeroed at the end

    62 

    63 	/** default constructor - initializes empty blob */

    64 	FORCEINLINE CBlobBaseSimple() { InitEmpty(); }

    65 	/** copy constructor */

    66 	FORCEINLINE CBlobBaseSimple(const CBlobBaseSimple& src)

    67 	{

    68 		InitEmpty();

    69 		AppendRaw(src);

    70 	}

    71 	/** destructor */

    72 	FORCEINLINE ~CBlobBaseSimple() { Free(); }

    73 protected:

    74 	/** initialize the empty blob by setting the ptr_u.m_pHdr_1 pointer to the static CHdr with

    75 	 *  both m_size and m_max_size containing zero */

    76 	FORCEINLINE void InitEmpty() { static CHdr hdrEmpty[] = {{0, 0}, {0, 0}}; ptr_u.m_pHdr_1 = &hdrEmpty[1]; }

    77 	/** initialize blob by attaching it to the given header followed by data */

    78 	FORCEINLINE void Init(CHdr* hdr) { ptr_u.m_pHdr_1 = &hdr[1]; }

    79 	/** blob header accessor - use it rather than using the pointer arithmetics directly - non-const version */

    80 	FORCEINLINE CHdr& Hdr() { return ptr_u.m_pHdr_1[-1]; }

    81 	/** blob header accessor - use it rather than using the pointer arithmetics directly - const version */

    82 	FORCEINLINE const CHdr& Hdr() const { return ptr_u.m_pHdr_1[-1]; }

    83 	/** return reference to the actual blob size - used when the size needs to be modified */

    84 	FORCEINLINE int& RawSizeRef() { return Hdr().m_size; };

    85 

    86 public:

    87 	/** return true if blob doesn't contain valid data */

    88 	FORCEINLINE bool IsEmpty() const { return RawSize() == 0; }

    89 	/** return the number of valid data bytes in the blob */

    90 	FORCEINLINE int RawSize() const { return Hdr().m_size; };

    91 	/** return the current blob capacity in bytes */

    92 	FORCEINLINE int MaxRawSize() const { return Hdr().m_max_size; };

    93 	/** return pointer to the first byte of data - non-const version */

    94 	FORCEINLINE int8* RawData() { return ptr_u.m_pData; }

    95 	/** return pointer to the first byte of data - const version */

    96 	FORCEINLINE const int8* RawData() const { return ptr_u.m_pData; }

    97 #if 0 // reenable when needed

    98 	/** return the 32 bit CRC of valid data in the blob */

    99 	FORCEINLINE uint32 Crc32() const {return CCrc32::Calc(RawData(), RawSize());}

   100 #endif //0

   101 	/** invalidate blob's data - doesn't free buffer */

   102 	FORCEINLINE void Clear() { RawSizeRef() = 0; }

   103 	/** free the blob's memory */

   104 	FORCEINLINE void Free() { if (MaxRawSize() > 0) {RawFree(&Hdr()); InitEmpty();} }

   105 	/** copy data from another blob - replaces any existing blob's data */

   106 	FORCEINLINE void CopyFrom(const CBlobBaseSimple& src) { Clear(); AppendRaw(src); }

   107 	/** overtake ownership of data buffer from the source blob - source blob will become empty */

   108 	FORCEINLINE void MoveFrom(CBlobBaseSimple& src) { Free(); ptr_u.m_pData = src.ptr_u.m_pData; src.InitEmpty(); }

   109 	/** swap buffers (with data) between two blobs (this and source blob) */

   110 	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; }

   111 

   112 	/** append new bytes at the end of existing data bytes - reallocates if necessary */

   113 	FORCEINLINE void AppendRaw(int8 *p, int num_bytes)

   114 	{

   115 		assert(p != NULL);

   116 		if (num_bytes > 0) {

   117 			memcpy(GrowRawSize(num_bytes), p, num_bytes);

   118 		} else {

   119 			assert(num_bytes >= 0);

   120 		}

   121 	}

   122 

   123 	/** append bytes from given source blob to the end of existing data bytes - reallocates if necessary */

   124 	FORCEINLINE void AppendRaw(const CBlobBaseSimple& src)

   125 	{

   126 		if (!src.IsEmpty())

   127 			memcpy(GrowRawSize(src.RawSize()), src.RawData(), src.RawSize());

   128 	}

   129 

   130 	/** Reallocate if there is no free space for num_bytes bytes.

   131 	 *  @return pointer to the new data to be added */

   132 	FORCEINLINE int8* MakeRawFreeSpace(int num_bytes)

   133 	{

   134 		assert(num_bytes >= 0);

   135 		int new_size = RawSize() + num_bytes;

   136 		if (new_size > MaxRawSize()) SmartAlloc(new_size);

   137 		FixTail();

   138 		return ptr_u.m_pData + RawSize();

   139 	}

   140 

   141 	/** Increase RawSize() by num_bytes.

   142 	 *  @return pointer to the new data added */

   143 	FORCEINLINE int8* GrowRawSize(int num_bytes)

   144 	{

   145 		int8* pNewData = MakeRawFreeSpace(num_bytes);

   146 		RawSizeRef() += num_bytes;

   147 		return pNewData;

   148 	}

   149 

   150 	/** Decrease RawSize() by num_bytes. */

   151 	FORCEINLINE void ReduceRawSize(int num_bytes)

   152 	{

   153 		if (MaxRawSize() > 0 && num_bytes > 0) {

   154 			assert(num_bytes <= RawSize());

   155 			if (num_bytes < RawSize()) RawSizeRef() -= num_bytes;

   156 			else RawSizeRef() = 0;

   157 		}

   158 	}

   159 	/** reallocate blob data if needed */

   160 	void SmartAlloc(int new_size)

   161 	{

   162 		int old_max_size = MaxRawSize();

   163 		if (old_max_size >= new_size) return;

   164 		// calculate minimum block size we need to allocate

   165 		int min_alloc_size = sizeof(CHdr) + new_size + Ttail_reserve;

   166 		// ask allocation policy for some reasonable block size

   167 		int alloc_size = AllocPolicy(min_alloc_size);

   168 		// allocate new block

   169 		CHdr* pNewHdr = RawAlloc(alloc_size);

   170 		// setup header

   171 		pNewHdr->m_size = RawSize();

   172 		pNewHdr->m_max_size = alloc_size - (sizeof(CHdr) + Ttail_reserve);

   173 		// copy existing data

   174 		if (RawSize() > 0)

   175 			memcpy(pNewHdr + 1, ptr_u.m_pData, pNewHdr->m_size);

   176 		// replace our block with new one

   177 		CHdr* pOldHdr = &Hdr();

   178 		Init(pNewHdr);

   179 		if (old_max_size > 0)

   180 			RawFree(pOldHdr);

   181 	}

   182 	/** simple allocation policy - can be optimized later */

   183 	FORCEINLINE static int AllocPolicy(int min_alloc)

   184 	{

   185 		if (min_alloc < (1 << 9)) {

   186 			if (min_alloc < (1 << 5)) return (1 << 5);

   187 			return (min_alloc < (1 << 7)) ? (1 << 7) : (1 << 9);

   188 		}

   189 		if (min_alloc < (1 << 15)) {

   190 			if (min_alloc < (1 << 11)) return (1 << 11);

   191 			return (min_alloc < (1 << 13)) ? (1 << 13) : (1 << 15);

   192 		}

   193 		if (min_alloc < (1 << 20)) {

   194 			if (min_alloc < (1 << 17)) return (1 << 17);

   195 			return (min_alloc < (1 << 19)) ? (1 << 19) : (1 << 20);

   196 		}

   197 		min_alloc = (min_alloc | ((1 << 20) - 1)) + 1;

   198 		return min_alloc;

   199 	}

   200 

   201 	/** all allocation should happen here */

   202 	static FORCEINLINE CHdr* RawAlloc(int num_bytes) { return (CHdr*)malloc(num_bytes); }

   203 	/** all deallocations should happen here */

   204 	static FORCEINLINE void RawFree(CHdr* p) { free(p); }

   205 	/** fixing the four bytes at the end of blob data - useful when blob is used to hold string */

   206 	FORCEINLINE void FixTail()

   207 	{

   208 		if (MaxRawSize() > 0) {

   209 			int8 *p = &ptr_u.m_pData[RawSize()];

   210 			for (int i = 0; i < Ttail_reserve; i++) p[i] = 0;

   211 		}

   212 	}

   213 };

   214 

   215 /** Blob - simple dynamic Titem_ array. Titem_ (template argument) is a placeholder for any type.

   216  *  Titem_ can be any integral type, pointer, or structure. Using Blob instead of just plain C array

   217  *  simplifies the resource management in several ways:

   218  *  1. When adding new item(s) it automatically grows capacity if needed.

   219  *  2. When variable of type Blob comes out of scope it automatically frees the data buffer.

   220  *  3. Takes care about the actual data size (number of used items).

   221  *  4. Dynamically constructs only used items (as opposite of static array which constructs all items) */

   222 template <class Titem_, class Tbase_ = CBlobBaseSimple>

   223 class CBlobT : public CBlobBaseSimple {

   224 	// make template arguments public:

   225 public:

   226 	typedef Titem_ Titem;

   227 	typedef Tbase_ Tbase;

   228 

   229 	static const int Titem_size = sizeof(Titem);

   230 

   231 	/** Default constructor - makes new Blob ready to accept any data */

   232 	FORCEINLINE CBlobT() : Tbase() {}

   233 	/** Copy constructor - make new blob to become copy of the original (source) blob */

   234 	FORCEINLINE CBlobT(const Tbase& src) : Tbase(src) {assert((RawSize() % Titem_size) == 0);}

   235 	/** Destructor - ensures that allocated memory (if any) is freed */

   236 	FORCEINLINE ~CBlobT() { Free(); }

   237 	/** Check the validity of item index (only in debug mode) */

   238 	FORCEINLINE void CheckIdx(int idx) { assert(idx >= 0); assert(idx < Size()); }

   239 	/** Return pointer to the first data item - non-const version */

   240 	FORCEINLINE Titem* Data() { return (Titem*)RawData(); }

   241 	/** Return pointer to the first data item - const version */

   242 	FORCEINLINE const Titem* Data() const { return (const Titem*)RawData(); }

   243 	/** Return pointer to the idx-th data item - non-const version */

   244 	FORCEINLINE Titem* Data(int idx) { CheckIdx(idx); return (Data() + idx); }

   245 	/** Return pointer to the idx-th data item - const version */

   246 	FORCEINLINE const Titem* Data(int idx) const { CheckIdx(idx); return (Data() + idx); }

   247 	/** Return number of items in the Blob */

   248 	FORCEINLINE int Size() const { return (RawSize() / Titem_size); }

   249 	/** Free the memory occupied by Blob destroying all items */

   250 	FORCEINLINE void Free()

   251 	{

   252 		assert((RawSize() % Titem_size) == 0);

   253 		int old_size = Size();

   254 		if (old_size > 0) {

   255 			// destroy removed items;

   256 			Titem* pI_last_to_destroy = Data(0);

   257 			for (Titem* pI = Data(old_size - 1); pI >= pI_last_to_destroy; pI--) pI->~Titem_();

   258 		}

   259 		Tbase::Free();

   260 	}

   261 	/** Grow number of data items in Blob by given number - doesn't construct items */

   262 	FORCEINLINE Titem* GrowSizeNC(int num_items) { return (Titem*)GrowRawSize(num_items * Titem_size); }

   263 	/** Grow number of data items in Blob by given number - constructs new items (using Titem_'s default constructor) */

   264 	FORCEINLINE Titem* GrowSizeC(int num_items)

   265 	{

   266 		Titem* pI = GrowSizeNC(num_items);

   267 		for (int i = num_items; i > 0; i--, pI++) new (pI) Titem();

   268 	}

   269 	/** Destroy given number of items and reduce the Blob's data size */

   270 	FORCEINLINE void ReduceSize(int num_items)

   271 	{

   272 		assert((RawSize() % Titem_size) == 0);

   273 		int old_size = Size();

   274 		assert(num_items <= old_size);

   275 		int new_size = (num_items <= old_size) ? (old_size - num_items) : 0;

   276 		// destroy removed items;

   277 		Titem* pI_last_to_destroy = Data(new_size);

   278 		for (Titem* pI = Data(old_size - 1); pI >= pI_last_to_destroy; pI--) pI->~Titem();

   279 		// remove them

   280 		ReduceRawSize(num_items * Titem_size);

   281 	}

   282 	/** Append one data item at the end (calls Titem_'s default constructor) */

   283 	FORCEINLINE Titem* AppendNew()

   284 	{

   285 		Titem& dst = *GrowSizeNC(1); // Grow size by one item

   286 		Titem* pNewItem = new (&dst) Titem(); // construct the new item by calling in-place new operator

   287 		return pNewItem;

   288 	}

   289 	/** Append the copy of given item at the end of Blob (using copy constructor) */

   290 	FORCEINLINE Titem* Append(const Titem& src)

   291 	{

   292 		Titem& dst = *GrowSizeNC(1); // Grow size by one item

   293 		Titem* pNewItem = new (&dst) Titem(src); // construct the new item by calling in-place new operator with copy ctor()

   294 		return pNewItem;

   295 	}

   296 	/** Add given items (ptr + number of items) at the end of blob */

   297 	FORCEINLINE Titem* Append(const Titem* pSrc, int num_items)

   298 	{

   299 		Titem* pDst = GrowSizeNC(num_items);

   300 		Titem* pDstOrg = pDst;

   301 		Titem* pDstEnd = pDst + num_items;

   302 		while (pDst < pDstEnd) new (pDst++) Titem(*(pSrc++));

   303 		return pDstOrg;

   304 	}

   305 	/** Remove item with the given index by replacing it by the last item and reducing the size by one */

   306 	FORCEINLINE void RemoveBySwap(int idx)

   307 	{

   308 		CheckIdx(idx);

   309 		// destroy removed item

   310 		Titem* pRemoved = Data(idx);

   311 		RemoveBySwap(pRemoved);

   312 	}

   313 	/** Remove item given by pointer replacing it by the last item and reducing the size by one */

   314 	FORCEINLINE void RemoveBySwap(Titem* pItem)

   315 	{

   316 		Titem* pLast = Data(Size() - 1);

   317 		assert(pItem >= Data() && pItem <= pLast);

   318 		// move last item to its new place

   319 		if (pItem != pLast) {

   320 			pItem->~Titem_();

   321 			new (pItem) Titem_(*pLast);

   322 		}

   323 		// destroy the last item

   324 		pLast->~Titem_();

   325 		// and reduce the raw blob size

   326 		ReduceRawSize(Titem_size);

   327 	}

   328 	/** Ensures that given number of items can be added to the end of Blob. Returns pointer to the

   329 	 *  first free (unused) item */

   330 	FORCEINLINE Titem* MakeFreeSpace(int num_items) { return (Titem*)MakeRawFreeSpace(num_items * Titem_size); }

   331 };

   332 

   333 // simple string implementation

   334 struct CStrA : public CBlobT<char>

   335 {

   336 	typedef CBlobT<char> base;

   337 	CStrA(const char* str = NULL) {Append(str);}

   338 	FORCEINLINE CStrA(const CBlobBaseSimple& src) : base(src) {}

   339 	void Append(const char* str) {if (str != NULL && str[0] != '\0') base::Append(str, (int)strlen(str));}

   340 };

   341 

   342 #endif /* BLOB_HPP */