High Level Memory Management API

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

At the top level are a set of macro definitions that begin with the prefix rtxMem. These are mapped to a set of similar functions that begin with the prefix rtxMemHeap. A table showing this basic mapping is as follows:

Macro Function Description
rtxMemAlloc rtxMemHeapAlloc Allocate memory
rtxMemAllocZ rtxMemHeapAllocZ Allocate and zero memory
rtxMemRealloc rtxMemHeapRealloc Reallocate memory
rtxMemFree rtxMemHeapFreeAll Free all memory in context
rtxMemFreePtr rtxMemHeapFreePtr Free a specific memory block

See the ASN1C C/C++ Common Runtime Reference Manual for further details on these functions and macros.

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 ASN1C 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, size_t nbytes) {
      return malloc (nbytes);
   }

   /* Allocate and zero memory */
   void* rtxMemHeapAllocZ (void **ppvMemHeap, size_t nbytes) {
      return calloc (nbytes, 1);
   }

   /* Free memory pointer */
   void rtxMemHeapFreePtr (void **ppvMemHeap, void *mem_p) {
      free (mem_p);
   }

   /* Reallocate memory */
   void* rtxMemHeapRealloc (void **ppvMemHeap, void *mem_p, size_t nbytes) {
      return realloc (mem_p, nbytes);
   }

   /* Free heap memory, reset all heap variables. */
   void rtxMemHeapFreeAll (void **ppvMemHeap) {
      /* There is no analog in standard memory management. */
   }

   /* Free heap memory, reset all heap variables, and free heap structure if
      it was allocated. */
   void rtxMemHeapRelease (void **ppvMemHeap) {
      /* There is no analog in standard memory management. */
   }

In most cases it is only necessary to implement the following functions:

There is no analog in standard memory management for ASN1C's rtxMemFree macro (i.e. the rtxMemHeapFreeAll function). The user is responsible for freeing all items in a generated ASN1C 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.