GEOS SDK TechDocs
|
| 
3.1 Memory Etiquette
| 
3.3 Freeing Memory
MemAlloc(), MemAllocSetOwner(), MemReAlloc()
When you need a block of raw memory, you must use one of the kernel's memory allocation routines. You also must use kernel memory routines to change the size of a block or to reallocate space for a discarded block.
MemAlloc()
creates a block and assigns a handle to it. The routine must be passed the size (in bytes) of the block to be allocated, along with the
HeapAllocFlags
and
HeapFlags
for that block.
MemAlloc()
will set the block's owner as the owner of the thread that called it. It will return the handle of the newly-allocated block.
MemAllocSetOwner()
is the same as
MemAlloc()
, except that the caller explicitly sets the owner of the new block by passing the handle of the owning geode. Like
MemAlloc()
, it returns the handle of the new block. This is commonly used by drivers and shared libraries, which allocate memory owned by the geode which calls them. When the block's owner exits, the block will be freed, even if the block's creator is still running.
If you request a fixed block or pass the flag HAF_LOCK, the block will be allocated locked on the heap. However, the routine will still return just the memory handle. To translate this handle to a pointer, call the routine
MemDeref()
.
MemDeref()
is passed a block's handle and returns a pointer to the block (or a null pointer if the block has been discarded).
To change the size of a block, call the routine
MemReAlloc()
. This routine is also used to allocate memory for a block that has been discarded. The routine is passed the memory handle, the new size, and the
HeapAllocFlags
; it returns the block's memory handle. You can reallocate a fixed or locked block; however, the block may be moved on the global heap to satisfy the request. (This is the only way a fixed block can move.) As with
MemAlloc()
, you can request that the memory manager lock the block after reallocating it; you will then have to call
MemDeref()
to get the address of the block. Note that if the new size is
smaller
than the original size, the routine is guaranteed to succeed, and the block will not move from its current position. Reallocating a block to zero bytes discards the block but preserves its handle; the block can then be reallocated later.
If the memory manager is unable to accommodate a request, it will return an error condition. The requestor can prevent error messages by passing the flag HAF_NO_ERR; this will result in a system error if the memory cannot be allocated. Passing HAF_NO_ERR is therefore strongly discouraged.
GEOS SDK TechDocs
|
| 3.1 Memory Etiquette
| 3.3 Freeing Memory