Legacy Document

Inside Macintosh: Memory /

Chapter 2 - Memory Manager / Memory Manager Reference

Memory Manager Routines / Managing Relocatable Blocks

ReserveMem

Use the ReserveMem procedure when you allocate a relocatable block that you intend to lock for long periods of time. This helps prevent heap fragmentation because it reserves space for the block as close to the bottom of the heap as possible. Consistent use of ReserveMem for this purpose ensures that all locked, relocatable blocks and nonrelocatable blocks are together at the bottom of the heap zone and thus do not prevent unlocked relocatable blocks from moving about the zone.

PROCEDURE ReserveMem (cbNeeded: Size);

cbNeeded

The number of bytes to reserve near the bottom of the heap.

DESCRIPTION

The ReserveMem procedure attempts to create free space for a block of cbNeeded contiguous logical bytes at the lowest possible position in the current heap zone. It pursues every available means of placing the block as close as possible to the bottom
of the zone, including moving other relocatable blocks upward, expanding the zone
(if possible), and purging blocks from it.

Because ReserveMem does not actually allocate the block, you must combine calls to ReserveMem with calls to the NewHandle function.

Do not use the ReserveMem procedure for a relocatable block you intend to lock for only a short period of time. If you do so and then allocate a nonrelocatable block above it, the relocatable block becomes trapped under the nonrelocatable block when you unlock that relocatable block.

Note

It isn't necessary to call ReserveMem to reserve space for a nonrelocatable block, because the NewPtr function calls it automatically. Also, you do not need to call ReserveMem to reserve memory before you load a locked resource into memory, because the Resource Manager calls ReserveMem automatically.

SPECIAL CONSIDERATIONS

Because the ReserveMem procedure could move and purge memory, you should not call it at interrupt time.

ASSEMBLY-LANGUAGE INFORMATION

The registers on entry and exit for ReserveMem are

Registers on entry
D0	Number of bytes to reserve

Registers on exit
D0	Result code

The ReserveMem procedure reserves memory in the current heap zone. If you want to reserve memory in the system heap zone rather than in the current heap zone, set 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:

_ResrvMem ,SYS

RESULT CODES

noErr	0	No error
memFullErr	-108	Not enough memory