Files CCore/inc/MemBase.h CCore/src/MemBase_general.cpp HCore/CCore/src/MemBase.cpp XCore/CCore/src/MemBase.cpp
Files CCore/inc/RadixHeap.h CCore/src/RadixHeap.cpp
Files CCore/inc/HeapEngine.h CCore/src/HeapEngine.cpp
CCore uses its own memory management subsystem. We don't rely on the standard malloc/free or new/delete, provided by the C++ compiler support libraries. In fact, in XCore targets it is recommended to build these libraries based on CCore memory allocation functions. This is because we need much more from the heap, namely:
The heart of CCore heaps is the class RadixHeap. This class implements a radix-tree based heap atop on a primary memory management facility. The heap is maintained in the one or several large blocks of memory, obtained dynamically from the OS, or fixed in the memory. RadixHeap is a real-time heap. Its operations has a time execution limit, assuming there is no primary memory management functions calls. In practice, the cost of allocation and deallocation memory functions is a 100s CPU clocks. This heap is also best-fit and provides a protection from wrong memory block address arguments. If you try to free a memory at an arbitrary address, then it's very likely the abort will be called.
CCore heap is a global object, maintained by the PlanInit and derived from the HeapEngine class, which implements the top-level logic over the RadixHeap functionality. Been a general purpose global object, CCore heap is a mutex-protected. In HCore primary large blocks of memory are obtained from the OS. In XCore it is a single fixed block of memory, provided by the target.
During uninitialization, CCore heap calls abort if not all allocated memory blocks were released.
Here is the basic memory function list from MemBase.h:
/* words */ enum JustTryType { JustTry }; /* functions */ void GuardNoMem(ulen len); /* Mem...() */ void * TryMemAlloc(ulen len) noexcept; void * MemAlloc(ulen len); ulen MemLen(const void *mem); // mem may == 0 bool MemExtend(void *mem,ulen len); // mem may == 0 bool MemShrink(void *mem,ulen len); // mem may == 0 void MemFree(void *mem); // mem may == 0 void MemLim(ulen limit);
MemAlloc() allocates a memory block of required length and returns its address. The block is always MaxAligned, the actual length can be a slightly greater than the required and always non-null. If the operation is failed, then an exception is thrown. The exception class is derived from the std::bad_alloc as required by the C++ standard, but it is also derived from the CatchType, according CCore rules.
TryMemAlloc() is similar, but in case of failure it just returns null.
MemLim() setup the global allocation limit. If the argument is zero, then there is no limit. If it is not zero, heap will keep the total allocated memory length below this limit (approximately). This feature is useful for testing purpose, it helps reproduce the situation of the memory shortage.
In the remaining four functions the argument mem must be either an address of the allocated memory block or null. Otherwise the memory heap protection abort is called (with high probability, the detection is not 100%).
MemFree() releases the allocated memory block.
MemExtend() tries to extend the allocated memory block. If successful, it returns true and the new length of the block is at least len. If the mem is null, the function does nothing and returns false. MemExtend() is always successful, if the len is not greater than the length of the memory block, in this case it does nothing. If additional space is required, then MemExtend() is looking for the space behind the block. If enough such space is free, it resizes both memory blocks. Otherwise it fails.
MemShrink() shrinks the allocated memory block. If successful, it returns true and the new length of the block is at least len. If the mem is null, the function does nothing and returns false. MemShrink() fails only if the len is greater than the length of the memory block.
MemLen() returns the actual length of the allocated memory block or 0 for the null mem.
GuardNoMem() throws an exception, it is used when no memory error happens.
JustTry is a word. It is used to distinguish between throwing and non-throwing variants of some operation.
MemStatData is a simple Small Data Type, used to represent a memory allocation statistics. It has two fields: block_count — the number of allocated blocks, and len_count — the total length of blocks. It has number of methods with obvious meaning. The method setMax() replaces the current object with the given argument, if the argument has a greater len_count. It is used to accumulate the "peak" stat value.
struct MemStatData
{
ulen block_count;
ulen len_count;
MemStatData();
// count
void add(ulen len) { block_count++; len_count+=len; }
void del(ulen len) { block_count--; len_count-=len; }
void extend(ulen delta) { len_count+=delta; }
void shrink(ulen delta) { len_count-=delta; }
// set
void set(const MemStatData &obj) { *this=obj; }
void setMax(const MemStatData &obj);
// compare
bool operator == (const MemStatData &obj) const;
bool operator != (const MemStatData &obj) const;
// print object
template <class P>
void print(P &out) const;
};
To get a heap statistic information there are two Class-functions:
/* struct MemStat */ struct MemStat : MemStatData { MemStat(); }; /* struct MemPeak */ struct MemPeak : MemStatData { MemPeak(); };
MemStat returns the current heap usage, while MemPeak — the peak usage.
MemScope is a Scope Lock Type, which controls memory release during some scope of execution. In constructor it records the current heap statistic, in destructor it retrieves it again and compares. If they doesn't match, a error message is printed using Printf(NoException,...).
class MemScope : NoCopy
{
MemStat on_init;
public:
MemScope() {}
~MemScope();
};
This class is useful for the catching memory leaks.
Another helpful Property Type class is the MemBase:
struct MemBase
{
// placement new/delete
void * operator new(std::size_t,Place<void> place) { return place; }
void operator delete(void *,Place<void>) {}
// new/delete
void * operator new(std::size_t len) { return MemAlloc(len); }
void * operator new(std::size_t len,JustTryType) noexcept { return TryMemAlloc(len); }
void operator delete(void *mem) { MemFree(mem); }
void operator delete(void *mem,JustTryType) { MemFree(mem); }
// extra space
template <class T>
static Place<void> ExtraSpace(T *obj) { return PlaceAt(obj)+Align(sizeof (T)); }
void * operator new(std::size_t len,ulen extra,ulen size_of=1) { return MemAlloc(LenOf(extra,size_of,Align(len))); }
void operator delete(void *mem,ulen,ulen) { MemFree(mem); }
};
This class redefines the new/delete operators to use the CCore heap. Specify this class as the base class to make sure the derived class object been created by the operator new will be placed in the CCore heap. It also defines a non-throwing variant of the operator new with JustTry argument.
You may also take some additional space after the object, using the overloaded operator new. extra is the number of parts of size_of length. To retrieve this space use the function ExtraSpace. An example:
template <class T>
struct Header : MemBase_nocopy
{
ulen object_count;
explicit Header(ulen object_count_) : object_count(object_count_) {}
Place<void> getSpace() { return ExtraSpace(this); }
static Header * Create(ulen object_count)
{
return new(object_count,sizeof (T)) Header(object_count);
}
};
MemBase_nocopy is a non-copyable variant of the MemBase.
Files CCore/inc/MemSpaceHeap.h CCore/src/MemSpaceHeap.cpp
SpaceHeap is a heap class for a stand-alone usage. It provides a heap functionality, the memory blocks comes from a single fixed memory buffer. The memory buffer is allocated from the main heap.
class SpaceHeap : NoCopy
{
....
public:
explicit SpaceHeap(ulen mem_len);
~SpaceHeap();
bool isEmpty() const { return heap.isEmpty(); }
void * alloc(ulen len);
ulen getLen(const void *mem); // mem!=0
void free(void *mem); // mem!=0
bool extend(void *mem,ulen len); // mem!=0
bool shrink(void *mem,ulen len); // mem!=0
};
Constructor argument is the length of the memory buffer.
alloc() returns null on failure.
The argument mem must not be null.
Destructor calls abort on memory leak.
extend() and shrink() work the same way as MemExtend() and MemShrink(), except they don't accept the null argument.
There is no a mutex protection for methods of the SpaceHeap.
MemSpace class is a primary memory provider class for the RadixHeap. It is used to build the SpaceHeap.
class MemSpace : NoCopy
{
ulen max_store_len;
RadixHeapBlock *cache;
public:
explicit MemSpace(Space space); // aligned
void cleanup(bool clean);
ulen getMaxStoreLen() const { return max_store_len; }
RadixHeapBlock * alloc(ulen blen);
void free(RadixHeapBlock *block);
bool extend(RadixHeapBlock *block,ulen blen);
ulen shrink(RadixHeapBlock *block,ulen blen);
};
space must be aligned, both the base address and the length.
Files HCore/CCore/inc/MemPageHeap.h HCore/CCore/src/MemPageHeap.cpp
PageHeap is another HCore heap class for a stand-alone usage. It provides a heap functionality, the memory blocks comes from a set of large memory buffers. These buffers are allocated using memory page functions, provided by OS.
class PageHeap : NoCopy
{
....
public:
PageHeap();
explicit PageHeap(ulen min_page_alloc_len);
~PageHeap();
bool isEmpty() const { return heap.isEmpty(); }
void * alloc(ulen len);
ulen getLen(const void *mem); // mem!=0
void free(void *mem); // mem!=0
bool extend(void *mem,ulen len); // mem!=0
bool shrink(void *mem,ulen len); // mem!=0
};
The interface of the PageHeap is identical to the SpaceHeap interface.
PageHeap has two constructors. The argument min_page_alloc_len is the minimum large buffer length. Default constructor uses some default value for it.
The amount of memory, provided by the PageHeap, is limited only by the address space and available physical memory.
MemPage class is a primary memory provider class for the RadixHeap. It is used to build the PageHeap.
class MemPage : NoCopy
{
public:
MemPage();
explicit MemPage(ulen min_alloc_len);
void cleanup(bool clean);
ulen getMaxStoreLen() const { return max_store_len; }
RadixHeapBlock * alloc(ulen blen);
void free(RadixHeapBlock *block);
bool extend(RadixHeapBlock *block,ulen blen);
ulen shrink(RadixHeapBlock *block,ulen blen);
};
The constructor argument min_alloc_len has the same meaning, as the min_page_alloc_len for the PageHeap constructor.
Files XCore/CCore/inc/SpecialMemBase.h XCore/CCore/src/SpecialMemBase.cpp
XCore provides additional memory functions. There are 2 additional memory heaps, one to be used in the interrupt context, another to distribute shared memory. The main heap is protected by a mutex, so it cannot be used in the interrupt context. The interrupt heap is protected by the IntLock. This heap is used in the C++ exception implementation, so exceptions can be used without limitation. Shared memory is a special class of memory, which is not cached by the CPU. This memory is used to exchange data with peripheral devices.
/* init/exit functions */ void Init_SpecialMem(); void Exit_SpecialMem();
Init_SpecialMem() and Exit_SpecialMem() are initialization functions, they are called by the board initialization code and must not be used anywhere else.
/* Mem..._int() functions */ void * TryMemAlloc_int(ulen len) noexcept; void MemFree_int(void *mem); /* Mem..._shared() functions */ void * TryMemAlloc_shared(ulen len) noexcept; void MemFree_shared(void *mem);
TryMemAlloc_int() and MemFree_int() are the heap functions of the interrupt heap.
TryMemAlloc_shared() and MemFree_shared() are the heap functions of the shared heap.
/* struct MemStat_int */
struct MemStat_int : MemStatData
{
MemStat_int();
};
/* struct MemPeak_int */
struct MemPeak_int : MemStatData
{
MemPeak_int();
};
MemStat_int and MemPeak_int are the statistic heap Class-functions of the interrupt heap.