Carbon


ReserveMem

Header: MacMemory.h Carbon status: Supported

Allocates a relocatable block of memory as close to the bottom of the heap as possible.

void ReserveMem (
    Size cbNeeded
);
cbNeeded

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

DISCUSSION

The ReserveMem function attempts to create free space for the specified number of 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.

Use the ReserveMem function when allocating 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.

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 function 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.

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.

Call the function MemError to get the result code. See “Result Codes”.

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

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when InterfaceLib 7.1 or later is installed. Exported by CarbonLib 1.0 and later and by InterfaceLib 7.1 and later.


© 2000 Apple Computer, Inc. — (Last Updated 4/6/2000)