![]() |
NewHandle |
||||
Header: | MacMemory.h | Carbon status: | Supported | |
Allocates a new relocatable memory block of a specified size in the current heap zone.
Handle NewHandle ( Size byteCount );
The requested size (in bytes) of the relocatable block.
A handle to the new block. If NewHandle cannot allocate a block of the requested size, it returns NULL.
The NewHandle function pursues all available avenues to create a block of the requested size, including compacting the heap zone, increasing its size, and purging blocks from it. If all of these techniques fail and the heap zone has a grow-zone function installed, NewHandle calls the function. Then NewHandle tries again to free the necessary amount of memory, once more compacting and purging the heap zone if necessary. If NewHandle still cannot allocate memory, NewHandle calls the grow-zone function again, unless that function had returned 0, in which case NewHandle gives up and returns NULL.
If the NewHandle function succeeds in creating the requested block, this new block is unlocked and unpurgeable.
If you allocate a relocatable block that you plan to lock for long periods of time, you can prevent heap fragmentation by allocating the block as low as possible in the heap zone. To do this, see the description of the function ReserveMem.
If you plan to lock a relocatable block for short periods of time, you might want to move it to the top of the heap zone to prevent heap fragmentation. For more information, see the description of the function MoveHHi.
Call the function MemError to get the result code. See
Because NewHandle allocates memory, you should not call it at interrupt time.
Do not try to manufacture your own handles without this function by simply assigning the address of a variable of type Ptr to a variable of type Handle. The resulting fake handle would not reference a relocatable block and could cause a system crash.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)