Wiki source for KeyPgAllocate


Show raw source

{{fbdoc item="title" value="ALLOCATE"}}----
Allocates a block of memory from the free store

{{fbdoc item="syntax"}}##
[[KeyPgDeclare|declare]] [[KeyPgFunction|function]] **Allocate** [[KeyPgCdecl|cdecl]] ( [[KeyPgByval|byval]] //count// [[KeyPgAs|as]] [[KeyPgUinteger|uinteger]] ) [[KeyPgAs|as]] [[KeyPgAny|any]] [[KeyPgPtr|ptr]]
##
{{fbdoc item="usage"}}##
//result// = **Allocate**( //count// )
##
{{fbdoc item="param"}}
##//count//##
The size, in bytes, of the block of memory to allocate.

{{fbdoc item="ret"}}
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.

{{fbdoc item="desc"}}
Attempts to allocate, or reserve, ##//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 ##[[KeyPgString|String]]## or ##[[KeyPgType|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 ##[[KeyPgCallocate|Callocate]]## (clearing memory), or ##[[KeyPgOpNew|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.

The pointer that is returned is an [[KeyPgAny|any]] [[KeyPgPtr|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 ##[[KeyPgDeallocate|Deallocate]]## when no longer needed.

{{fbdoc item="ex"}}
{{fbdoc item="filename" value="examples/manual/memory/allocate.bas"}}%%(freebasic)
'' 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##
<<::c::

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.

{{fbdoc item="filename" value="examples/manual/memory/allocate2.bas"}}%%(freebasic)
'' 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
%%

{{fbdoc item="target"}}
- This procedure is not guaranteed to be thread-safe.

{{fbdoc item="lang"}}
- Not available in the //[[CompilerOptlang|-lang qb]]// dialect unless referenced with the alias ##**""__Allocate""**##

{{fbdoc item="diff"}}
- New to ""FreeBASIC""

{{fbdoc item="see"}}
- ##[[KeyPgCallocate|Callocate]]##
- ##[[KeyPgReallocate|Reallocate]]##
- ##[[KeyPgDeallocate|Deallocate]]##

{{fbdoc item="back" value="CatPgMemory|Memory Functions"}}
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki



sf.net phatcode