module ti.sysbios.heaps.HeapCallback

A heap that calls user supplied callback functions

C synopsis
Individual elements
DETAILS
EXAMPLES
Configuration settings
Individual elements

The HeapCallback module enables users to provide a custom heap implementation by providing callback functions that will be invoked by HeapCallback for the various heap management functions. [ more ... ]

C synopsis target-domain sourced in ti/sysbios/heaps/HeapCallback.xdc

#include <ti/sysbios/heaps/HeapCallback.h>

Functions
Void	HeapCallback_construct// Initialize a new instance object inside the provided structure(HeapCallback_Struct structP, const HeapCallback_Params params);
HeapCallback_Handle	HeapCallback_create// Allocate and initialize a new instance object and return its handle(const HeapCallback_Params params, Error_Block eb);
Void	HeapCallback_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(HeapCallback_Handle *handleP);
Void	HeapCallback_destruct// Finalize the instance object inside the provided structure(HeapCallback_Struct *structP);
UArg	HeapCallback_getContext// Get the context returned from user supplied create function(HeapCallback_Handle handle);
Void	HeapCallback_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(HeapCallback_Params *params);
Functions common to all IHeap modules
Ptr	HeapCallback_alloc// Allocates a block of memory from the heap(HeapCallback_Handle handle, SizeT size, SizeT align, Error_Block *eb);
Void	HeapCallback_free// Free a block of memory back to the heap(HeapCallback_Handle handle, Ptr block, SizeT size);
Void	HeapCallback_getStats// Retrieve the statistics from the heap(HeapCallback_Handle handle, Memory_Stats *stats);
Bool	HeapCallback_isBlocking// Returns whether the heap may block during an `alloc()` or `free()`(HeapCallback_Handle handle);
Functions common to all target instances
	HeapCallback_handle// Convert this instance structure pointer into an instance handle, HeapCallback_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, HeapCallback_Handle_label// The label associated with this instance object, HeapCallback_Handle_name// The name of this instance object, HeapCallback_Handle_upCast// unconditionally move one level up the inheritance hierarchy, HeapCallback_Object_count// The number of statically-created instance objects, HeapCallback_Object_first// The handle of the first dynamically-created instance object, or NULL, HeapCallback_Object_get// The handle of the i-th statically-created instance object (array == NULL), HeapCallback_Object_heap// The heap used to allocate dynamically-created instance objects, HeapCallback_Object_next// The handle of the next dynamically-created instance object, or NULL, HeapCallback_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
	HeapCallback_Module_getMask// Returns the diagnostics mask for this module, HeapCallback_Module_hasMask// Test whether this module has a diagnostics mask, HeapCallback_Module_heap// The heap from which this module allocates memory, HeapCallback_Module_id// Get this module's unique id, HeapCallback_Module_setMask// Set the diagnostics mask for this module, HeapCallback_Module_startupDone// Test if this module has completed startup
Typedefs
typedef Ptr	(*HeapCallback_AllocInstFxn// Instance alloc callback function signature)(UArg,SizeT,SizeT);
typedef UArg	(*HeapCallback_CreateInstFxn// Instance create callback function signature)(UArg);
typedef Void	(*HeapCallback_DeleteInstFxn// Instance delete callback function signature)(UArg);
typedef Void	(*HeapCallback_FreeInstFxn// Instance free callback function signature)(UArg,Ptr,SizeT);
typedef Void	(HeapCallback_GetStatsInstFxn// Instance getStats callback function signature)(UArg,Memory_Stats);
typedef HeapCallback_Object *	HeapCallback_Handle// Client reference to an instance object;
typedef UArg	(*HeapCallback_InitInstFxn// Instance init callback function signature)(UArg);
typedef Bool	(*HeapCallback_IsBlockingInstFxn// Instance isblocking callback function signature)(UArg);
typedef struct	HeapCallback_Object// Opaque internal representation of an instance object HeapCallback_Object;
typedef struct	HeapCallback_Params// Instance config-params structure ...
typedef struct	HeapCallback_Struct// Opaque client structure large enough to hold an instance object HeapCallback_Struct;
Constants
extern const HeapCallback_AllocInstFxn	HeapCallback_allocInstFxn// User supplied instance alloc function;
extern const HeapCallback_CreateInstFxn	HeapCallback_createInstFxn// User supplied instance create function;
extern const HeapCallback_DeleteInstFxn	HeapCallback_deleteInstFxn// User supplied instance delete function;
extern const HeapCallback_FreeInstFxn	HeapCallback_freeInstFxn// User supplied instance free function;
extern const HeapCallback_GetStatsInstFxn	HeapCallback_getStatsInstFxn// User supplied getStat function;
extern const HeapCallback_InitInstFxn	HeapCallback_initInstFxn// User supplied init function;
extern const HeapCallback_IsBlockingInstFxn	HeapCallback_isBlockingInstFxn// User supplied isBlocking function;

DETAILS

The HeapCallback module enables users to provide a custom heap implementation by providing callback functions that will be invoked by HeapCallback for the various heap management functions.

The user-supplied HeapCallback.initInstFxn is called during boot time to initialize any HeapCallback objects that were created in the .cfg file. The user-supplied HeapCallback.createInstFxn is called during runtime for any calls to HeapCallback_create(). Both of these functions return a context value (typically a pointer to an object managed by the user-supplied heap code). This context value is passed to subsequent user allocInstFxn, freeInstFxn, etc. functions.

HeapCallback_alloc(), HeapCallback_free() and HeapCallback_getStats() call the user-supplied allocInstFxn, freeInstFxn and getStatsInstFxn functions with the context value returned by initInstFxn or createInstFxn.

HeapCallback_delete() calls the user-supplied instDeleteFxn with the context returned by the createInstFxn.

EXAMPLES

Configuration example: The following XDC configuration statements creates a HeapCallback instance and plugs in the user defined functions.

  var HeapCallback = xdc.useModule('ti.sysbios.heaps.HeapCallback');

  var params = new HeapCallback.Params();
  params.arg = 1;
  HeapCallback.create(params);

  HeapCallback.initInstFxn = '&userInitFxn';
  HeapCallback.createInstFxn = '&userCreateFxn';
  HeapCallback.deleteInstFxn = '&userDeleteFxn';
  HeapCallback.allocInstFxn = '&userAllocFxn';
  HeapCallback.freeInstFxn = '&userFreeFxn';
  HeapCallback.getStatsInstFxn = '&userGetStatsFxn';
  HeapCallback.isBlockingInstFxn = '&userIsBlockingFxn';

typedef HeapCallback_AllocInstFxn