Description
This function allows a thread specific heap to be created directly from a user code call.
Prototype
Uns ClpHeapAllocTs( Uns heapSize,
Uns cacheSize,
Uns flags );
Parameters
heapSize
This parameter determines the heap size. This is the total space allocated for the heap, its cache, and its state tables.
cacheSize
This parameter determines how much of the heap is to be reserved for cache.
flags
This parameter determines the required heap characteristics and there are two switches. Firstly heap allocation behavior can be optimized for real time execution (CLP_MEM_REAL_TIME) which selects for deterministic execution, or throughput (CLP_MEM_OFF_LINE), which optimizes for aggregate execution speed; the default is to optimize for throughput. The second switch allows behavior to be optimized for speed (CLP_MEM_FAST) or size (CLP_MEM_SMALL); the default is to optimize for speed.
Return Value
If successful, the call will return a non-zero unsigned integer 'heapId' that identifies the newly created heap. The heapId is required when 'freeing' the thread specific heap (see ClpHeapFreeTs).
Notes
Thread specific storage is usually allocated by the translator (see process attributes) but this call provides a means of creating a temporary heap. If memory is a critical resource then this mechanism may be useful because it can allow available resources to be more efficiently shared.
Threads can only own one thread specific heap at a time. If process attributes dictate that a particular thread creates a heap (by specifying a non-zero heap size in the process attributes), then attempts to create a further heap dynamically using this call will fail.
The heapSize attribute needs to specify a heap that is large enough to accommodate the heap's state variables (see ClpHeapOverhead), and the user specified cacheSize, otherwise the call will fail. So if the sum of cacheSize and ClpHeapOverhead() is greater than heapSize then the function will return zero.
In practice, most application's heap usage is difficult to calculate exactly. The ClpHeapStats call provides actual usage statistics that can be used to estimate how much heap is actually required.
The start of the allocated heap will be 32 byte aligned.
For details of the memory management API see Memory Management. For a general overview of memory management see Basic Memory Management.
Example
Uns foo( void )
{
Uns i, j;
Uns heapId;
void *block[100];
// Create a thread specific heap
heapId = ClpHeapAllocTs( 0x100000, // Allocate 1Mb for this thread's heap
0x10000, // Reserve 64k (one sixteenth) of the heap for cache
CLP_MEM_REAL_TIME | CLP_MEM_FAST ); // Optimize for determinism and speed
if ( !heapId )
return FALSE; // Allocation failed
// Give the heap a workout
for ( i = 0; i < 10; i++ ){
for ( j= 0; j < 100; j++ ){
block[j] = ClpMallocTs( i + j ); // Allocate a block
populate( block[j] ); // Write to it
if ( !ClpCheckAlloc( block[j] ) ){ // Check for over-write and/or under-write
ClpDiag( "Block %d corrupted\n" );
return FALSE;
}
}
for ( j = 0; j < 100; j++ )
ClpFreeTs( block[j] );
}
// Check usage statistics
Uns heapSize; // Total heap size
Uns heapUsed; // Total heap space currently allocated
Uns maxHeapUsed; // Peak heap usage
Uns cacheSize; // Total cache size
Uns cacheUsed; // Total cache space currently allocated
Uns maxCacheUsed; // Peak cache usage
Uns cacheFaults; // Total number of cache faults
ClpHeapStats( heapId,
&heapSize,
&heapUsed,
&maxHeapUsed,
&cacheSize,
&cacheUsed,
&maxCacheUsed,
&cacheFaults );
// Display an estimate for heap size for the next run
// Use this run's max heap usage + 10% safety factor
ClpDiag( "Next time try %d\n", maxHeapUsed + maxHeapUsed/10 );
// Free the thread specific heap and return its resources to the 'main process' heap
ClpHeapFreeTs( heapId );
// Return status
return TRUE;
}