All programs perform some form of memory allocation. The Essbase API allocates memory internally, some of which is returned in the form of pointers to the calling program. The calling program can also allocate memory, which is passed as pointers to the API. To avoid potential conflicts between different memory management schemes, the API provides two mechanisms for integrating the memory management in your application:
Use the API's memory management scheme in your application
Customize the API to use your application's memory management scheme internally
Using the C API's Memory Management Scheme
The API provides a set of memory management functions, EssAlloc(), EssRealloc(), and EssFree(). These functions (plus all internal API memory allocations) call memory allocation routines pointed to by the AllocFunc, ReallocFunc, and FreeFunc fields of the ESS_INIT_T initialization structure. If you pass NULLs into these fields, you use the default allocation routines supplied with the API, which use native memory application routines appropriate to the target platform.
The native memory allocation routines called by all platforms call the C standard library calls malloc(), realloc(), and free(). The C standard library calls accommodate the operation of the Outline API, which uses many small allocations of memory during normal usage. Unlike GlobalRealloc(), realloc() does not initialize new buffer areas to NULLs.
Note: | If you are using a compiler for an Intel X86-based Microsoft Windows platform, remember that the API exclusively uses the large memory model. |
Customizing the Memory Management Scheme
If you do not want to call the API's memory management functions, or you want to ensure that the same allocation scheme is used consistently throughout your application, you can define your own set of memory management functions for the API to use. To do this, you can write your own custom functions to allocate, reallocate, and free memory, and make your functions available to the API. Usually these functions internally call the corresponding memory management functions used within your application.
Defining Custom Memory Management Functions in C Programs
To define your own custom memory management functions in a program, you write the functions and set the Allocfunc, ReallocFunc, and FreeFunc fields in the API initialization structure to point to your custom function before calling EssInit(). You can use any names you wish for these functions and their arguments, but you must use the following form to declare them:
ESS_FUNC_M CustomAlloc (ESS_SIZE_T BufSize, ESS_PPVOID_T ppBuffer); ESS_FUNC_M CustomRealloc (ESS_SIZE_T BufSize, ESS_PPVOID_T ppBuffer); ESS_FUNC_M CustomFree (ESS_PVOID_T pBuffer);
In this code, the fields are defined as follows:
The BufSize argument is the minimum size of memory buffer to allocate or reallocate.
The ppBuffer argument is the address of a memory pointer to receive the allocated or reallocated buffer's address.
The pBuffer argument is the address of a memory buffer to free. These functions return zero (0) for success and non-zero for failure.
Pointers to these three functions should then be assigned to the AllocFunc, ReallocFunc, and FreeFunc fields of the initialization structure before it is passed to the EssInit() function (see Initializing the C Main API).
Note: | If you decide to define your own custom memory management functions, you must create and assign functions for all three structure fields. |
After you have defined your own custom memory management functions, you cannot use the default API memory management within that application, as any calls made to the Essbase memory management API functions, EssAlloc(), EssRealloc(), and EssFree(), from within your code will automatically invoke the equivalent custom functions you defined. However, any other applications simultaneously using the API will not be affected; each application which calls EssInit() can independently choose whether to define its own custom functions or use the default ones.
Note: You should not attempt to call any Essbase API functions from within your custom message function, with the exception of the memory management API functions, EssAlloc(), EssRealloc(), and EssFree().