module xdc.runtime.HeapMin

Growth-only based heap implementation

HeapMin is a minimal footprint heap implementation. This module is is designed for applications that only create module instances and generally only allocate memory at runtime, but never delete created instances or free memory explicitly. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/HeapMin.xdc
#include <xdc/runtime/HeapMin.h>
Functions
Void
Void
Void
Void
Functions common to all IHeap modules
Ptr 
Void 
Void 
Bool 
Functions common to all target instances
Functions common to all target modules
Typedefs
typedef HeapMin_Object *
typedef struct
typedef struct
typedef struct
Constants
extern const Assert_Id 
extern const Error_Id 
extern const Bool 
 
DETAILS
HeapMin is a minimal footprint heap implementation. This module is is designed for applications that only create module instances and generally only allocate memory at runtime, but never delete created instances or free memory explicitly.
For configuration-time HeapMin.create, the heap is aligned to Memory.getMaxDefaultTypeAlignMeta() for those targets that support static alignment. For targets that do not support static alignment, the buffer alignment is undefined.
When calling create() at runtime, the client is responsible for aligning the buffer.
 
config HeapMin_A_zeroSize  // module-wide

Assert that the size is non-zero on the create

C synopsis target-domain
extern const Assert_Id HeapMin_A_zeroSize;
 
 
config HeapMin_E_freeError  // module-wide

Error raised if free() is called

C synopsis target-domain
extern const Error_Id HeapMin_E_freeError;
 
DETAILS
This error is only raised if a free() is called and freeError is true.
 
config HeapMin_freeError  // module-wide

Flag to control whether E_freeError is enabled

C synopsis target-domain
extern const Bool HeapMin_freeError;
 
DETAILS
If true, a E_freeError error occurs when trying to free a buffer.
If false, no error occurs and the free() does nothing.
Module-Wide Built-Ins

C synopsis target-domain
Types_ModuleId HeapMin_Module_id();
// Get this module's unique id
 
Bool HeapMin_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle HeapMin_Module_heap();
// The heap from which this module allocates memory
 
Bool HeapMin_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 HeapMin_Module_getMask();
// Returns the diagnostics mask for this module
 
Void HeapMin_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types

C synopsis target-domain
typedef struct HeapMin_Object HeapMin_Object;
// Opaque internal representation of an instance object
 
typedef HeapMin_Object *HeapMin_Handle;
// Client reference to an instance object
 
typedef struct HeapMin_Struct HeapMin_Struct;
// Opaque client structure large enough to hold an instance object
 
HeapMin_Handle HeapMin_handle(HeapMin_Struct *structP);
// Convert this instance structure pointer into an instance handle
 
HeapMin_Struct *HeapMin_struct(HeapMin_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters

C synopsis target-domain
typedef struct HeapMin_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // Common per-instance configs
    Ptr buf;
    // Buffer that will be managed by the heap instance
    Memory_Size size;
    // Size (in MADUs) of the heap
} HeapMin_Params;
 
Void HeapMin_Params_init(HeapMin_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
 
config HeapMin_Params.buf  // instance

Buffer that will be managed by the heap instance

C synopsis target-domain
struct HeapMin_Params {
      ...
    Ptr buf;
 
DETAILS
When creating a heap at runtime, the user must supply the memory that the heap will manage. It is up to the caller to align the buffer as needed.
This parameter is ignored when creating heaps during configuration.
 
config HeapMin_Params.size  // instance

Size (in MADUs) of the heap

C synopsis target-domain
struct HeapMin_Params {
      ...
    Memory_Size size;
 
DETAILS
This parameter specifies the size of the heap managed by a HeapMin instance. In the static case, a buffer of length size will be created. In the dynamic case, size specifies the size of the buffer (i.e. parameter buf) that the caller provides.
This is a required parameter. It must be set by the caller. Failure to do so, will result in a build error for the static create or an A_zeroSize assert for the runtime create.
Runtime Instance Creation

C synopsis target-domain
HeapMin_Handle HeapMin_create(const HeapMin_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
 
Void HeapMin_construct(HeapMin_Struct *structP, const HeapMin_Params *params);
// 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
This heap is a growth-only heap that is intended to be used by systems that never delete objects or free memory. Objects can be created at runtime based on values determined at runtime, but objects can not be deleted.
SEE
Instance Deletion

C synopsis target-domain
Void HeapMin_delete(HeapMin_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
 
Void HeapMin_destruct(HeapMin_Struct *structP);
// Finalize the instance object inside the provided structure
 
HeapMin_alloc()  // instance

Allocate a block of memory from the heap

C synopsis target-domain
Ptr HeapMin_alloc(HeapMin_Handle handle, SizeT size, SizeT align, Error_Block *eb);
 
ARGUMENTS
handle — handle of a previously-created HeapMin 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.
RETURNS
Returns the address of the allocated memory.
CONSTRAINTS
The alignment must be a power of 2.
SEE
 
HeapMin_free()  // instance

Free a block of memory back to the heap

C synopsis target-domain
Void HeapMin_free(HeapMin_Handle handle, Ptr block, SizeT size);
 
ARGUMENTS
handle — handle of a previously-created HeapMin 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.
This is a growth only heap. Calling the HeapMin_free function will result in a E_freeError error unless freeError is set to false.
SEE
 
HeapMin_getStats()  // instance

Retrieve the statistics from the heap

C synopsis target-domain
Void HeapMin_getStats(HeapMin_Handle handle, Memory_Stats *stats);
 
ARGUMENTS
handle — handle of a previously-created HeapMin 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.
 
HeapMin_isBlocking()  // instance

Can this heap block the caller

C synopsis target-domain
Bool HeapMin_isBlocking(HeapMin_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created HeapMin instance object
RETURNS
If the heap might block, TRUE is returned. If the heap does not block, FALSE is returned.
HeapMin always returns FALSE since it never blocks on a resource.
Instance Convertors

C synopsis target-domain
IHeap_Handle HeapMin_Handle_upCast(HeapMin_Handle handle);
// unconditionally move one level up the inheritance hierarchy
 
HeapMin_Handle HeapMin_Handle_downCast(IHeap_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins

C synopsis target-domain
Int HeapMin_Object_count();
// The number of statically-created instance objects
 
HeapMin_Handle HeapMin_Object_get(HeapMin_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
 
HeapMin_Handle HeapMin_Object_first();
// The handle of the first dynamically-created instance object, or NULL
 
HeapMin_Handle HeapMin_Object_next(HeapMin_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle HeapMin_Object_heap();
// The heap used to allocate dynamically-created instance objects
 
Types_Label *HeapMin_Handle_label(HeapMin_Handle handle, Types_Label *buf);
// The label associated with this instance object
 
String HeapMin_Handle_name(HeapMin_Handle handle);
// The name of this instance object
 
Configuration settings sourced in xdc/runtime/HeapMin.xdc
var HeapMin = xdc.useModule('xdc.runtime.HeapMin');
module-wide config parameters
        msg: "HeapMin_create cannot have a zero size value"
    };
        msg: "free() invalid in growth-only HeapMin"
    };
 
per-instance config parameters
    var params = new HeapMin.Params// Instance config-params object;
        params.sectionName// Section name of the heap = String null;
        params.size// Size (in MADUs) of the heap = UArg 0;
per-instance creation
    var inst = HeapMin.create// Create an instance-object(params);
 
 
config HeapMin.A_zeroSize  // module-wide

Assert that the size is non-zero on the create

Configuration settings
HeapMin.A_zeroSize = Assert.Desc {
    msg: "HeapMin_create cannot have a zero size value"
};
 
C SYNOPSIS
 
config HeapMin.E_freeError  // module-wide

Error raised if free() is called

Configuration settings
HeapMin.E_freeError = Error.Desc {
    msg: "free() invalid in growth-only HeapMin"
};
 
DETAILS
This error is only raised if a free() is called and freeError is true.
C SYNOPSIS
 
config HeapMin.freeError  // module-wide

Flag to control whether E_freeError is enabled

Configuration settings
HeapMin.freeError = Bool true;
 
DETAILS
If true, a E_freeError error occurs when trying to free a buffer.
If false, no error occurs and the free() does nothing.
C SYNOPSIS
 
metaonly config HeapMin.common$  // module-wide

Common module configuration parameters

Configuration settings
HeapMin.common$ = Types.Common$ undefined;
 
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.
Instance Config Parameters

Configuration settings
var params = new HeapMin.Params;
// Instance config-params object
    params.align = SizeT undefined;
    // Alignment of the buffer being managed by this heap instance
    params.buf = Ptr 0;
    // Buffer that will be managed by the heap instance
    params.sectionName = String null;
    // Section name of the heap
    params.size = UArg 0;
    // Size (in MADUs) of the heap
 
config HeapMin.Params.buf  // instance

Buffer that will be managed by the heap instance

Configuration settings
var params = new HeapMin.Params;
  ...
params.buf = Ptr 0;
 
DETAILS
When creating a heap at runtime, the user must supply the memory that the heap will manage. It is up to the caller to align the buffer as needed.
This parameter is ignored when creating heaps during configuration.
C SYNOPSIS
 
config HeapMin.Params.size  // instance

Size (in MADUs) of the heap

Configuration settings
var params = new HeapMin.Params;
  ...
params.size = UArg 0;
 
DETAILS
This parameter specifies the size of the heap managed by a HeapMin instance. In the static case, a buffer of length size will be created. In the dynamic case, size specifies the size of the buffer (i.e. parameter buf) that the caller provides.
This is a required parameter. It must be set by the caller. Failure to do so, will result in a build error for the static create or an A_zeroSize assert for the runtime create.
C SYNOPSIS
 
metaonly config HeapMin.Params.align  // instance

Alignment of the buffer being managed by this heap instance

Configuration settings
var params = new HeapMin.Params;
  ...
params.align = SizeT undefined;
 
DETAILS
In the static HeapMin.create() call, the buffer allocated for the HeapMin instance will have the alignment specified by this parameter on targets that support static alignment.
In the dynamic case, the client must supply the buffer, so it is the client's responsibility to manage the buffer's alignment, and there is no 'align' parameter.
The specified align parameter must be a power of 2.
The default alignment of zero causes the buffer to get aligned using Memory.getMaxDefaultTypeAlignMeta().
 
metaonly config HeapMin.Params.sectionName  // instance

Section name of the heap

Configuration settings
var params = new HeapMin.Params;
  ...
params.sectionName = String null;
 
DETAILS
When creating heaps during configuration, this parameter specifies where the heap's buffer will be placed. This parameter is passed as the section name in the Memory.staticPlace function.
SEE
Static Instance Creation

Configuration settings
var params = new HeapMin.Params;
// Allocate instance config-params
params.config =   ...
// Assign individual configs
 
var inst = HeapMin.create(params);
// Create an instance-object
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
This heap is a growth-only heap that is intended to be used by systems that never delete objects or free memory. Objects can be created at runtime based on values determined at runtime, but objects can not be deleted.
SEE
generated on Tue, 14 Feb 2017 20:01:28 GMT