How to Manage Dynamic Memory (Allocation / Deallocation) in FB

Forum for discussion about the documentation project.
fxm
Posts: 8524
Joined: Apr 22, 2009 12:46
Location: Paris (suburbs), FRANCE

How to Manage Dynamic Memory (Allocation / Deallocation) in FB

Postby fxm » May 18, 2018 11:54

FreeBASIC supports three basic types of memory allocation:
- Static allocation occurs for static and global variables. Memory is allocated once when the program runs and persists throughout the life of the program.
- Stack allocation occurs for procedure parameters and local variables. Memory is allocated when the corresponding block is entered, and released when the block is left, as many times as necessary.
- Dynamic allocation is the subject of this article.

Static allocation and stack allocation have two things in common:
- The size of the variable must be known at compile time.
- Memory allocation and deallocation occur automatically (when the variable is instantiated then destroyed). The user can not anticipate the destruction of such a variable.

Most of the time, that is fine. However, there are situations where one or other of these constraints cause problems (when the memory needed depends on user input, the sizing can only be determined during run-time).

If the size of everything must be declared at compile time, the best is try to estimate the maximum size of the variables needed and hope this will be enough.
This is a bad solution for at least third reasons:
- First, it leads to wasting memory if it is not fully used.
- Second, most normal variables are allocated in a part of the memory called the stack. The amount of stack memory for a program is usually quite low (1 MB by default). If exceeding this number, the stack overflow will occur, and the program will abort.
- Third, and most importantly, this can lead to artificial limitations and / or overflows. What happens if the required memory becomes greater than the reserved memory (stopping the program, emitting message to user, ...).

Fortunately, these problems are easily solved through the dynamic allocation of memory. Dynamic memory allocation is a way of running programs to request memory from the operating system when needed. This memory does not come from the program's limited stack memory, but it is rather allocated from a much larger memory pool managed by the operating system called heap. On modern machines, the heap can have a size of several gigabytes.

1) Keywords for dynamic memory allocation:
    There are two sets of keyword for dynamic allocation / deallocation:
    • [C]Allocate / Reallocate / Deallocate: for raw memory allocation then deallocation, for simple pre-defined types or buffers (as numeric pre-defined types, user buffer, ...).
    • New / Delete: for memory allocation + construction then destruction + deallocation, for object type (as var-len strings, UDTs, ...).
    Mixing keywords between these two sets is very strongly discouraged when managing a same memory block.
2) Dynamic memory allocation management by using [C]Allocate / Reallocate / Deallocate:
    For each keyword, see the detailed syntax, precise description and examples in the individual documentation pages.

    Additional functionalities and tips for use:
    • [C]Allocate / Reallocate allows to know if memory allocation is successful (otherwise a nul pointer is returned).
    • Even if the allocated memory size is requested for 0 Byte, a non null pointer is returned and its value should be used to then release the allocation (except for Reallocate(pointer, 0) which behaves similar to Deallocate).
    • For memory deallocation, Deallocate can be called on any type of pointer (with the right value anyway).
    • If the user absolutely wants to use this type of allocation for an object (for example to be able to do reallocation), it's up to him to manually call if necessary the constructor and the destructor (by using member access operator) at the right way.
    • After deallocation, the pointer value becomes invalid (pointing to an invalid memory address), and its reuse (for dereferencing or calling Deallocate again) will result in undefined behavior.
    • If the requested memory could not be allocated, [C]Allocate or Reallocate returns a null pointer (but it is not the case for New that always returns a non null pointer).
3) Dynamic memory allocation management by using New / Delete:
    For each keyword, see the detailed syntax, precise description and examples in the individual documentation pages.

    Additional functionalities and tips for use:
    • New does not signal if memory allocation is successful (program hangs).
      (this exists in C++ by using the 'new (nothrow)' syntax, for FB: see the feature request #302)
    • Even if the allocated memory size is requested for 0 Byte ('New predefined_datatype[0]'), a non null pointer is returned and its value should be used to then release the allocation.
    • For object destruction and memory deallocation, Delete must be called on a rightly typed pointer (otherwise the object destructor will be not called and that may resulting in memory leak).
    • The user can also use this type of allocation for a simple pre-defined types (except for the fix-len strings), but this does not functionally add anything, except a simpler usage syntax for allocation.
    • After destruction + deallocation, the pointer value becomes invalid (pointing to an invalid memory address), and its reuse (for dereferencing or calling Delete again) will result in undefined behavior.
    • If the requested memory could not be allocated, New returns a null pointer (but it is not the case for [C]Allocate or Reallocate that always returns a non null pointer).
    • If used, the special placement New (using memory already allocated) induces only object construction, so use Delete is forbidden (to avoid double request of deallocation). If necessary, the object destruction must be manually do by user (calling the destructor by using member access operator).
4) Variant by using Redim / Erase:
    FreeBASIC also supports dynamic arrays (variable-length arrays).
    The memory used by a dynamic array to store its elements is allocated at run-time in the heap. Dynamic arrays can contain simple types as well as complex objects.
    By using Redim, the user does not need to call the constructor / destructor because Redim does this automatically when adding / removing element. Erase then destroys all the remaining elements to completely free the memory allocated to them.
5) Use cases by comparing 4 methods:
    Usage example on a set of objects, by comparing 4 methods:
    - 3 objects + 1: Callocate, Reallocate, Deallocate, (+ .constructor + .destructor).
    - 3 objects: New, Delete.
    - 3 objects: Placement New, (+ .destructor).
    - 3 objects + 1: Redim, Erase.

    Code: Select all

    Type UDT
      Dim As String S = "FreeBASIC"                '' induce an implicit constructor and destructor
    End Type

    Dim As UDT Ptr p1 = Callocate(3, Sizeof(UDT))  '' allocate cleared memory for 3 elements (string descriptors cleared,
                                                   ''     but maybe useless because of the constructor's call right behind)
    For I As Integer = 0 To 2
      p1[I].Constructor()                          '' call the constructor on each element
    Next I
    For I As Integer = 0 To 2
      p1[I].S &= Str(I)                            '' add the element number to the string of each element
    Next I
    For I As Integer = 0 To 2
      Print "'" & p1[I].S & "'",                   '' print each element string
    Next I
    Print
    p1 = Reallocate(p1, 4 * Sizeof(UDT))           '' reallocate memory for one additional element
    Clear p1[3], 0, 3 * Sizeof(Integer)            '' clear the descriptor of the additional element,
                                                   ''     but maybe useless because of the constructor's call right behind
    p1[3].Constructor()                            '' call the constructor on the additional element
    p1[3].S &= Str(3)                              '' add the element number to the string of the additional element
    For I As Integer = 0 To 3
      Print "'" & p1[I].S & "'",                   '' print each element string
    Next I
    Print
    For I As Integer = 0 To 3
      p1[I].Destructor()                           '' call the constructor on each element
    Next I
    Deallocate(p1)                                 '' deallocate the memory
    Print

    Dim As UDT Ptr p2 = New UDT[3]                 '' allocate memory and construct 3 elements
    For I As Integer = 0 To 2
      p2[I].S &= Str(I)                            '' add the element number to the string of each element
    Next I
    For I As Integer = 0 To 2
      Print "'" & p2[I].S & "'",                   '' print each element string
    Next I
    Print
    Delete [] p2                                   '' destroy the 3 element and deallocate the memory
    Print

    Redim As Byte array(0 to 3 * Sizeof(UDT) - 1)  '' allocate buffer for 3 elements
    Dim As Any Ptr p = @array(0)
    Dim As UDT Ptr p3 = New(p) UDT[3]              '' only construct the 3 elements in the buffer (placement New)
    For I As Integer = 0 To 2
      p3[I].S &= Str(I)                            '' add the element number to the string of each element
    Next I
    For I As Integer = 0 To 2
      Print "'" & p3[I].S & "'",                   '' print each element string
    Next I
    Print
    For I As Integer = 0 To 2
      p3[I].Destructor()                           '' call the constructor on each element
    Next I
    Erase array                                    '' deallocate the buffer
    Print

    Redim As UDT p4(0 To 2)                        '' define a dynamic array of 3 elements
    For I As Integer = 0 To 2
      p4(I).S &= Str(I)                            '' add the element number to the string of each element
    Next I
    For I As Integer = 0 To 2
      Print "'" & p4(I).S & "'",                   '' print each element string
    Next I
    Print
    Redim Preserve p4(0 To 3)                      '' resize the dynamic array for one additional element
    p4(3).S &= Str(3)                              '' add the element number to the string of the additional element
    For I As Integer = 0 To 3
      Print "'" & p4(I).S & "'",                   '' print each element string
    Next I
    Print
    Erase p4                                       '' erase the dynamic array
    Print

    Sleep

    Code: Select all

    'FreeBASIC0'  'FreeBASIC1'  'FreeBASIC2'
    'FreeBASIC0'  'FreeBASIC1'  'FreeBASIC2'  'FreeBASIC3'

    'FreeBASIC0'  'FreeBASIC1'  'FreeBASIC2'

    'FreeBASIC0'  'FreeBASIC1'  'FreeBASIC2'

    'FreeBASIC0'  'FreeBASIC1'  'FreeBASIC2'
    'FreeBASIC0'  'FreeBASIC1'  'FreeBASIC2'  'FreeBASIC3'
Last edited by fxm on May 19, 2018 10:48, edited 5 times in total.
jj2007
Posts: 932
Joined: Oct 23, 2016 15:28
Location: Roma, Italia
Contact:

Re: How to Manage Dynamic Memory in FB

Postby jj2007 » May 18, 2018 13:02

fxm wrote:Static and automatic allocation have two things in common:
- The size of the variable must be known at compile time.
- Memory allocation and deallocation occur automatically (when the variable is instantiated then destroyed).

Can you deallocate a static/global variable? If it's in the data section, you can't. Maybe the difference between static and global variables should be explained.

Otherwise, it's very well written, compliments.
marcov
Posts: 2650
Joined: Jun 16, 2005 9:45
Location: Eindhoven, NL
Contact:

Re: How to Manage Dynamic Memory in FB

Postby marcov » May 18, 2018 13:04

I mainly have a reservations with the names of the three types. I'd use stack based and heap based for automatic and dynamic because:

- There is a limited possibility for dynamic allocation on the stack (alloca in C)
- I would call automatic allocation stack allocation and reserve automatic allocation for forms of heap allocation that auto free (like ref counting or GC)
fxm
Posts: 8524
Joined: Apr 22, 2009 12:46
Location: Paris (suburbs), FRANCE

Re: How to Manage Dynamic Memory in FB

Postby fxm » May 18, 2018 14:16

I tried to improve the text a little without going into details off topic versus dynamic memory allocation.
fxm
Posts: 8524
Joined: Apr 22, 2009 12:46
Location: Paris (suburbs), FRANCE

Re: How to Manage Dynamic Memory (Allocation / Deallocation) in FB

Postby fxm » May 18, 2018 17:41

Added the paragraph: '4) Variant by using Redim / Erase'.
fxm
Posts: 8524
Joined: Apr 22, 2009 12:46
Location: Paris (suburbs), FRANCE

Re: How to Manage Dynamic Memory (Allocation / Deallocation) in FB

Postby fxm » May 18, 2018 21:10

Added the paragraph: '5) Use cases by comparing 4 methods'.

Return to “Documentation”

Who is online

Users browsing this forum: No registered users and 1 guest