module ti.sysbios.heaps.HeapMultiBuf

Multiple fixed size buffer heap manager

C synopsis
Individual elements
Configuration settings
Individual elements

The HeapMultiBuf manager provides functions to allocate and free storage from a heap of type HeapMultiBuf which inherits from IHeap. HeapMultiBuf manages multiple fixed-size memory buffers. Each buffer contains a fixed number of allocable memory 'blocks' of the same size. Simply put, a HeapMultiBuf instance manages a collection of HeapBuf instances. HeapMultiBuf is intended as a fast and deterministic memory manager which can service requests for blocks of arbitrary size. [ more ... ]

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

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

Functions
Void	HeapMultiBuf_construct// Initialize a new instance object inside the provided structure(HeapMultiBuf_Struct structP, const HeapMultiBuf_Params params, Error_Block *eb);
HeapMultiBuf_Handle	HeapMultiBuf_create// Allocate and initialize a new instance object and return its handle(const HeapMultiBuf_Params params, Error_Block eb);
Void	HeapMultiBuf_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(HeapMultiBuf_Handle *handleP);
Void	HeapMultiBuf_destruct// Finalize the instance object inside the provided structure(HeapMultiBuf_Struct *structP);
Void	HeapMultiBuf_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(HeapMultiBuf_Params *params);
Functions common to all IHeap modules
Ptr	HeapMultiBuf_alloc// Allocates a block of memory from the heap(HeapMultiBuf_Handle handle, SizeT size, SizeT align, Error_Block *eb);
Void	HeapMultiBuf_free// Free a block of memory back to the heap(HeapMultiBuf_Handle handle, Ptr block, SizeT size);
Void	HeapMultiBuf_getStats// Retrieve the statistics from the heap(HeapMultiBuf_Handle handle, Memory_Stats *stats);
Bool	HeapMultiBuf_isBlocking// Returns whether the heap may block during an `alloc()` or `free()`(HeapMultiBuf_Handle handle);
Functions common to all target instances
	HeapMultiBuf_handle// Convert this instance structure pointer into an instance handle, HeapMultiBuf_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, HeapMultiBuf_Handle_label// The label associated with this instance object, HeapMultiBuf_Handle_name// The name of this instance object, HeapMultiBuf_Handle_upCast// unconditionally move one level up the inheritance hierarchy, HeapMultiBuf_Object_count// The number of statically-created instance objects, HeapMultiBuf_Object_first// The handle of the first dynamically-created instance object, or NULL, HeapMultiBuf_Object_get// The handle of the i-th statically-created instance object (array == NULL), HeapMultiBuf_Object_heap// The heap used to allocate dynamically-created instance objects, HeapMultiBuf_Object_next// The handle of the next dynamically-created instance object, or NULL, HeapMultiBuf_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
	HeapMultiBuf_Module_getMask// Returns the diagnostics mask for this module, HeapMultiBuf_Module_hasMask// Test whether this module has a diagnostics mask, HeapMultiBuf_Module_heap// The heap from which this module allocates memory, HeapMultiBuf_Module_id// Get this module's unique id, HeapMultiBuf_Module_setMask// Set the diagnostics mask for this module, HeapMultiBuf_Module_startupDone// Test if this module has completed startup
Typedefs
typedef HeapMultiBuf_Object *	HeapMultiBuf_Handle// Client reference to an instance object;
typedef struct	HeapMultiBuf_Object// Opaque internal representation of an instance object HeapMultiBuf_Object;
typedef struct	HeapMultiBuf_Params// Instance config-params structure ...
typedef struct	HeapMultiBuf_Struct// Opaque client structure large enough to hold an instance object HeapMultiBuf_Struct;
Constants
extern const Assert_Id	HeapMultiBuf_A_blockNotFreed// Invalid block pointer;
extern const Error_Id	HeapMultiBuf_E_size// Raised when requested size exceeds all blockSizes;

DETAILS

An example HeapMultiBuf instance might have sixteen 32-byte blocks in one buffer, and four 128-byte blocks in another buffer. A request for memory will be serviced by the smallest possible block, so a request for 100 bytes would receive a 128-byte block in our example.

Allocating from HeapMultiBuf will try to return a block from the first buffer which has:

1. A block size that is >= to the requested size

AND

2. An alignment that is >= to the requested alignment

If the first matching buffer is empty, HeapMultiBuf will only continue searching for a block if 'block borrowing' is enabled (see Block Borrowing).

HeapMultiBuf and HeapBuf

The HeapMultiBuf module is built on top of the HeapBuf module. Each buffer in a HeapMultiBuf is in fact managed by a HeapBuf instance. Configuration of a HeapMultiBuf is done by providing an array of configured HeapBuf parameter structures. Refer to the HeapBuf documentation for information on the buffer parameters. All of the documentation and parameters for HeapBuf apply equally to HeapMultiBuf. Another consequence of this is that configuration checking is left to the HeapBuf module. If a buffer in a HeapMultiBuf has been incorrectly configured (with blockSize = 0, for example), HeapBuf, not HeapMultiBuf, will raise an Assert. Since HeapMultiBuf is built on HeapBuf, it simply performs the logic to determine which HeapBuf to allocate a block from or which HeapBuf to free a block to.

Configuration Example

The following configuration code creates a HeapMultiBuf instance which manages 3 pools of 10 blocks each, with block sizes of 64, 128 and 256.

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

  // Create parameter structure for HeapMultiBuf instance.
  var hmbParams = new HeapMultiBuf.Params();
  hmbParams.numBufs = 3;

  // Create the parameter structures for each of the three
  // HeapBufs to be managed by the HeapMultiBuf instance.
  hmbParams.bufParams.$add(new HeapBuf.Params());
  hmbParams.bufParams[0].blockSize = 64;
  hmbParams.bufParams[0].numBlocks = 10;

  hmbParams.bufParams.$add(new HeapBuf.Params());
  hmbParams.bufParams[1].blockSize = 128;
  hmbParams.bufParams[1].numBlocks = 10;

  hmbParams.bufParams.$add(new HeapBuf.Params());
  hmbParams.bufParams[2].blockSize = 256;
  hmbParams.bufParams[2].numBlocks = 10;


  // Create the HeapMultiBuf instance, and assign the global handle
  // 'multiBufHeap' to it. Add '#include <xdc/cfg/global.h>' to your
  // .c file to reference the instance by this handle.
  Program.global.multiBufHeap = HeapMultiBuf.create(hmbParams);

Block Borrowing

HeapMultiBuf can support "block borrowing". With this feature turned on, if a request is made for a 32-byte block and none are available, HeapMultiBuf will continue looking for an available block in other buffers. When a borrowed block is freed, it will be returned back to its original buffer. Enabling Block Borrowing changes the determinism of alloc, since it may have to check any number of buffers to find an available block. Block borrowing may also occur, even if it is disabled, if a block of a particular size is requested with an alignment that is greater than the configured alignment for that block size. For example, a HeapMultiBuf is configured with a buffer of 32-byte blocks with an alignment of 8, and a buffer of 64-byte blocks with an alignment of 16. If a request is made for a 32-byte block with an alignment of 16, it will be serviced by the buffer of 64-byte blocks.

Static vs. Dynamic Creation

As with HeapBuf, a statically created HeapMultiBuf instance will ignore the bufSize and buf parameters. Dynamic creates require all of the parameters. It should be noted that static creates are ideal if code space is a concern; dynamically creating a HeapMultiBuf requires a relatively large amount of initialization code to be pulled in to the executable.

Block Sizes and Alignment

A buffer with a requested alignment of 0 will receive the target- specific minimum alignment.
The actual block sizes will be a multiple of the alignment. For example, if a buffer is configured to have 56-byte blocks with an alignment of 32, HeapMultiBuf will actually create 64-byte blocks. When providing the buffer for a dynamic create, make sure it is large enough to take this into account.
Multiple buffers with the same block size ARE allowed. This may occur, for example, if sizeof is used to specify the block sizes.
If any buffers have both the same block size and alignment, they will be merged. If this is a problem, consider managing these buffers directly with HeapBuf objects.

Real-Time Concerns

Allocation from and freeing to a HeapMultiBuf instance is non-blocking. HeapMultiBuf is deterministic:

A call to alloc will always take the same amount of time for a given block size (with block borrowing disabled).
The worst case call to free is constant and proportional to the number of buffers managed.

Restrictions

Align parameters must be a power of 2.
The buffers passed to dynamically create a HeapMultiBuf must be aligned according to the alignment parameter, and must be large enough to account for the actual block size after it has been rounded up to a multiple of the alignment.
Buffers must be provided to dynamically create a HeapMultiBuf, and cannot be provided to statically create a HeapMultiBuf.

Unconstrained Functions

All functions

Calling Context

Function	Hwi	Swi	Task	Main	Startup
Params_init	Y	Y	Y	Y	Y
alloc	Y	Y	Y	Y	N
construct	N*	N*	Y	Y	N
create	N*	N*	Y	Y	N
delete	N*	N*	Y	Y	N
destruct	N*	N*	Y	Y	N
free	Y	Y	Y	Y	N
getStats	Y	Y	Y	Y	N
isBlocking	Y	Y	Y	Y	N
Definitions: Hwi: API is callable from a Hwi thread. Swi: API is callable from a Swi thread. Task: API is callable from a Task thread. Main: API is callable during any of these phases: In your module startup after this module is started (e.g. HeapMultiBuf_Module_startupDone() returns TRUE). During xdc.runtime.Startup.lastFxns. During main(). During BIOS.startupFxns. Startup: API is callable during any of these phases: During xdc.runtime.Startup.firstFxns. In your module startup before this module is started (e.g. HeapMultiBuf_Module_startupDone() returns FALSE). : Assuming blocking Heap is used for creation. *: Assuming GateMutex is used as HeapMem's Gate. + : Cannot use HeapMem object while it is being restored.

config HeapMultiBuf_A_blockNotFreed // module-wide