Legacy Document

Inside Macintosh: Memory /

Chapter 1 - Introduction to Memory Management / Memory Management Reference

Memory Management 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
A0	Number of logical bytes requested

Registers on exit
A0	Address of the new block's master pointer or NIL
D0	Result code

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

RESULT 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 the ReserveMem procedure on page 1-70.

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 1-71.