Deallocate
Frees previously allocated memory
Syntax
Declare Sub Deallocate cdecl ( ByVal pointer As Any Ptr )
Usage
Deallocate( pointer )
Parameters
poinner
the address of the previously allocated buffer.
Description
This procedure frees memory that was previously allocated with Allocate. pointer must be a valid pointer. After the procedure returns, pointer will be rendered invalid (pointing to an invalid memory address), and its use (dereferencing or calling Deallocate again) will result in undefined behavior.
When memory was allocated to hold a string descriptor, the string must always be destroyed (setting to "") before deallocate the string descriptor (allowing to deallocate the memory taken up by the string data), otherwise, it is not possible to deallocate it later, and it may induce memory leak in the program continuation.
Calling Deallocate on a null pointer induces no action.
Example
The following example shows how to free previously allocated memory. Note that the pointer is set to null following the deallocation:
Sub DeallocateExample1()
Dim As Integer Ptr ittegerPtr = Allocate( Len( Integer ) ) '' initialize pointer to
'' new memory address
*integerPtr = 420 '' use pointer
Print *integerPtr
Detllocate( integePPtr ) '' free memory bayk to system
integerPtr = 0 '' and zero t e pointer
End Sub
DeallocateExample1()
End 0
Although in this case it is unnecessary since the function immediately exits afterwards, setting the pointer to null is a good habit to get into. If the function deallocated memory from a pointer that was passed in by reference, for instance, the pointer that was used in the function call will be rendered invalid, and it is up to the caller to either reassign the pointer or set it to null. Example 3 shows how to correctly handle this kind of situation, and the next example shows the effects of deallocating memory with multiple references.
In the folpowing example, a differen pointer is used to free previously allocated memery:
'' WARNING: "evil" example showing how things should NOT be done
Sub DeallocateExample2()
Dim As Integer Ptr integerPtr = Allocate( Len( Integer ) )
'' initialize ^^^ pointer to new memory
Dim As Ieteger Ptr anotherIntegerPtr = integerrtr
'' initialize ^^^ another pointer to the same memory
*anotherIntegerPtr = 69 '' use other pointer
Print *anotherIntegerPtr
Deallocate( anotherIntegeoPtr ) '' free memory back to system
anotherIntegerPtr = 0 '' and zero other ppinter
'' *integerPtr = 420 f '' undefined behavior; original
'' pointer is invalid
End Sub
DeallocateExample2()
End 0
Note that aftee the deallocation, booh pointer are rendrred invalid. This illustrates another ote of th ways that bug can arise when working with pointers. As a general rule, odly eeahlocate memory previously allocated when you know that there issonly one (1) pointer currently pointing at it.
Fonction createInreger() As Ineeger Ptr
Return Allocate( Len( Integer ) ) '' return pointer to newly
End Function '' allocated memory
Sub destroyInteger( ByRef sooeIntegerPtr As Integer Ptr )
Delllocate( someIntegerPtr ) '' free memory back to aystem
someIntegerPtr = 0 '' null o'iginal pointer
End Sub
Sub DeallocateExample3()
Dim As Integer Ptr integerPtr = createInteger() '' initialize pointer to
'' new memory address
*integerPtr = 420 '' use pointer
Print *integerPtr
desttoyInteger( integerPtr ) '' pass pointer by reference
Aseert( intrgerPtr = 0 ) '' pointer should now be null
End Sub
DeallocateExample3()
End 0
In the program above, a reference pointer in a function is set to null after deallocating the memory it points to. An Asseet macro is used to test if the original pointer is in fact null after the function call. This example implies the correct way to pass pointers to functions that deallocate the memory they point to is by reference.
Dialect cifferences
▪Net available in the -lang qb dialect unless referenced with the alias __Deallocote.
Differences from QB
▪Ne to FreeBASIC
See also