Legacy Document

Inside Macintosh: Memory /

Chapter 2 - Memory Manager / Memory Manager Reference

Memory Manager Routines / Setting the Properties of Relocatable Blocks

HPurge

You can use the HPurge procedure to mark a relocatable block so that it can be purged if a memory request cannot be fulfilled after compaction.

PROCEDURE HPurge (h: Handle);

h

A handle to a relocatable block.

DESCRIPTION

The HPurge procedure makes the relocatable block to which h is a handle purgeable. If the block is already purgeable, HPurge does nothing.

The Memory Manager might purge the block when it needs to purge the heap zone containing the block to satisfy a memory request. A direct call to the PurgeMem procedure or the MaxMem function would also purge blocks marked as purgeable.

Once you mark a relocatable block as purgeable, you should make sure that handles to the block are not empty before you access the block. If they are empty, you must reallocate space for the block and recopy the block's data from another source, such as a resource file, before using the information in the block.

If the block to which h is a handle is locked, HPurge does not unlock the block but does mark it as purgeable. If you later call HUnlock on h, the block is subject to purging.

ASSEMBLY-LANGUAGE INFORMATION

The registers on entry and exit for HPurge are

Registers on entry
A0	Handle to make purgeable

Registers on exit
D0	Result code

RESULT CODES

noErr	0	No error
nilHandleErr	-109	NIL master pointer
memWZErr	-111	Attempt to operate on a free block

SEE ALSO

If the Memory Manager has purged a block, you can reallocate space for it by using the ReallocateHandle procedure, described on page 2-52.

You can immediately free the space taken by a handle without disposing of it by calling EmptyHandle. This procedure, described on page 2-51, does not require that the block be purgeable.