Important: The information in this document is obsolete and should not be used for new development.
NewHandle
You can use theNewHandle
function to allocate a relocatable memory block of a specified size.
FUNCTION NewHandle (logicalSize: Size): Handle;
logicalSize
- The requested size (in bytes) of the relocatable block.
DESCRIPTION
TheNewHandle
function attempts to allocate a new relocatable block in the current heap zone with a logical size oflogicalSize
bytes and then return a handle to the block. The new block is unlocked and unpurgeable. IfNewHandle
cannot allocate a block of the requested size, it returnsNIL
.
The
- WARNING
- 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 typeHandle
. The resulting "fake handle" would not reference a relocatable block and could cause a system crash.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. ThenNewHandle
tries again to free the necessary amount of memory, once more compacting and purging the heap zone if necessary. If memory still cannot be allocated,NewHandle
calls the grow-zone function again, unless that function had returned 0, in which caseNewHandle
gives up and returnsNIL
.SPECIAL CONSIDERATIONS
BecauseNewHandle
allocates memory, you should not call it at interrupt time.ASSEMBLY-LANGUAGE INFORMATION
The registers on entry and exit forNewHandle
are
Registers on entry A0 Number of logical bytes requested
Registers on exit A0 Address of the new block's master pointer or NIL
D0 Result code You can specify that the
NewHandle
function apply to the system heap zone instead of the current zone by setting bit 10 of the routine trap word. In most development systems, you can do this by supplying the wordSYS
as the second argument to the routine macro, as follows:
_NewHandle ,SYSIf you want to clear the bytes of a block of memory to 0 when you allocate it with theNewHandle
function, set bit 9 of the routine trap word. You can usually do this by supplying the wordCLEAR
as the second argument to the routine macro, as follows:
_NewHandle ,CLEARYou can combineSYS
andCLEAR
in the same macro call, butSYS
must come first.
_NewHandle ,SYS,CLEARRESULT CODES
noErr 0 No error memFullErr -108 Not enough memory in heap zone SEE ALSO
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 theReserveMem
procedure on page 2-55.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
MoveHHi
procedure on page 2-56.