OpenEuphoria

allocate_data

include machine.e 
namespace machine 
public function allocate_data(memory :positive_int n, types :boolean cleanup = 0) 

Allocate a contiguous block of data memory.

Parameters:

1. n : a positive integer, the size of the requested block.
2. cleanup : an integer, if non-zero, then the returned pointer will be automatically freed when its reference count drops to zero, or when passed as a parameter to delete.

Returns:

An atom, the address of the allocated memory or 0 if the memory can't be allocated. NOTE you must use either an atom or object to receive the returned value as sometimes the returned memory address is too larger for an integer to hold.

Comments:

• Since allocate acquires memory from the system, it is your responsiblity to return that memory when your application is done with it. There are two ways to do that - automatically or manually.
  • Automatically - If the cleanup parameter is non-zero, then the memory is returned when the variable that receives the address goes out of scope and is not referenced by anything else. Alternatively you can force it be released by calling the delete function.
  • Manually - If the cleanup parameter is zero, then you must call the free function at some point in your program to release the memory back to the system.
• When your program terminates, the operating system will reclaim all memory that your applicaiton acquired anyway.
• An address returned by this function shouldn't be passed to call. For that purpose you should use allocate_code instead.
• The address returned will be at least 8-byte aligned.

Example 1:

buffer = allocate(100) 
for i = 0 to 99 do 
    poke(buffer+i, 0) 
end for 

See Also:

Using Data Bytes, Using Data Words, Using Data Double Words, Using Strings, allocate_code, free