The HeapBuf manager provides functions to allocate and free storage from a
heap of type HeapBuf which inherits from IHeap. HeapBuf manages a single
fixed-size buffer, split into equally sized allocable blocks.
The HeapBuf manager is intended as a very fast and deterministic memory
manager which can only allocate blocks of a single size. It is ideal for
managing a heap that is only used for allocating a single type of object,
or for objects that have very similar sizes.
Allocation from and freeing to a HeapBuf instance is non-blocking and
deterministic: a call to alloc or free will always take the same amount of
time.
metaonly struct HeapBuf.BasicView |
|
XDCscript usage |
meta-domain |
var obj = new HeapBuf.BasicView;
obj.label = String ...
obj.bufSize = UArg ...
obj.align = SizeT ...
obj.blockSize = SizeT ...
obj.numBlocks = UInt ...
obj.totalFreeSize = Int ...
obj.numberAllocatedBlocks = UInt ...
obj.numFreeBlocks = UInt ...
obj.maxAllocatedBlocks = UInt ...
obj.buf = Ptr ...
obj.statStr = String ...
metaonly struct HeapBuf.DetailedView |
|
XDCscript usage |
meta-domain |
var obj = new HeapBuf.DetailedView;
obj.label = String ...
obj.bufSize = UArg ...
obj.align = SizeT ...
obj.blockSize = SizeT ...
obj.numBlocks = UInt ...
obj.totalFreeSize = Int ...
obj.numberAllocatedBlocks = UInt ...
obj.numFreeBlocks = UInt ...
obj.maxAllocatedBlocks = UInt ...
obj.buf = Ptr ...
obj.freeList = Ptr ...
obj.statStr = String ...
struct HeapBuf.ExtendedStats |
|
Stats structure for the getExtendedStats API
XDCscript usage |
meta-domain |
var obj = new HeapBuf.ExtendedStats;
obj.maxAllocatedBlocks = UInt ...
obj.numAllocatedBlocks = UInt ...
typedef struct HeapBuf_ExtendedStats {
UInt maxAllocatedBlocks;
UInt numAllocatedBlocks;
} HeapBuf_ExtendedStats;
FIELDS
maxAllocatedBlocks
The maximum number of blocks allocated from
this heap at any single point in time, during
the lifetime of this HeapBuf instance.
numAllocatedBlocks
The total number of blocks currently
allocated in this HeapBuf instance.
config HeapBuf.A_bufAlign // module-wide |
|
Assert raised when the buf parameter has not been aligned on the
requested alignment
XDCscript usage |
meta-domain |
msg: "buf not properly aligned"
};
config HeapBuf.A_invalidAlign // module-wide |
|
Assert raised when the align parameter is not the default value of zero,
or a power of 2 that is greater than or equal to the value defined by
xdc.runtime.Memory.getMaxDefaultTypeAlign
XDCscript usage |
meta-domain |
msg: "align parameter must be 0 or a power of 2 >= the value of Memory_getMaxDefaultTypeAlign()"
};
extern const Assert_Id HeapBuf_A_invalidAlign;
config HeapBuf.A_invalidBufSize // module-wide |
|
Assert raised when the bufSize parameter is too small
to handle requested blocks
XDCscript usage |
meta-domain |
msg: "HeapBuf_create's bufSize parameter is invalid (too small)"
};
extern const Assert_Id HeapBuf_A_invalidBufSize;
config HeapBuf.A_noBlocksToFree // module-wide |
|
Assert raised when free is called and there are no blocks allocated
XDCscript usage |
meta-domain |
msg: "Cannot call HeapBuf_free when no blocks have been allocated"
};
extern const Assert_Id HeapBuf_A_noBlocksToFree;
config HeapBuf.A_nullBuf // module-wide |
|
Assert raised when the buf parameter has been omitted (null) for a
dynamic create
XDCscript usage |
meta-domain |
msg: "buf parameter cannot be null"
};
config HeapBuf.A_zeroBlockSize // module-wide |
|
Assert raised when the blockSize parameter is 0
XDCscript usage |
meta-domain |
msg: "blockSize cannot be zero"
};
extern const Assert_Id HeapBuf_A_zeroBlockSize;
config HeapBuf.A_zeroBlocks // module-wide |
|
Assert raised when the numBlocks parameter is 0
XDCscript usage |
meta-domain |
msg: "numBlocks cannot be zero"
};
config HeapBuf.A_zeroBufSize // module-wide |
|
Assert raised when the bufSize parameter is 0
XDCscript usage |
meta-domain |
msg: "bufSize cannot be zero"
};
extern const Assert_Id HeapBuf_A_zeroBufSize;
config HeapBuf.trackMaxAllocs // module-wide |
|
This will enable/disable the tracking of the maximum number of
allocations for a HeapBuf instance. This maximum refers to the "all
time" maximum number of allocations for the history of a HeapBuf
instance, not the current number of allocations
XDCscript usage |
meta-domain |
HeapBuf.trackMaxAllocs = Bool false;
extern const Bool HeapBuf_trackMaxAllocs;
metaonly config HeapBuf.common$ // module-wide |
|
Common module configuration parameters
XDCscript usage |
meta-domain |
DETAILS
All modules have this configuration parameter. Its name
contains the '$' character to ensure it does not conflict with
configuration parameters declared by the module. This allows
new configuration parameters to be added in the future without
any chance of breaking existing modules.
module-wide built-ins |
|
// Get this module's unique id
Bool HeapBuf_Module_startupDone( );
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool HeapBuf_Module_hasMask( );
// Test whether this module has a diagnostics mask
Bits16 HeapBuf_Module_getMask( );
// Returns the diagnostics mask for this module
Void HeapBuf_Module_setMask( Bits16 mask );
// Set the diagnostics mask for this module
per-instance object types |
|
typedef struct HeapBuf_Object HeapBuf_Object;
// Opaque internal representation of an instance object
// Client reference to an instance object
typedef struct HeapBuf_Struct HeapBuf_Struct;
// Opaque client structure large enough to hold an instance object
// Convert this instance structure pointer into an instance handle
// Convert this instance handle into an instance structure pointer
per-instance config parameters |
|
XDCscript usage |
meta-domain |
var params = new HeapBuf.Params;
// Instance config-params object
params.align = SizeT 0;
// Alignment (in MAUs) of each block
params.blockSize = SizeT 0;
// Size (in MAUs) of each block
params.buf = Ptr 0;
// User supplied buffer; for dynamic creates only
params.bufSize = UArg 0;
// Size (in MAUs) of the entire buffer; for dynamic creates only
params.numBlocks = UInt 0;
// Number of fixed-size blocks
params.sectionName = String null;
// Section name for the buffer managed by the instance
typedef struct HeapBuf_Params {
// Instance config-params structure
// Common per-instance configs
SizeT align;
// Alignment (in MAUs) of each block
SizeT blockSize;
// Size (in MAUs) of each block
Ptr buf;
// User supplied buffer; for dynamic creates only
// Size (in MAUs) of the entire buffer; for dynamic creates only
UInt numBlocks;
// Number of fixed-size blocks
} HeapBuf_Params;
// Initialize this config-params structure with supplier-specified defaults before instance creation
config HeapBuf.align // per-instance |
|
Alignment (in MAUs) of each block
XDCscript usage |
meta-domain |
var params = new HeapBuf.Params;
...
params.align = SizeT 0;
DETAILS
The alignment must be a power of 2 that is greater than or equal to
the target dependent value defined by
xdc.runtime.Memory.getMaxDefaultTypeAlign. If the default value
of 0 is specified, this value will be changed to be the minimum
structure alignment requirement, as defined by
xdc.runtime.Memory.getMaxDefaultTypeAlign.
For static creates, the HeapBuf module will allocate space for the
buffer and will align it on this requested alignment.
For dynamic creates, this parameter is used solely for error checking.
The buffer provided to a dynamically created HeapBuf must be aligned
manually, and an assert will be raised if the buffer is not properly
aligned. For dynamic creates, HeapBuf will NOT adjust the buffer to
satisfy the alignment.
config HeapBuf.blockSize // per-instance |
|
Size (in MAUs) of each block
XDCscript usage |
meta-domain |
var params = new HeapBuf.Params;
...
params.blockSize = SizeT 0;
DETAILS
HeapBuf will round the blockSize up to the nearest multiple of the
alignment, so the actual blockSize may be larger. When creating a
HeapBuf dynamically, this needs to be taken into account to determine
the proper buffer size to pass in.
Required parameter.
The default size of the blocks is 0 MAUs.
config HeapBuf.buf // per-instance |
|
User supplied buffer; for dynamic creates only
XDCscript usage |
meta-domain |
var params = new HeapBuf.Params;
...
params.buf = Ptr 0;
DETAILS
The caller must supply the memory buffer for a dynamically created
HeapBuf to manage. The provided buffer must be aligned according to the
HeapBuf's alignment parameter. i.e., if a buffer's alignment parameter
is 128, then the buffer's start address must be a multiple of 128.
For static creates, the buffer is allocated automatically based on the
blockSize and numBlocks parameters.
This parameter is required for dynamic creates and ignored for static
creates.
config HeapBuf.bufSize // per-instance |
|
Size (in MAUs) of the entire buffer; for dynamic creates only
XDCscript usage |
meta-domain |
var params = new HeapBuf.Params;
...
params.bufSize = UArg 0;
DETAILS
When dynamically creating a HeapBuf, this should be the actual size
of the memory buffer provided for HeapBuf to manage.
This parameter is used soley for error checking; an Error is raised
if the bufSize is too small for the requested blockSize and numBlocks.
Because of minimum alignment considerations, it's easy to provide too
small of a buffer to manage, and difficult to detect if it happened.
This parameter is required for dynamic creates and ignored for static
creates.
The default buffer size is 0 MAUs.
config HeapBuf.numBlocks // per-instance |
|
Number of fixed-size blocks
XDCscript usage |
meta-domain |
var params = new HeapBuf.Params;
...
params.numBlocks = UInt 0;
DETAILS
Required parameter.
The default number of blocks is 0.
metaonly config HeapBuf.sectionName // per-instance |
|
Section name for the buffer managed by the instance
XDCscript usage |
meta-domain |
var params = new HeapBuf.Params;
...
params.sectionName = String null;
DETAILS
The buffer allocated for a statically created HeapBuf instance will be
placed in this section.
The default section is the 'dataSection' in the platform.
per-instance creation |
|
XDCscript usage |
meta-domain |
var params =
new HeapBuf.
Params;
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = HeapBuf.create( params );
// Create an instance-object
// Allocate and initialize a new instance object and return its handle
// Initialize a new instance object inside the provided structure
ARGUMENTS
params
per-instance config params, or NULL to select default values (target-domain only)
eb
active error-handling block, or NULL to select default policy (target-domain only)
DETAILS
See specific IHeap implementation for parameters used.
per-instance deletion |
|
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
// Finalize the instance object inside the provided structure
HeapBuf.alloc( ) // per-instance |
|
Allocates a block of memory from the heap
ARGUMENTS
handle
handle of a previously-created HeapBuf instance object
size
size (in MADUs) of the block
align
alignment (in MADUs) of the block
eb
pointer to error block
DETAILS
This method returns a block of memory from the heap.
It is called by the
xdc.runtime.Memory.alloc() function.
HeapBuf_alloc will only fail if there are no available blocks or if the
requested block size is larger than the HeapBuf's blockSize. All other
requests, regardless of size, will succeed.
HEAPBUF
All alignment is handled in the create, therefore the
align argument in alloc is ignored.
RETURNS
Returns the address of the allocated memory.
HeapBuf.free( ) // per-instance |
|
Free a block of memory back to the heap
ARGUMENTS
handle
handle of a previously-created HeapBuf instance object
block
non-NULL address of allocated block to free
size
size (in MADUs) of the block of memory to free
DETAILS
This method gives back a block of memory to a heap.
It is called by the
xdc.runtime.Memory.free() function.
HeapBuf.getExtendedStats( ) // per-instance |
|
ARGUMENTS
handle
handle of a previously-created HeapBuf instance object
stats
Location for the returned extended statistics.
DETAILS
This function retrieves the extended statistics for a HeapBuf instance.
It does not retrieve the standard xdc.runtime.Memory.Stats information.
HEAPBUF
Retrieves the extended statistics for a HeapBuf instance.
HeapBuf.getStats( ) // per-instance |
|
Retrieve the statistics from the heap
ARGUMENTS
handle
handle of a previously-created HeapBuf instance object
stats
non-NULL pointer to an output buffer
DETAILS
The caller passes in a pointer to a
xdc.runtime.Memory.Stats
structure and
getStats fills in this structure.
This function is called by the
xdc.runtime.Memory.getStats()
function.
HeapBuf.isBlocking( ) // per-instance |
|
Returns whether the heap may block during an alloc() or
free()
ARGUMENTS
handle
handle of a previously-created HeapBuf instance object
HEAPBUF
This function always returns FALSE since the alloc/free
never block on a resource.
RETURNS
If the heap might block, TRUE is returned.
If the heap does not block, FALSE is returned.
per-instance convertors |
|
// unconditionally move one level up the inheritance hierarchy
// conditionally move one level down the inheritance hierarchy; NULL upon failure
per-instance built-ins |
|
Int HeapBuf_Object_count( );
// The number of statically-created instance objects
// The handle of the i-th statically-created instance object (array == NULL)
// The handle of the first dynamically-created instance object, or NULL
// The handle of the next dynamically-created instance object, or NULL
// The heap used to allocate dynamically-created instance objects
// The label associated with this instance object
// The name of this instance object