Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

Inside Macintosh: Memory /
Chapter 2 - Memory Manager / Memory Manager Reference
Memory Manager Routines / Allocating and Releasing Relocatable Blocks of Memory


NewHandle

You can use the NewHandle 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
The NewHandle function attempts to allocate a new relocatable block in the current heap zone with a logical size of logicalSize bytes and then return a handle to the block. The new block is unlocked and unpurgeable. If NewHandle cannot allocate a block of the requested size, it returns NIL.

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 type Handle. The resulting "fake handle" would not reference a relocatable block and could cause a system crash.
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 memory still cannot be allocated, NewHandle calls the grow-zone function again, unless that function had returned 0, in which case NewHandle gives up and returns NIL.

SPECIAL CONSIDERATIONS
Because NewHandle allocates memory, you should not call it at interrupt time.

ASSEMBLY-LANGUAGE INFORMATION
The registers on entry and exit for NewHandle are
Registers on entry
A0Number of logical bytes requested
Registers on exit
A0Address of the new block's master pointer or NIL
D0Result 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 word SYS as the second argument to the routine macro, as follows:

_NewHandle ,SYS
If you want to clear the bytes of a block of memory to 0 when you allocate it with the NewHandle function, set bit 9 of the routine trap word. You can usually do this by supplying the word CLEAR as the second argument to the routine macro, as follows:

_NewHandle ,CLEAR
You can combine SYS and CLEAR in the same macro call, but SYS must come first.

_NewHandle ,SYS,CLEAR
RESULT CODES
noErr0No error
memFullErr-108Not 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 the ReserveMem 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.


Previous Book Contents Book Index Next

© Apple Computer, Inc.
3 JUL 1996