Home > Support > Documentation

Memory Allocation Macros and Functions

Memory allocation functions and macros handle memory management for the XBinder C run-time. More...

Defines

#define OSRTALLOCTYPE(pctxt, type)   (type*) rtxMemHeapAlloc (&(pctxt)->pMemHeap, sizeof(type))
 This macro allocates a single element of the given type.
#define OSRTALLOCTYPEZ(pctxt, type)   (type*) rtxMemHeapAllocZ (&(pctxt)->pMemHeap, sizeof(type))
 This macro allocates and zeros a single element of the given type.
#define OSRTREALLOCARRAY(pctxt, pseqof, type)
#define OSCRTMALLOC0(nbytes)   malloc(nbytes)
#define OSCRTFREE0(ptr)   free(ptr)
#define OSCRTMALLOC   rtxMemAlloc
#define OSCRTFREE   rtxMemFreePtr
#define OSCDECL
#define rtxMemAlloc(pctxt, nbytes)   rtxMemHeapAlloc(&(pctxt)->pMemHeap,nbytes)
#define rtxMemAllocZ(pctxt, nbytes)   rtxMemHeapAllocZ(&(pctxt)->pMemHeap,nbytes)
#define rtxMemRealloc(pctxt, mem_p, nbytes)   rtxMemHeapRealloc(&(pctxt)->pMemHeap, (void*)mem_p, nbytes)
#define rtxMemFreePtr(pctxt, mem_p)   rtxMemHeapFreePtr(&(pctxt)->pMemHeap, (void*)mem_p)
#define rtxMemFree(pctxt)   rtxMemHeapFreeAll(&(pctxt)->pMemHeap)
#define rtxMemReset(pctxt)   rtxMemHeapReset(&(pctxt)->pMemHeap)
#define rtxMemAllocType(pctxt, ctype)   (ctype*)rtxMemHeapAlloc(&(pctxt)->pMemHeap,sizeof(ctype))
 Allocate type.
#define rtxMemAllocTypeZ(pctxt, ctype)   (ctype*)rtxMemHeapAllocZ(&(pctxt)->pMemHeap,sizeof(ctype))
 Allocate type and zero memory.
#define rtxMemFreeType(pctxt, mem_p)   rtxMemHeapFreePtr(&(pctxt)->pMemHeap, (void*)mem_p)
#define rtxMemAllocArray(pctxt, n, type)   (type*)rtxMemHeapAlloc (&(pctxt)->pMemHeap, sizeof(type)*n)
 Allocate a dynamic array.
#define rtxMemAllocArrayZ(pctxt, n, type)   (type*)rtxMemHeapAllocZ (&(pctxt)->pMemHeap, sizeof(type)*n)
#define rtxMemFreeArray(pctxt, mem_p)   rtxMemHeapFreePtr(&(pctxt)->pMemHeap, (void*)mem_p)
#define rtxMemReallocArray(pctxt, mem_p, n, type)   (type*)rtxMemHeapRealloc(&(pctxt)->pMemHeap, (void*)mem_p, sizeof(type)*n)
#define rtxMemNewAutoPtr(pctxt, nbytes)   rtxMemHeapAlloc(&(pctxt)->pMemHeap, nbytes)
 This function allocates a new block of memory and creates an auto-pointer with reference count set to one.
#define rtxMemAutoPtrRef(pctxt, ptr)   rtxMemHeapAutoPtrRef(&(pctxt)->pMemHeap, ptr)
 This function increments the auto-pointer reference count.
#define rtxMemAutoPtrUnref(pctxt, ptr)   rtxMemHeapAutoPtrUnref(&(pctxt)->pMemHeap, ptr)
 This function decrements the auto-pointer reference count.
#define rtxMemAutoPtrGetRefCount(pctxt, ptr)   rtxMemHeapAutoPtrGetRefCount(&(pctxt)->pMemHeap, ptr)
 This function returns the reference count of the given pointer.

Typedefs

typedef void *OSCDECL * OSMallocFunc (size_t size)
typedef void *OSCDECL * OSReallocFunc (void *ptr, size_t size)

Functions

EXTERNRT void rtxMemSetAllocFuncs (OSMallocFunc malloc_func, OSReallocFunc realloc_func, OSFreeFunc free_func)
 This function sets the pointers to standard allocation functions.
EXTERNRT void rtxMemSetDefBlkSize (OSUINT32 blkSize)
 This function sets the minimum size and the granularity of memory blocks for newly created memory heaps.
EXTERNRT OSUINT32 rtxMemGetDefBlkSize ()
 This function returns the actual granularity of memory blocks.
EXTERNRT OSBOOL rtxMemIsZero (const void *pmem, size_t memsiz)
 This helper function determines if an arbitrarily sized block of memory is set to zero.

Detailed Description

Memory allocation functions and macros handle memory management for the XBinder C run-time.

Special algorithms are used for allocation and deallocation of memory to improve the run-time performance.

Define Documentation

#define OSRTALLOCTYPE (  pctxt,
type   )     (type*) rtxMemHeapAlloc (&(pctxt)->pMemHeap, sizeof(type))
 

This macro allocates a single element of the given type.

Parameters:
pctxt - Pointer to a context block
type - Data type of record to allocate

Definition at line 56 of file rtxMemory.h.

#define OSRTALLOCTYPEZ (  pctxt,
type   )     (type*) rtxMemHeapAllocZ (&(pctxt)->pMemHeap, sizeof(type))
 

This macro allocates and zeros a single element of the given type.

Parameters:
pctxt - Pointer to a context block
type - Data type of record to allocate

Definition at line 65 of file rtxMemory.h.

#define rtxMemAllocArray (  pctxt,
n,
type   )     (type*)rtxMemHeapAlloc (&(pctxt)->pMemHeap, sizeof(type)*n)
 

Allocate a dynamic array.

This macro allocates a dynamic array of records of the given type. The pointer to the allocated array is returned to the caller.

Parameters:
pctxt - Pointer to a context block
n - Number of records to allocate
type - Data type of an array record

Definition at line 372 of file rtxMemory.h.

#define rtxMemAllocType (  pctxt,
ctype   )     (ctype*)rtxMemHeapAlloc(&(pctxt)->pMemHeap,sizeof(ctype))
 

Allocate type.

This macro allocates memory to hold a variable of the given type.

Parameters:
pctxt - Pointer to a context block
ctype - Name of C typedef
Returns:
- Pointer to allocated memory or NULL if insufficient memory was available to fulfill the request.

Definition at line 334 of file rtxMemory.h.

#define rtxMemAllocTypeZ (  pctxt,
ctype   )     (ctype*)rtxMemHeapAllocZ(&(pctxt)->pMemHeap,sizeof(ctype))
 

Allocate type and zero memory.

This macro allocates memory to hold a variable of the given type and initializes the allocated memory to zero.

Parameters:
pctxt - Pointer to a context block
ctype - Name of C typedef
Returns:
- Pointer to allocated memory or NULL if insufficient memory was available to fulfill the request.

Definition at line 346 of file rtxMemory.h.

#define rtxMemAutoPtrGetRefCount (  pctxt,
ptr   )     rtxMemHeapAutoPtrGetRefCount(&(pctxt)->pMemHeap, ptr)
 

This function returns the reference count of the given pointer.

goes to zero, the memory is freed.

Parameters:
pctxt Pointer to a context structure.
ptr Pointer on which reference count is to be fetched.
Returns:
Pointer reference count.

Definition at line 457 of file rtxMemory.h.

#define rtxMemAutoPtrRef (  pctxt,
ptr   )     rtxMemHeapAutoPtrRef(&(pctxt)->pMemHeap, ptr)
 

This function increments the auto-pointer reference count.

Parameters:
pctxt Pointer to a context structure.
ptr Pointer on which reference count is to be incremented.
Returns:
Referenced pointer value (ptr argument) or NULL if reference count could not be incremented.

Definition at line 433 of file rtxMemory.h.

#define rtxMemAutoPtrUnref (  pctxt,
ptr   )     rtxMemHeapAutoPtrUnref(&(pctxt)->pMemHeap, ptr)
 

This function decrements the auto-pointer reference count.

If the count goes to zero, the memory is freed.

Parameters:
pctxt Pointer to a context structure.
ptr Pointer on which reference count is to be decremented.
Returns:
Positive reference count or a negative error code. If zero, memory held by pointer will have been freed.

Definition at line 446 of file rtxMemory.h.

#define rtxMemNewAutoPtr (  pctxt,
nbytes   )     rtxMemHeapAlloc(&(pctxt)->pMemHeap, nbytes)
 

This function allocates a new block of memory and creates an auto-pointer with reference count set to one.

The rtxMemAutoPtrRef and rtxMemAutoPtrUnref functions can be used to increment and decrement the reference count. When the count goes to zero, the memory held by the pointer is freed.

Parameters:
pctxt Pointer to a context structure.
nbytes Number of bytes to allocate.
Returns:
Pointer to allocated memory or NULL if not enough memory is available.

Definition at line 422 of file rtxMemory.h.

Function Documentation

EXTERNRT OSUINT32 rtxMemGetDefBlkSize (   ) 
 

This function returns the actual granularity of memory blocks.

Returns:
The currently used minimum size and the granularity of memory blocks.

EXTERNRT OSBOOL rtxMemIsZero (  const void *  pmem,
size_t  memsiz
) 
 

This helper function determines if an arbitrarily sized block of memory is set to zero.

Parameters:
pmem Pointer to memory block to check
memsiz Size of the memory block
Returns:
Boolean result: true if memory is all zero

EXTERNRT void rtxMemSetAllocFuncs (  OSMallocFunc  malloc_func,
OSReallocFunc  realloc_func,
OSFreeFunc  free_func
) 
 

This function sets the pointers to standard allocation functions.

These functions are used to allocate/reallocate/free memory blocks. By default, standard C functions - 'malloc', 'realloc' and 'free' - are used. But if some platforms do not support these functions (or some other reasons exist) they can be overloaded. The functions being overloaded should have the same prototypes as the standard functions.

Parameters:
malloc_func Pointer to the memory allocation function ('malloc' by default).
realloc_func Pointer to the memory reallocation function ('realloc' by default).
free_func Pointer to the memory deallocation function ('free' by default).

EXTERNRT void rtxMemSetDefBlkSize (  OSUINT32  blkSize  ) 
 

This function sets the minimum size and the granularity of memory blocks for newly created memory heaps.

Parameters:
blkSize The minimum size and the granularity of memory blocks.