1

/* $Id$ */

     2

     3

/** @file blob.hpp Support for storing random binary data. */

     4

     5

#ifndef BLOB_HPP

     6

#define BLOB_HPP

     7

     8

#include "../core/alloc_func.hpp"

    10

    11

/** Base class for simple binary blobs.

    12

*  Item is byte.

    13

*  The word 'simple' means:

    14

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

    15

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

    16

*        module (DLL) where the blob was allocated

    17

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

    18

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

    19

*    - no thread synchronization at all

    20

*

    21

*  Internal member layout:

    22

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

    23

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

    24

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

    25

*                                                      sizeof(CHdr) + <data capacity>

    26

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

    27

*     of the alloated block.

    28

*  4. The pointter (in ptr_u) pobsize_ts behind the header (to the first data byte).

    29

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

    30

*  5. Benefits of this layout:

    31

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

    32

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

    33

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

    34

*  6. Drawbacks of this layout:

    35

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

    36

*       it is stored can lead to several confusions:

    37

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

    38

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

    39

* */

    40

class CBlobBaseSimple {

    41

public:

    42

	typedef ::ptrdiff_t bsize_t;

    43

	typedef ::byte      bitem_t;

    44

    45

protected:

    46

	/** header of the allocated memory block */

    47

	struct CHdr {

    48

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

    49

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

    50

	};

    51

    52

	/** type used as class member */

    53

	union {

    54

		bitem_t    *m_pData;    ///< ptr to the first byte of data

    55

#if defined(HAS_WCHAR)

    56

		wchar_t    *m_pwData;   ///< ptr to the first byte of data

    57

#endif /* HAS_WCHAR */

    58

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

    59

	} ptr_u;

    60

    61

public:

    62

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

    63

    64

	/** default constructor - initializes empty blob */

    65

	FORCEINLINE CBlobBaseSimple() { InitEmpty(); }

    66

	/** constructor - create blob with data */

    67

	FORCEINLINE CBlobBaseSimple(const bitem_t *p, bsize_t num_bytes)

    68

	{

    69

		InitEmpty();

    70

		AppendRaw(p, num_bytes);

    71

	}

    72

    73

	/** copy constructor */

    74

	FORCEINLINE CBlobBaseSimple(const CBlobBaseSimple& src)

    75

	{

    76

		InitEmpty();

    77

		AppendRaw(src);

    78

	}

    79

    80

	/** move constructor - take ownership of blob data */

    81

	FORCEINLINE CBlobBaseSimple(CHdr * const & pHdr_1)

    82

	{

    83

		assert(pHdr_1 != NULL);

    84

		ptr_u.m_pHdr_1 = pHdr_1;

    85

		*(CHdr**)&pHdr_1 = NULL;

    86

	}

    87

    88

	/** destructor */

    89

	FORCEINLINE ~CBlobBaseSimple()

    90

	{

    91

		Free();

    92

	}

    93

    94

protected:

    95

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

    96

	*  both m_size and m_max_size containing zero */

    97

	FORCEINLINE void InitEmpty()

    98

	{

    99

		static CHdr hdrEmpty[] = {{0, 0}, {0, 0}};

   100

		ptr_u.m_pHdr_1 = &hdrEmpty[1];

   101

	}

   102

   103

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

   104

	FORCEINLINE void Init(CHdr* hdr)

   105

	{

   106

		ptr_u.m_pHdr_1 = &hdr[1];

   107

	}

   108

   109

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

   110

	FORCEINLINE CHdr& Hdr()

   111

	{

   112

		return ptr_u.m_pHdr_1[-1];

   113

	}

   114

   115

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

   116

	FORCEINLINE const CHdr& Hdr() const

   117

	{

   118

		return ptr_u.m_pHdr_1[-1];

   119

	}

   120

   121

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

   122

	FORCEINLINE bsize_t& RawSizeRef()

   123

	{

   124

		return Hdr().m_size;

   125

	};

   126

   127

public:

   128

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

   129

	FORCEINLINE bool IsEmpty() const

   130

	{

   131

		return RawSize() == 0;

   132

	}

   133

   134

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

   135

	FORCEINLINE bsize_t RawSize() const

   136

	{

   137

		return Hdr().m_size;

   138

	};

   139

   140

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

   141

	FORCEINLINE bsize_t MaxRawSize() const

   142

	{

   143

		return Hdr().m_max_size;

   144

	};

   145

   146

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

   147

	FORCEINLINE bitem_t* RawData()

   148

	{

   149

		return ptr_u.m_pData;

   150

	}

   151

   152

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

   153

	FORCEINLINE const bitem_t* RawData() const

   154

	{

   155

		return ptr_u.m_pData;

   156

	}

   157

   158

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

   159

	//FORCEINLINE bsize_t Crc32() const

   160

	//{

   161

	//	return CCrc32::Calc(RawData(), RawSize());

   162

	//}

   163

   164

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

   165

	FORCEINLINE void Clear()

   166

	{

   167

		RawSizeRef() = 0;

   168

	}

   169

   170

	/** free the blob's memory */

   171

	FORCEINLINE void Free()

   172

	{

   173

		if (MaxRawSize() > 0) {

   174

			RawFree(&Hdr());

   175

			InitEmpty();

   176

		}

   177

	}

   178

   179

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

   180

	FORCEINLINE void CopyFrom(const CBlobBaseSimple& src)

   181

	{

   182

		Clear();

   183

		AppendRaw(src);

   184

	}

   185

   186

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

   187

	FORCEINLINE void MoveFrom(CBlobBaseSimple& src)

   188

	{

   189

		Free();

   190

		ptr_u.m_pData = src.ptr_u.m_pData;

   191

		src.InitEmpty();

   192

	}

   193

   194

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

   195

	FORCEINLINE void Swap(CBlobBaseSimple& src)

   196

	{

   197

		bitem_t *tmp = ptr_u.m_pData; ptr_u.m_pData = src.ptr_u.m_pData;

   198

		src.ptr_u.m_pData = tmp;

   199

	}

   200

   201

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

   202

	FORCEINLINE void AppendRaw(const void *p, bsize_t num_bytes)

   203

	{

   204

		assert(p != NULL);

   205

		if (num_bytes > 0) {

   206

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

   207

		} else {

   208

			assert(num_bytes >= 0);

   209

		}

   210

	}

   211

   212

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

   213

	FORCEINLINE void AppendRaw(const CBlobBaseSimple& src)

   214

	{

   215

		if (!src.IsEmpty())

   216

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

   217

	}

   218

   219

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

   220

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

   221

	FORCEINLINE bitem_t* MakeRawFreeSpace(bsize_t num_bytes)

   222

	{

   223

		assert(num_bytes >= 0);

   224

		bsize_t new_size = RawSize() + num_bytes;

   225

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

   226

		return ptr_u.m_pData + RawSize();

   227

	}

   228

   229

	/** Increase RawSize() by num_bytes.

   230

	*  @return pointer to the new data added */

   231

	FORCEINLINE bitem_t* GrowRawSize(bsize_t num_bytes)

   232

	{

   233

		bitem_t* pNewData = MakeRawFreeSpace(num_bytes);

   234

		RawSizeRef() += num_bytes;

   235

		return pNewData;

   236

	}

   237

   238

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

   239

	FORCEINLINE void ReduceRawSize(bsize_t num_bytes)

   240

	{

   241

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

   242

			assert(num_bytes <= RawSize());

   243

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

   244

			else RawSizeRef() = 0;

   245

		}

   246

	}

   247

   248

	/** reallocate blob data if needed */

   249

	void SmartAlloc(bsize_t new_size)

   250

	{

   251

		bsize_t old_max_size = MaxRawSize();

   252

		if (old_max_size >= new_size) return;

   253

		// calculate minimum block size we need to allocate

   254

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

   255

		// ask allocation policy for some reasonable block size

   256

		bsize_t alloc_size = AllocPolicy(min_alloc_size);

   257

		// allocate new block

   258

		CHdr* pNewHdr = RawAlloc(alloc_size);

   259

		// setup header

   260

		pNewHdr->m_size = RawSize();

   261

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

   262

		// copy existing data

   263

		if (RawSize() > 0)

   264

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

   265

		// replace our block with new one

   266

		CHdr* pOldHdr = &Hdr();

   267

		Init(pNewHdr);

   268

		if (old_max_size > 0)

   269

			RawFree(pOldHdr);

   270

	}

   271

   272

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

   273

	FORCEINLINE static bsize_t AllocPolicy(bsize_t min_alloc)

   274

	{

   275

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

   276

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

   277

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

   278

		}

   279

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

   280

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

   281

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

   282

		}

   283

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

   284

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

   285

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

   286

		}

   287

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

   288

		return min_alloc;

   289

	}

   290

   291

	/** all allocation should happen here */

   292

	static FORCEINLINE CHdr* RawAlloc(bsize_t num_bytes)

   293

	{

   294

		return (CHdr*)MallocT<byte>(num_bytes);

   295

	}

   296

   297

	/** all deallocations should happen here */

   298

	static FORCEINLINE void RawFree(CHdr* p)

   299

	{

   300

		free(p);

   301

	}

   302

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

   303

	FORCEINLINE void FixTail() const

   304

	{

   305

		if (MaxRawSize() > 0) {

   306

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

   307

			for (bsize_t i = 0; i < Ttail_reserve; i++) {

   308

				p[i] = 0;

   309

			}

   310

		}

   311

	}

   312

};

   313

   314

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

   315

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

   316

*  simplifies the resource management in several ways:

   317

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

   318

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

   319

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

   320

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

   321

template <class Titem_, class Tbase_ = CBlobBaseSimple>

   322

class CBlobT : public Tbase_ {

   323

	// make template arguments public:

   324

public:

   325

	typedef Titem_ Titem;

   326

	typedef Tbase_ Tbase;

   327

	typedef typename Tbase::bsize_t bsize_t;

   328

   329

	static const bsize_t Titem_size = sizeof(Titem);

   330

   331

	struct OnTransfer {

   332

		typename Tbase_::CHdr *m_pHdr_1;

   333

		OnTransfer(const OnTransfer& src) : m_pHdr_1(src.m_pHdr_1) {assert(src.m_pHdr_1 != NULL); *(typename Tbase_::CHdr**)&src.m_pHdr_1 = NULL;}

   334

		OnTransfer(CBlobT& src) : m_pHdr_1(src.ptr_u.m_pHdr_1) {src.InitEmpty();}

   335

		~OnTransfer() {assert(m_pHdr_1 == NULL);}

   336

	};

   337

   338

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

   339

	FORCEINLINE CBlobT()

   340

		: Tbase()

   341

	{}

   342

   343

	/** Constructor - makes new Blob with data */

   344

	FORCEINLINE CBlobT(const Titem_ *p, bsize_t num_items)

   345

		: Tbase((typename Tbase_::bitem_t*)p, num_items * Titem_size)

   346

	{}

   347

   348

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

   349

	FORCEINLINE CBlobT(const Tbase& src)

   350

		: Tbase(src)

   351

	{

   352

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

   353

	}

   354

   355

	/** Take ownership constructor */

   356

	FORCEINLINE CBlobT(const OnTransfer& ot)

   357

		: Tbase(ot.m_pHdr_1)

   358

	{}

   359

   360

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

   361

	FORCEINLINE ~CBlobT()

   362

	{

   363

		Free();

   364

	}

   365

   366

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

   367

	FORCEINLINE void CheckIdx(bsize_t idx) const

   368

	{

   369

		assert(idx >= 0); assert(idx < Size());

   370

	}

   371

   372

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

   373

	FORCEINLINE Titem* Data()

   374

	{

   375

		return (Titem*)Tbase::RawData();

   376

	}

   377

   378

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

   379

	FORCEINLINE const Titem* Data() const

   380

	{

   381

		return (const Titem*)Tbase::RawData();

   382

	}

   383

   384

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

   385

	FORCEINLINE Titem* Data(bsize_t idx)

   386

	{

   387

		CheckIdx(idx);

   388

		return (Data() + idx);

   389

	}

   390

   391

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

   392

	FORCEINLINE const Titem* Data(bsize_t idx) const

   393

	{

   394

		CheckIdx(idx);

   395

		return (Data() + idx);

   396

	}

   397

   398

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

   399

	FORCEINLINE bsize_t Size() const

   400

	{

   401

		return (Tbase::RawSize() / Titem_size);

   402

	}

   403

   404

	/** Return total number of items that can fit in the Blob without buffer reallocation */

   405

	FORCEINLINE bsize_t MaxSize() const

   406

	{

   407

		return (Tbase::MaxRawSize() / Titem_size);

   408

	}

   409

	/** Return number of additional items that can fit in the Blob without buffer reallocation */

   410

	FORCEINLINE bsize_t GetReserve() const

   411

	{

   412

		return ((Tbase::MaxRawSize() - Tbase::RawSize()) / Titem_size);

   413

	}

   414

   415

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

   416

	FORCEINLINE void Free()

   417

	{

   418

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

   419

		bsize_t old_size = Size();

   420

		if (old_size > 0) {

   421

			// destroy removed items;

   422

			Titem* pI_last_to_destroy = Data(0);

   423

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

   424

		}

   425

		Tbase::Free();

   426

	}

   427

   428

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

   429

	FORCEINLINE Titem* GrowSizeNC(bsize_t num_items)

   430

	{

   431

		return (Titem*)Tbase::GrowRawSize(num_items * Titem_size);

   432

	}

   433

   434

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

   435

	FORCEINLINE Titem* GrowSizeC(bsize_t num_items)

   436

	{

   437

		Titem* pI = GrowSizeNC(num_items);

   438

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

   439

	}

   440

   441

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

   442

	FORCEINLINE void ReduceSize(bsize_t num_items)

   443

	{

   444

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

   445

		bsize_t old_size = Size();

   446

		assert(num_items <= old_size);

   447

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

   448

		// destroy removed items;

   449

		Titem* pI_last_to_destroy = Data(new_size);

   450

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

   451

		// remove them

   452

		Tbase::ReduceRawSize(num_items * Titem_size);

   453

	}

   454

   455

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

   456

	FORCEINLINE Titem* AppendNew()

   457

	{

   458

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

   459

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

   460

		return pNewItem;

   461

	}

   462

   463

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

   464

	FORCEINLINE Titem* Append(const Titem& src)

   465

	{

   466

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

   467

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

   468

		return pNewItem;

   469

	}

   470

   471

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

   472

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

   473

	{

   474

		Titem* pDst = GrowSizeNC(num_items);

   475

		Titem* pDstOrg = pDst;

   476

		Titem* pDstEnd = pDst + num_items;

   477

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

   478

		return pDstOrg;

   479

	}

   480

   481

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

   482

	FORCEINLINE void RemoveBySwap(bsize_t idx)

   483

	{

   484

		CheckIdx(idx);

   485

		// destroy removed item

   486

		Titem* pRemoved = Data(idx);

   487

		RemoveBySwap(pRemoved);

   488

	}

   489

   490

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

   491

	FORCEINLINE void RemoveBySwap(Titem* pItem)

   492

	{

   493

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

   494

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

   495

		// move last item to its new place