1

/* $Id$ */

     2

     5

#ifndef  BLOB_HPP

     6

#define  BLOB_HPP

     7

     8

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

     9

 * @param d destination buffer

    10

 * @param s source buffer

    11

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

    12

template <class Titem_>

    13

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

    14

{

    15

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

    16

}

    17

    18

    19

/** Base class for simple binary blobs.

    20

 *  Item is byte.

    21

 *  The word 'simple' means:

    22

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

    23

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

    24

 *        module (DLL) where the blob was allocated

    25

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

    26

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

    27

 *    - no thread synchronization at all

    28

 *

    29

 *  Internal member layout:

    30

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

    31

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

    32

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

    33

 *                                                      sizeof(CHdr) + <data capacity>

    34

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

    35

 *     of the alloated block.

    36

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

    37

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

    38

 *  5. Benefits of this layout:

    39

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

    40

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

    41

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

    42

 *  6. Drawbacks of this layout:

    43

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

    44

 *       it is stored can lead to several confusions:

    45

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

    46

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

    47

 * */

    48

class CBlobBaseSimple {

    49

protected:

    50

	/** header of the allocated memory block */

    51

	struct CHdr {

    52

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

    53

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

    54

	};

    55

    56

	/** type used as class member */

    57

	union {

    58

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

    59

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

    60

	} ptr_u;

    61

    62

public:

    63

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

    64

    65

	/** default constructor - initializes empty blob */

    66

	FORCEINLINE CBlobBaseSimple() { InitEmpty(); }

    67

	/** copy constructor */

    68

	FORCEINLINE CBlobBaseSimple(const CBlobBaseSimple& src)

    69

	{

    70

		InitEmpty();

    71

		AppendRaw(src);

    72

	}

    73

	/** destructor */

    74

	FORCEINLINE ~CBlobBaseSimple() { Free(); }

    75

protected:

    76

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

    77

	 *  both m_size and m_max_size containing zero */

    78

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

    79

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

    80

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

    81

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

    82

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

    83

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

    84

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

    85

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

    86

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

    87

    88

public:

    89

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

    90

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

    91

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

    92

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

    93

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

    94

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

    95

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

    96

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

    97

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

    98

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

    99

#if 0 // reenable when needed

   100

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

   101

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

   102

#endif //0

   103

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

   104

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

   105

	/** free the blob's memory */

   106

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

   107

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

   108

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

   109

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

   110

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

   111

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

   112

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

   113

   114

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

   115

	FORCEINLINE void AppendRaw(int8 *p, int num_bytes)

   116

	{

   117

		assert(p != NULL);

   118

		if (num_bytes > 0) {

   119

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

   120

		} else {

   121

			assert(num_bytes >= 0);

   122

		}

   123

	}

   124

   125

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

   126

	FORCEINLINE void AppendRaw(const CBlobBaseSimple& src)

   127

	{

   128

		if (!src.IsEmpty())

   129

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

   130

	}

   131

   132

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

   133

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

   134

	FORCEINLINE int8* MakeRawFreeSpace(int num_bytes)

   135

	{

   136

		assert(num_bytes >= 0);

   137

		int new_size = RawSize() + num_bytes;

   138

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

   139

		FixTail();

   140

		return ptr_u.m_pData + RawSize();

   141

	}

   142

   143

	/** Increase RawSize() by num_bytes.

   144

	 *  @return pointer to the new data added */

   145

	FORCEINLINE int8* GrowRawSize(int num_bytes)

   146

	{

   147

		int8* pNewData = MakeRawFreeSpace(num_bytes);

   148

		RawSizeRef() += num_bytes;

   149

		return pNewData;

   150

	}

   151

   152

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

   153

	FORCEINLINE void ReduceRawSize(int num_bytes)

   154

	{

   155

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

   156

			assert(num_bytes <= RawSize());

   157

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

   158

			else RawSizeRef() = 0;

   159

		}

   160

	}

   161

	/** reallocate blob data if needed */

   162

	void SmartAlloc(int new_size)

   163

	{

   164

		int old_max_size = MaxRawSize();

   165

		if (old_max_size >= new_size) return;

   166

		// calculate minimum block size we need to allocate

   167

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

   168

		// ask allocation policy for some reasonable block size

   169

		int alloc_size = AllocPolicy(min_alloc_size);

   170

		// allocate new block

   171

		CHdr* pNewHdr = RawAlloc(alloc_size);

   172

		// setup header

   173

		pNewHdr->m_size = RawSize();

   174

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

   175

		// copy existing data

   176

		if (RawSize() > 0)

   177

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

   178

		// replace our block with new one

   179

		CHdr* pOldHdr = &Hdr();

   180

		Init(pNewHdr);

   181

		if (old_max_size > 0)

   182

			RawFree(pOldHdr);

   183

	}

   184

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

   185

	FORCEINLINE static int AllocPolicy(int min_alloc)

   186

	{

   187

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

   188

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

   189

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

   190

		}

   191

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

   192

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

   193

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

   194

		}

   195

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

   196

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

   197

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

   198

		}

   199

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

   200

		return min_alloc;

   201

	}

   202

   203

	/** all allocation should happen here */

   204

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

   205

	/** all deallocations should happen here */

   206

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

   207

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

   208

	FORCEINLINE void FixTail()

   209

	{

   210

		if (MaxRawSize() > 0) {

   211

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

   212

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

   213

		}

   214

	}

   215

};

   216

   217

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

   218

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

   219

 *  simplifies the resource management in several ways:

   220

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

   221

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

   222

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

   223

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

   224

template <class Titem_, class Tbase_ = CBlobBaseSimple>

   225

class CBlobT : public CBlobBaseSimple {

   226

	// make template arguments public:

   227

public:

   228

	typedef Titem_ Titem;

   229

	typedef Tbase_ Tbase;

   230

   231

	static const int Titem_size = sizeof(Titem);

   232

   233

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

   234

	FORCEINLINE CBlobT() : Tbase() {}

   235

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

   236

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

   237

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

   238

	FORCEINLINE ~CBlobT() { Free(); }

   239

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

   240

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

   241

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

   242

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

   243

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

   244

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

   245

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

   246

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

   247

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

   248

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

   249

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

   250

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

   251

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

   252

	FORCEINLINE void Free()

   253

	{

   254

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

   255

		int old_size = Size();

   256

		if (old_size > 0) {

   257

			// destroy removed items;

   258

			Titem* pI_last_to_destroy = Data(0);

   259

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

   260

		}

   261

		Tbase::Free();

   262

	}

   263

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

   264

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

   265

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

   266

	FORCEINLINE Titem* GrowSizeC(int num_items)

   267

	{

   268

		Titem* pI = GrowSizeNC(num_items);

   269

		for (int i = 0; i < num_items; ++i) new (pI + i) Titem();

   270

		return pI;

   271

	}

   272

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

   273

	FORCEINLINE void ReduceSize(int num_items)

   274

	{

   275

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

   276

		int old_size = Size();

   277

		assert(num_items <= old_size);

   278

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

   279

		// destroy removed items;

   280

		Titem* pI_last_to_destroy = Data(new_size);

   281

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

   282

		// remove them

   283

		ReduceRawSize(num_items * Titem_size);

   284

	}

   285

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

   286

	FORCEINLINE Titem* AppendNew()

   287

	{

   288

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

   289

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

   290

		return pNewItem;

   291

	}

   292

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

   293

	FORCEINLINE Titem* Append(const Titem& src)

   294

	{

   295

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

   296

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

   297

		return pNewItem;

   298

	}

   299

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

   300

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

   301

	{

   302

		Titem* pDst = GrowSizeNC(num_items);

   303

		Titem* pDstOrg = pDst;

   304

		Titem* pDstEnd = pDst + num_items;

   305

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

   306

		return pDstOrg;

   307

	}

   308

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

   309

	FORCEINLINE void RemoveBySwap(int idx)

   310

	{

   311

		CheckIdx(idx);

   312

		// destroy removed item

   313

		Titem* pRemoved = Data(idx);

   314

		RemoveBySwap(pRemoved);

   315

	}

   316

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

   317

	FORCEINLINE void RemoveBySwap(Titem* pItem)

   318

	{

   319

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

   320

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

   321

		// move last item to its new place

   322

		if (pItem != pLast) {

   323

			pItem->~Titem_();

   324

			new (pItem) Titem_(*pLast);

   325

		}

   326

		// destroy the last item

   327

		pLast->~Titem_();

   328

		// and reduce the raw blob size

   329

		ReduceRawSize(Titem_size);

   330

	}

   331

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

   332

	 *  first free (unused) item */

   333

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

   334

};

   335

   336

// simple string implementation

   337

struct CStrA : public CBlobT<char>

   338

{

   339

	typedef CBlobT<char> base;

   340

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

   341

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

   342

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

   343

};

   344

   345

#endif /* BLOB_HPP */