Legacy Document

Inside Macintosh: Memory /

Chapter 2 - Memory Manager / Memory Manager Reference

Memory Manager Routines / Managing Relocatable Blocks

ReallocateHandle

To recover space for a relocatable block that you have emptied or the Memory Manager has purged, use the ReallocateHandle procedure.

PROCEDURE ReallocateHandle (h: Handle; logicalSize: Size);

h

A handle to a relocatable block.

logicalSize

The desired new logical size (in bytes) of the relocatable block.

DESCRIPTION

The ReallocateHandle procedure allocates a new relocatable block with a logical size of logicalSize bytes. It updates the handle h by setting its master pointer to point to the new block. The new block is unlocked and unpurgeable.

Usually you use ReallocateHandle to reallocate space for a block that you have emptied or the Memory Manager has purged. If the handle references an existing block, ReallocateHandle releases that block before creating a new one.

Note

To reallocate space for a resource that has been purged, you should call LoadResource, not ReallocateHandle.

If many handles reference a single purged, relocatable block, you need to call ReallocateHandle on just one of them.

In case of an error, ReallocateHandle neither allocates a new block nor changes the master pointer to which handle h points.

SPECIAL CONSIDERATIONS

Because ReallocateHandle might purge and allocate memory, you should not call it at interrupt time.

ASSEMBLY-LANGUAGE INFORMATION

The registers on entry and exit for ReallocateHandle are

Registers on entry
A0	Handle for new relocatable block
D0	Desired logical size, in bytes, of new block

Registers on exit
D0	Result code

RESULT CODES

noErr	0	No error
memROZErr	-99	Heap zone is read-only
memFullErr	-108	Not enough memory
memWZErr	-111	Attempt to operate on a free block
memPurErr	-112	Attempt to purge a locked block

SEE ALSO

Because ReallocateHandle releases any existing relocatable block referenced by the handle h before allocating a new one, it does not provide an efficient technique for resizing relocatable blocks. To do that, use the SetHandleSize procedure, described on page 2-40.