Legacy Document

Inside Macintosh: Memory /

Chapter 1 - Introduction to Memory Management / Memory Management Reference

Memory Management 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

RESULT CODES

noErr	0	No error
memFullErr	-108	Not enough memory