Inside Macintosh: Memory /

Chapter 1 - Introduction to Memory Management / Memory Management Reference

Memory Management Routines / Managing Relocatable Blocks

EmptyHandle

The EmptyHandle procedure allows you to free memory taken by a relocatable block without freeing the relocatable block's master pointer for other uses.

PROCEDURE EmptyHandle (h: Handle);

h

A handle to a relocatable block.

DESCRIPTION

The EmptyHandle procedure purges the relocatable block whose handle is h and sets the handle's master pointer to NIL. The block whose handle is h must be unlocked but need not be purgeable.

Note

If there are multiple handles to the relocatable block, then calling
the EmptyHandle procedure empties them all, because all of the handles share a common master pointer. When you later use ReallocateHandle to reallocate space for the block, the master pointer is updated, and all of the handles reference the new block correctly.

SPECIAL CONSIDERATIONS

Because EmptyHandle purges memory, you should not call it at interrupt time.

ASSEMBLY-LANGUAGE INFORMATION

The registers on entry and exit for EmptyHandle are

Registers on entry
A0	Handle to relocatable block

Registers on exit
A0	Handle to relocatable block
D0	Result code

RESULT CODES

noErr	0	No error
memWZErr	-111	Attempt to operate on a free block
memPurErr	-112	Attempt to purge a locked block

SEE ALSO

To free the memory taken up by a relocatable block and release the block's master pointer for other uses, use the DisposeHandle procedure, described on page 1-57.