Defines, Structures, Typedefs, Functions. More...

Files
file	clHeapApi.h
	Header file of Heap Management related APIs.

Classes
struct	ClHeapConfigT
	ClHeapConfigT to be fetched by EO and contains the configuration of the heap library. More...

Enumerations
enum	ClHeapModeT { CL_HEAP_PREALLOCATED_MODE, CL_HEAP_NATIVE_MODE, CL_HEAP_CUSTOM_MODE }
	Heap Allocation modes. More...

Functions
ClPtrT	clHeapAllocate (CL_IN ClUint32T size)
	Allocates memory of the requested size.
ClPtrT	clHeapCalloc (CL_IN ClUint32T numChunks, CL_IN ClUint32T chunkSize)
	Allocates memory for an array and initializes it to zero.
void	clHeapFree (CL_IN ClPtrT pAddress)
	Frees a pre-allocated memory.
ClRcT	clHeapHooksDeregister (void)
	De-registers the hooks registered for CL_HEAP_CUSTOM_MODE.
ClRcT	clHeapHooksRegister (CL_IN ClPtrT(allocHook)(ClUint32T), CL_IN ClPtrT(reallocHook)(ClPtrT, ClUint32T), CL_IN ClPtrT(callocHook)(ClUint32T, ClUint32T), CL_IN void(freeHook)(ClPtrT))
	Register functions to be used in CL_HEAP_CUSTOM_MODE.
ClRcT	clHeapLibCustomFinalize (void)
	Customizes the finalization of heap library in CL_HEAP_CUSTOM_MODE.
ClRcT	clHeapLibCustomInitialize (const ClHeapConfigT *pHeapConfig)
	Customizes the initialization of heap library in CL_HEAP_CUSTOM_MODE.
ClRcT	clHeapLibFinalize (void)
	Finalizes the heap library.
ClRcT	clHeapLibInitialize (CL_IN const ClHeapConfigT *pHeapConfig)
	Initializes the heap library.
ClRcT	clHeapModeGet (CL_OUT ClHeapModeT *pMode)
	Returns the mode set during configuration.
ClRcT	clHeapPoolStatsGet (CL_IN ClUint32T numPools, CL_OUT ClUint32T pPoolSize, CL_OUT ClPoolStatsT pHeapPoolStats)
	Returns the statistics collected by heap library for an individual pool.
ClPtrT	clHeapRealloc (CL_IN ClPtrT pAddress, CL_IN ClUint32T size)
	Changes the size of the memory block (chunk).
ClRcT	clHeapShrink (CL_IN const ClPoolShrinkOptionsT *pShrinkOptions)
	Shrinks the configured pools of memory.
ClRcT	clHeapStatsGet (CL_OUT ClMemStatsT *pHeapStats)
	Returns the statistics collected by heap module.

Detailed Description

Defines, Structures, Typedefs, Functions.

Enumeration Type Documentation

enum ClHeapModeT

Heap Allocation modes.

System mode maps to malloc/free calls.

Enumerator:

CL_HEAP_PREALLOCATED_MODE

OpenClovis implementation of the memory management library.

CL_HEAP_NATIVE_MODE

Native C mode.

It maps to the memory APIs provided by libc.

CL_HEAP_CUSTOM_MODE

Custom pools.

The application developer can plug in customized memory management library calls.

Function Documentation

ClPtrT clHeapAllocate ( CL_IN ClUint32T size )

Allocates memory of the requested size.

Header File:: clHeapApi.h

Parameters

size	(in) Number of memory bytes to be allocated.

Return values:

A valid pointer on success.
NULL On memory allocation failure.

Description:: This function allocates memory of a specified size. The returned memory is aligned at an 8-byte boundary. When the heap library is configured to CL_HEAP_PREALLOCATED_MODE, it returns memory of minimum size. This memory size is greater than or equal to the requested size. If size is specified as 0, the system returns a valid pointer pointing to a chunk of minimum size that is previously configured. If heap library is configured to CL_HEAP_PREALLOCATED_MODE, failure of clHeapAllocate() for one size of memory does not mean that this function will fail for other sizes. For more information, refer to man page of malloc(3).

Library File:: libClUtils

See Also: clHeapCalloc(), clHeapFree(), clHeapRealloc(),

ClPtrT clHeapCalloc	(	CL_IN ClUint32T	numChunks,
		CL_IN ClUint32T	chunkSize
	)

Allocates memory for an array and initializes it to zero.

Header File:: clHeapApi.h

Parameters

numChunks	(in) Number of chunks to be allocated.
chunkSize	(in) Size of each chunk

Return values:

A valid pointer on success.
NULL On memory allocation failure.

Description:: This function allocates memory of a specific size. The memory chunk, it returns, is aligned at an 8-byte boundary. If CL_HEAP_PREALLOCATED_MODE is selected during heap configuration, failure of clHeapAllocate() for one size of memory does not mean that it will fail for other sizes also. For more information, refer to man page, malloc(3). Also refer to man page of calloc(3).

Library File:: libClUtils

See Also: clHeapAllocate(), clHeapFree(), clHeapRealloc()

void clHeapFree ( CL_IN ClPtrT pAddress )

Frees a pre-allocated memory.

Header File:: clHeapApi.h

Parameters

pAddress (in) Block of memory to be freed.

Return values:: None.

Description:: This function is used to free memory. pAddress should be a valid pointer allocated through a previous call to either clHeapAllocate(), clHeapRealloc(), or clHeapCalloc(). pAddress should not be used after a call to clHeapFree(). NULL is a valid value for pAddress. For more information, refer to man page of free(3).

Library File:: libClUtils

See Also: clHeapAllocate(), clHeapCalloc(), clHeapRealloc()

ClRcT clHeapHooksDeregister ( void )

De-registers the hooks registered for CL_HEAP_CUSTOM_MODE.

Header File:: clHeapApi.h

Parameters:: None

Return values

CL_OK	Function completed successfully.
CL_ERR_INITIALIZED	Heap library is not finalized through a previous call to the clHeapLibFinalize() function.
CL_ERR_NOT_INITIALIZED	Hooks were not registered through a previous call to clHeapHooksRegister() function.

Description:: This function is used to De-register the hooks registered for memory management in CL_HEAP_CUSTOM_MODE. After a call to this function, the memory related calls cannot be made until another call is made to clHeapHooksRegister(). This function should be called during the finalization of clHeapLibFinalize() through a call to open function clHeapLibCustomFinalize() present in ASP/models/<model-name>/config/clHeapCustom.c. Detailed desciption

Library File:: libClUtils

See Also: clHeapHooksRegister()

ClRcT clHeapHooksRegister	(	CL_IN ClPtrT(*)(ClUint32T)	allocHook,
		CL_IN ClPtrT(*)(ClPtrT, ClUint32T)	reallocHook,
		CL_IN ClPtrT(*)(ClUint32T, ClUint32T)	callocHook,
		CL_IN void(*)(ClPtrT)	freeHook
	)

Register functions to be used in CL_HEAP_CUSTOM_MODE.

Header File:: clHeapApi.h

Parameters

allocHook	(in) Function that allocates memory. This function is invoked when an application calls clHeapAllocate() function.
reallocHook	(in) Function that changes the size of the memory. This function is invoked when an application calls clHeapRealloc().
callocHook	(in) Function that allocates memory for an array. This function is invoked when an application calls clHeapCalloc().
freeHook	(in) Function that frees the memory. This function is invoked when an application calls clHeapFree().

Return values

CL_OK	Function completed successfully.
CL_ERR_INITIALIZED	Heap library is not initialized or it is finalized.
CL_ERR_NULL_POINTER	One of the input argument is a NULL pointer.

Description:: In CL_HEAP_CUSTOM_MODE, this function is used to register the hooks for memory management. The application should override the default implementation of clHeapLibCustomInitialize() and clHeapLibCustomFinalize() functions present in ASP/models/<model-name>/config/clHeapCustom.c. This function should be called from clHeapLibCustomInitialize(). In CL_HEAP_CUSTOM_MODE, no memory allocation should be made before registering these functions.

: During the life of a process, two different set of hooks for memory allocation should not be used. Unless due care is taken, memory allocated by one set of hooks cannot be freed using the other set of hooks as it leads to corruption of meta data structures.

Library File:: libClUtils

See Also: clHeapHooksDeregister()

ClRcT clHeapLibCustomFinalize ( void )

Customizes the finalization of heap library in CL_HEAP_CUSTOM_MODE.

Header File:: clHeapApi.h

Parameters:: None

Return values

CL_OK	Function completed successfully.
CL_ERR_NOT_INITIALIZED	Heap library is not initialized through a previous call to clHeapLibInitialize() or it is finalized using clHeapLibFinalize().

Description:: This function is used to customize the finalization of the heap library. This is an open function and the application developer should implement this function. This is called only when an application indicates that it needs to customize heap through CL_HEAP_CUSTOM_MODE. The function is available in ASP/models/<model-name>/config/clHeapCustom.c. This function must call clHeapHooksRegister() with the appropriate function pointers to override the implementation of heap provided by OpenClovis.

Library File:: libClUtils

See Also: clHeapLibFinalize(), clHeapLibCustomInitialize()

ClRcT clHeapLibCustomInitialize ( const ClHeapConfigT * pHeapConfig )

Customizes the initialization of heap library in CL_HEAP_CUSTOM_MODE.

Header File:: clHeapApi.h

Parameters

pHeapConfig (in) Pointer to configuration information used by heap library.

Return values

CL_OK	Function completed successfully.
CL_ERR_NULL_POINTER	Either pHeapConfig or pPoolConfig, a member of pHeapConfig is passed as NULL.
CL_ERR_NO_MEMORY	Heap library is out of memory and cannot proceed further.

Description:: This function is used to customize the initialization of the heap library. This is an open function and the application developer should implement this function.This is called only when an application indicates that it needs to customize heap through CL_HEAP_CUSTOM_MODE. The function is available in ASP/models/<model-name>/config/clHeapCustom.c. This function must call clHeapHooksRegister() with the appropriate function pointers to override the implementation of heap provided by OpenClovis.

Library File:: libClUtils

See Also: clHeapLibInitialize(), clHeapLibCustomFinalize()

ClRcT clHeapLibFinalize ( void )

Finalizes the heap library.

Header File:: clHeapApi.h

Parameters:: None

Return values

CL_OK	The API executed successfully
CL_ERR_NOT_INITIALIZED	heap library is not initialized through a previous call to clHeapLibInitialize() or it is finalized through a call to clHeapLibFinalize().

Description:: This function is used to finalize the heap library. After finalizing the heap library, it must not be used to allocate any memory or free previously allocated memory.

Library File:: libClUtils

See Also: clHeapLibInitialize()

ClRcT clHeapLibInitialize ( CL_IN const ClHeapConfigT * pHeapConfig )

Initializes the heap library.

Header File:: clHeapApi.h

Parameters

pHeapConfig (in) Pointer to the configuration to be used by heap library

Return values

CL_OK	The API executed successfully.
CL_ERR_NULL_POINTER	pHeapConfig or pPoolConfig (member of pHeapConfig) is NULL.
CL_ERR_INVALID_PARAMETER	numPools (member of pHeapConfig) is 0.
CL_ERR_NO_MEMORY	Heap library is out of memory and cannot proceed further.

Description:: This function is used to initialize the heap library. It is called during the initialization of the EO (Execution Object). The heap library must be initialized before it can be used to allocate memory. The caller should allocate and free the pHeapConfig parameter. Any configuration provided through this function to the heap library cannot be changed while the process calling this function is executing.

: During the lifetime of a process, this function must be called only once, preferably during process initialization. Subsequent calls to this function are ignored and it returns CL_OK without changing anything.

Library File:: libClUtils

See Also: clHeapLibFinalize()

ClRcT clHeapModeGet ( CL_OUT ClHeapModeT * pMode )

Returns the mode set during configuration.

Header File:: clHeapApi.h

Parameters

pMode (out) Configuration mode returned by the function

Return values

CL_OK	Function completed successfully.
CL_ERR_NOT_INITIALIZED	If this function is called before heap initialization through a clHeapIntialize() function.
CL_ERR_NULL_POINTER	If pMode is passed as NULL.

Description:: This function returns the configuration mode of the heap in the current process. It can be one of the following values: CL_HEAP_NATIVE_MODE, CL_HEAP_PREALLOCATED_MODE, or CL_HEAP_CUSTOM_MODE.

Library File:: libClUtils

ClRcT clHeapPoolStatsGet	(	CL_IN ClUint32T	numPools,
		CL_OUT ClUint32T *	pPoolSize,
		CL_OUT ClPoolStatsT *	pHeapPoolStats
	)

Returns the statistics collected by heap library for an individual pool.

Header File:: clHeapApi.h

Parameters

numPools	(in) Number of pools for which the statistics are required. This is used as the size for pPoolSize and pPoolStats.
pPoolSize	(out) Pointer to array which contains the sizes of various pools.
pHeapPoolStats	(out) Pointer to array which contains the statistics of various pools.

Return values

CL_OK	Function completed successfully.
CL_ERR_NOT_INITIALIZED	This function is called before initializing the heap library using the clHeapIntialize() function.
CL_ERR_NULL_POINTER	Either pPoolSize or pPoolStats or both the parameters is NULL.

Description:: This function is used by components to retrieve statistics about usage of various pools and their current size. The heap module gathers this information.

: If numPools is less than the number of pools configured in heap, the function returns the size and statistics of the first pool arranged in increasing order of chunk sizes. If numPools is greater than the number of pools configured, only first n entries of pPoolSize and pPoolStats are valid, where n is the number of pools configured.

Library File:: libClUtils

ClPtrT clHeapRealloc	(	CL_IN ClPtrT	pAddress,
		CL_IN ClUint32T	size
	)

Changes the size of the memory block (chunk).

Header File:: clHeapApi.h

Parameters

pAddress	(in) Original pointer to the memory block (chunk).
size	(in) New size of the memory block (chunk).

Returns: The function returns a valid pointer on success and returns NULL on memory allocation failure.

Description:

This function is used to change the size of the memory block pointed by pAddress to size in bytes. The new address returned is aligned at an 8-byte boundary. The contents of the returned memory block is unchanged to the minimum of the old and new sizes. The contents of the memory over the size of the previous block of memory is un initialized.

If pAddress is NULL, the call is equivalent to clHeapAllocate (size).
If size is zero, the call is equivalent to clHeapFree(pAddress) and the function returns NULL.
If pAddress is NULL and size is zero, it is still equal to clHeapAllocate (0).
If pAddress is not NULL, it must have been returned by an earlier call to clHeapAllocate()/clHeapRealloc()/clHeapCalloc().

: If clHeapRealloc() fails, the original memory block remains untouched (if is not freed or moved). If clHeapRealloc() succeeds, pAddress should no longer be used. For more information, refer to man page of realloc(3).

Library File:: libClUtils

See Also: clHeapAllocate(), clHeapFree(), clHeapCalloc()

ClRcT clHeapShrink ( CL_IN const ClPoolShrinkOptionsT * pShrinkOptions )

Shrinks the configured pools of memory.

Header File:: clHeapApi.h

Parameters

pShrinkOptions (in) shrinkFlags, a member of this structure indicates to what extent the existing pools can be shrunk.

Return values

CL_OK	Function completed successfully.
CL_ERR_NOT_INITIALIZED	The heap library is not initialized by a previous call to clHeapInitialize()

Description:: This function is used to shrink the memory used by the pools of all chunkSize so that next usages of pools can grow without violating the configured process wide upper limit of memory. These shrink options are used for all pools of heap library.

Library File:: libClUtils

ClRcT clHeapStatsGet ( CL_OUT ClMemStatsT * pHeapStats )

Returns the statistics collected by heap module.

Header File:: clHeapApi.h

Parameters

pHeapStats (out) Pointer to the memory block where heap module will copy the statistics.

Return values

CL_OK	Function completed successfully.
CL_ERR_NOT_INITIALIZED	Heap library is not initialized.
CL_ERR_NULL_POINTER	The parameter pHeapStats is passed as NULL.

Description:: This function is used by heap to collect the statistics about its usage. Other components can invoke this function to access these statistics.

Library File:: libClUtils

Files

Classes

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation