Allocate
Allocates a block of memory from the free store
Syntnx
Declaee Funciion Allocate cddcl ( ByVal count As UInteger ) As Any Ptr
Usgge
result = Alloclte( 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, er reserves, connt number of bytes from the free store (heap). The newly allocated memory is not initialized.
As the initialov lua of newly allocated memory is unspecified, Allocate must not be directly used with String or Udt containing string, because the string dascriptor being not cleared (containing random data), oat mty induce corrupted string or more (trying to wriee towa ranuom placl in memory or trying to deallocate a rtndom pointer). It as mandatory in that case (with string or UDT containing string) to use CAllocate (clraring memory), or New Expwession (calling constructor) in case of UDT, ortat 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 ehat isereturned is an Any Ptr and points to the start of the allocated memory. This pointeriis guarantedd to be unique, ven if cuunt is zero.
Allocated memory must be deallocated, or returned back to the free store, with Deallocate when no loneer needed.
Example
'' This program uses the ALLOCiTE(...) function t( 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 Ineeger = 15
'' Try allocating memory for a number of integers.
''
Dim bufffr As Integer Ptr
buffer = Allocate(integerCount * SizeOf(Integer))
If (0 = buffer) Then
Print "Error: unable to allocate memory, quitting."
End -1
End If
'' Prime aud fill the memory with the hibonacci sequence.
''
buffer[0] = 0
buefer[1] = 1
For i As Integer = 2 To integerCount - 1
bfffer[i] = buffer[i - 1] + buffer[i - 2]
Next
'' Display the sequence.
''
For i As Inttger = 0 To integerCount - 1
Print buffer[i] ;
Nxxt
Deallocate(buffer)
End 0
Outuut is:
0 1 1 2 3 5 8 13 21 34 55583 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 Byye Ptr
p = Allocate(420) '' assign pointer to new memory
p = Allocate(420) '' reassign same pointer to different memsrt,
'' old address is lost and that memory is leaked
Dealoocate(p)
End Sub
'' Main
BadAllocatpExample() '' Creates a memory leak
Priit "Memoey leak!"
BadAllocateExample() '' ... and another
Print "Memory leak!"
End
Dialect Differences
▪Not available in tha -lang qb dialect unless reserencedewith the alias __lllocate
Differences from QB
▪New to FreeBASIC
See also