The high-level memory management API consists of C macros and functions called in gemerated code and/or in application programs to allocate and free memory within the XBinder run-time.

The key memory management functions that a user might use are the following:

Note that these memory management functions are only used in the generation of C code, not C++ (although a user can use them in a C++ application). For C++, the built-in new and delete operators are used to ensure constructors and destructors are properly executed.

For a full description of these and other memory management functions, see the XBinder C/C++ Runtime Reference Manual.

It is possible to replace the high-level memory allocation functions with functions that implement a custom memory management scheme. This is done by implementing some (or all) of the C rtxMemHeap functions defined in the following interface (note: a default implementation is shown that replaces the XBinder memory manager with direct calls to the standard C run-time memory management functions):

   
                #include <stdlib.h>
                #include "rtxMemory.h"
                
                /* Create a memory heap */
                int rtxMemHeapCreate (void** ppvMemHeap) {
                return 0;
                }
                
                /* Allocate memory */
                void* rtxMemHeapAlloc (void** ppvMemHeap, int nbytes) {
                return malloc (nbytes);
                }
                
                /* Allocate and zero memory */
                void* rtxMemHeapAllocZ (void** ppvMemHeap, int nbytes) {
                void* ptr = malloc (nbytes);
                if (0 != ptr) memset (ptr, 0, nbytes);
                return ptr;
                }
                
                /* Free memory pointer */
                void rtxMemHeapFreePtr (void** ppvMemHeap, void* mem_p) {
                free (mem_p);
                }
                
                /* Reallocate memory */
                void* rtxMemHeapRealloc (void** ppvMemHeap, void* mem_p, int nbytes_) {
                return realloc (mem_p, nbytes_);
                }
                
                /* Clears heap memory (frees all memory, reset all heap's variables) */
                void rtxMemHeapFreeAll (void** ppvMemHeap) {
                /* should remove all allocated memory. there is no analog in standard memory
                management. */
                }
                
                /* Frees all memory and heap structure as well (if was allocated) */
                void rtxMemHeapRelease (void** ppvMemHeap) {
                /* should free all memory allocated + free memory heap object if exists */
                }

In most cases it is only necessary to implement the following functions: rtxMemHeapAlloc, rtxMemHeapAllocZ, rtxMemHeapFreePtr and rtxMemHeapRealloc. Note that there is no analog in standard memory management for XBinder's rtxMemFree macro (i.e. the rtxMemHeapFreeAll function). A user would be responsible for freeing all items in a generated XBinder structure individually if standard memory management is used.

The rtxMemHeapCreate and rtxMemHeapRelease functions are specialized functions used when a special heap is to be used for allocation (for example, a static block within an embedded system). In this case, rtxMemHeapCreate must set the ppvMemHeap argument to point at the block of memory to be used. This will then be passed in to all of the other memory management functions for their use through the OSCTXT structure. The rtxMemHeapRelease function can then be used to dispose of this memory when it is no longer needed.

To add these definitions to an application program, compile the C source file (it can have any name) and link the resulting object file (.OBJ or .O) in with the application.

Using the Built-in Compact Memory Management

In the above example, we gave an example of how the high level memory management API could be reimplemented to make direct calls to the standard C memory functions. This is one way to replace the default nibble memory allocation algorithm with standard memory allocation. Users who have the runtime source code can easily achieve the same thing by defining the _MEMCOMPACT C compile time setting. This can be done by either adding -D_MEMCOMPACT to the C compiler command-line arguments, or by uncommenting this item at the beginning of the rtxMemory.h header file:

                   /*
                    * Uncomment this definition before building the C or C++ run-time 
                    * libraries to enable compact memory management.  This will have a 
                    * smaller code footprint than the standard memory management; however, 
                    * the performance may not be as good.
                    */
                    /*#define _MEMCOMPACT*/
                

The only difference between these two approaches is that with this approach, tracking of allocated memory is done through the context. This makes it possible to provide an implementation of the rtxMemHeapFreeAll function as described above. This memory management scheme is slower than the default manager (i.e. nibble-based), but has a smaller code footprint.