Allocate

Allocates a block of memory from the free store

Syntax
   Declare Function Allocate cdecl ( ByVal count As UInteger ) As Any Ptr

Usage
   result = Allocate( count )

Parameters
   count
      The size, in bytes, of the block of memory to allocate.

Return Value
   If successful, the address of the start of the allocated memory is 
   returned. Otherwise, if the requested block size could not be allocated, 
   or if count < 0, then the null pointer (0) is returned.

Description
   Allocates, or reserves, count number of bytes from the free store 
   (heap). The newly allocated memory is not initialized.

   As the initial value of newly allocated memory is unspecified, Allocate 
   must not be directly used with String or Udt containing string, because 
   the string descriptor being not cleared (containing random data), that 
   may induce corrupted string or more (trying to write to a random place 
   in memory or trying to deallocate a random pointer).  It is mandatory in 
   that case (with string or UDT containing string) to use CAllocate 
   (clearing memory), or New Expression (calling constructor) in case of 
   UDT, or at worst after Allocate to explicitly clear the descriptor 
   (setting to 0) before the first string use.
   For allocating memory for a ZString or a WString, see the corresponding 
   page.

   The pointer that is returned is an Any Ptr and points to the start of 
   the allocated memory. This pointer is guaranteed to be unique, even if 
   count is zero.

   Allocated memory must be deallocated, or returned back to the free 
   store, with Deallocate when no longer needed. 

Example
   '' This program uses the ALLOCATE(...) function to create a buffer of 15 integers that is
   '' then filled with the first 15 numbers of the Fibonacci Sequence, then output to the
   '' screen. Note the call to DEALLOCATE(...) at the end of the program.

      Const integerCount As Integer = 15

      '' Try allocating memory for a number of integers.
      ''
      Dim buffer As Integer Ptr
      buffer = Allocate(integerCount * SizeOf(Integer))

      If (0 = buffer) Then
         Print "Error: unable to allocate memory, quitting."
         End -1
      End If

      '' Prime and fill the memory with the fibonacci sequence.
      ''
      buffer[0] = 0
      buffer[1] = 1
      For i As Integer = 2 To integerCount - 1
         buffer[i] = buffer[i - 1] + buffer[i - 2]
      Next

      '' Display the sequence.
      ''
      For i As Integer = 0 To integerCount - 1
         Print buffer[i] ;
      Next

      Deallocate(buffer)
      End 0

      Output is:
    0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

   It is important to free allocated memory if it's not going to be used 
   anymore. Unused memory that isn't freed is simply wasting memory, and if 
   the address of that memory is somehow overwritten or forgotten, that 
   memory can never be freed. This condition is known as a memory leak, and 
   should be avoided at all costs. Note that leaked memory is always 
   completely freed when the application terminates, either by an 
   "ordinary" exit or crash, so the leak "persists" only as long as the 
   application runs, nevertheless it's a good habit to free any allocated 
   memory inside your application. The following example demonstrates a 
   function with a memory leak, where the address of allocated memory is 
   lost and isn't and can't be freed anymore. If such a function is called 
   frequently, the total amount of memory wasted can add up quickly.

   '' Bad example of Allocate usage, causing memory leaks

   Sub BadAllocateExample()

      Dim p As Byte Ptr

      p = Allocate(420)   '' assign pointer to new memory

      p = Allocate(420)   '' reassign same pointer to different memory,
                     '' old address is lost and that memory is leaked

      Deallocate(p)

   End Sub

      '' Main
      BadAllocateExample() '' Creates a memory leak 
      Print "Memory leak!"
      BadAllocateExample() '' ... and another
      Print "Memory leak!"
      End

Dialect Differences
   * Not available in the -lang qb dialect unless referenced with the 
     alias __Allocate 

Differences from QB
   * New to FreeBASIC

See also
   * CAllocate
   * Reallocate
   * Deallocate

