Memory Manager Library

This library provides routines for manipulating dynamic memory allocation. Dynamic memory allocation (also known as heap-based memory allocation) is the allocation of memory storage for use in a program during the runtime of that program.
Dynamically allocated memory exists until it is released. This is in contrast to static memory allocation, which has a fixed duration. It is said that an object so allocated has a dynamic lifetime.

The heap memory size can be configured in the Edit Project window. Also, user can override heap memory size in the code, by setting the HEAP_SIZE constant.

MM_Init

Prototype	sub procedure MM_Init()
Description	Initializes the memory manager.
Parameters	None.
Returns	Nothing.
Requires	Nothing.
Example	MM_Init() ' Initializes memory manager
Notes	None.

GetMem

Prototype	sub procedure GetMem(dim byref P as ^byte, dim Size as longword)
Description	Allocates a block of memory from the memory Heap.
Parameters	`P:` pointer to the allocated memory block. `Size:` Size of the memory block to be allocated.
Returns	Returns a pointer to the fetched memory (of "Size" bytes) in P, if success; Otherwise 0 (no free blocks of memory are large enough).
Requires	Nothing.
Example	GetMem(ptr,20sizeof(PBuffer)) ' ptr will point to a memory block where PBuffer is allocated*
Notes	Following alignments are assumed : for size in bytes >= 4, alignment is set to 4. for size in bytes = 2, alignment is set to 2. else, alignment is set to 1. It is recommended to use New routine instead.

GetMemAlign

Prototype	sub procedure GetMemAlign(dim byref P as ^byte, dim Size as longword, dim alignment as byte)
Description	Allocates a block of memory from the memory Heap.
Parameters	`P:` pointer to the allocated memory block. `Size:` Size of the memory block to be allocated. `alignment:` desired address alignment
Returns	Returns a pointer to the fetched memory (of "Size" bytes) in P if success; Otherwise 0 (no free blocks of memory are large enough).
Requires	Nothing.
Example	GetMemAlign(ptr,20sizeof(PBuffer)); ' ptr will point to a memory block where PBuffer is allocated*
Notes	User must take care when specifing alignment parameter, as the compiler assumes that certain data types must be properly aligned. Having that in mind, it is advisable to use GetMem and New routines instead.

Malloc

Prototype	sub function Malloc(dim Size as longword) as ^byte
Description	Allocates a block of memory from the memory Heap, returning a pointer to the beginning of the block. The content of the newly allocated block of memory is not initialized, remaining with indeterminate values.
Parameters	`Size:` Size of the memory block to be allocated.
Returns	Returns a pointer to the memory block allocated by the function. If the function failed to allocate the requested block of memory, a zero is returned
Requires	Nothing.
Example	dim p as ^longword ' pointer to longword dim a as longword[100] ' array of longwords p = longword(Malloc(sizeof(a))) ' p will point to a memory block where the array is allocated
Notes	None.

FreeMem

Prototype	sub procedure FreeMem(dim byref P as ^byte, dim Size as longword)
Description	This function is used to free memory block allocated by GetMem or Malloc.
Parameters	`P:` variable of any pointer type previously assigned by the Getmem procedure. `Size:` specifies the size in bytes of the dynamic variable to dispose of and should be the same as the one used to Getmem.
Returns	Nothing.
Requires	Nothing.
Example	FreeMem(ptr,20sizeof(PBuffer)) ' ptr will point to a memory block where PBuffer is allocated*
Notes	None.

Free

Prototype	sub procedure Free(dim byref P as ^byte, dim Size as longword)
Description	This function is used to free memory block allocated by GetMem or Malloc.
Parameters	`P:` pointer to the memory block `Size:` actual size of the memory block.
Returns	Nothing.
Requires	Nothing.
Example	dim p as ^longword ' pointer to longword dim a as longword[100] ' array of longwords p = longword(Malloc(sizeof(a))) ' p will point to a memory block where the array is allocated Free(p, sizeof(p)) ' frees memory block from the Heap allocated by Malloc, pointed to by the p pointer
Notes	None.

MM_LargestFreeMemBlock

Prototype	sub function MM_LargestFreeMemBlock() as longword
Description	This function is used to determine largest available free memory of contiguous memory on the heap.
Parameters	None.
Returns	Returns, after defragmentation of the freelist the size (in bytes) of the largest free block of contiguous memory on the heap.
Requires	Nothing.
Example	dim block as longword ... block = MM_LargestFreeMemBlock()
Notes	None.

MM_TotalFreeMemSize

Prototype	sub function MM_TotalFreeMemSize() as longword
Description	This function is used to determine total free memory size on the heap.
Parameters	None.
Returns	Returns the size (in bytes) of the total free memory on the heap.
Requires	Nothing.
Example	dim total as longword ... total = MM_TotalFreeMemSize()
Notes	None.

Library Example

Copy Code To Clipboard

program MM_Example

' Structure that describes Item object
structure  tItem
    dim id as longword     ' Item number
    dim name as ^char      ' Item name
end structure

dim it as ^tItem[3]        ' Array of pointers to Item objects
dim txt as char[15]
dim freeMemSize as longword
dim largerstFreeBlock as longword

' Allocate and initialize a new Item object and returns pointer to created Item
sub function make_item(dim byref name as string) as ^tItem
  dim item as ^tItem
  item =  malloc(sizeof(tItem))             ' Allocate a block of memory for a new Item object
  if item = 0 then                          ' If allocation failed return null
    result = 0
    exit
  end if

  memset(item, 0, sizeof(tItem))            ' Initialize the members of the new Item
  item^.id = longword(-1)
  item^.name = 0

  item^.name = malloc(strlen(name) + 1)     ' Allocate a block of memory for a name in the Item
  if item^.name = 0 then                    ' If allocation failed return null
    Free(item, sizeof(tItem))
    result = 0
    exit
  end if
  strcpy(item^.name, name)                  ' Save a copy of the name in the new Item

  result = item                             ' Return the created Item object
end sub

' Deallocate an Item object
sub procedure destroy_item(dim item as ^tItem)
  if item = 0 then                          ' Check for a null object pointer
    exit
  end if

  if (item^.name <> 0)then
    Free(item^.name, strlen(item^.name) + 1)' Deallocate the name string saved within the Item
    item^.name = 0
  end if

  Free(item, sizeof(tItem))                 ' Deallocate the Item object itself
end sub

main:
  MM_Init()

  freeMemSize = MM_TotalFreeMemSize()          ' Get free memory size before allocating
  largerstFreeBlock = MM_LargestFreeMemBlock() ' Get largest free memory block size before allocating

  it[0] = make_item("one")                     ' Allocate object
  it[1] = make_item("two")
  it[2] = make_item("three")
  freeMemSize = MM_TotalFreeMemSize()          ' Get free memory size
  largerstFreeBlock = MM_LargestFreeMemBlock() ' Get largest free memory block size
  strcpy(txt,it[0]^.name)
  strcpy(txt,it[1]^.name)
  strcpy(txt,it[2]^.name)

  destroy_item(it[0])                          ' Deallocate the Item object
  it[0] = make_item("instead one")             ' Make another Item object
  strcpy(txt,it[0]^.name)
  strcpy(txt,it[1]^.name)
  strcpy(txt,it[2]^.name)

  destroy_item(it[1])                          ' Deallocate Items
  destroy_item(it[2])
  freeMemSize = MM_TotalFreeMemSize()          ' Get free memory size
end.

Want more examples and libraries?
Find them on