EmptyHandle

Purge a particular relocatable block

#include <Memory.h> Memory Manager

void EmptyHandle( theHandle );

Handle theHandle ; Handle whose data you wish to discard

EmptyHandle discards the data of an existing handle. It sets the handle's

master pointer to NIL, allowing subsequent allocations and compactions to

overwrite its data area.

theHandle is a handle to a relocatable data area, typically a value obtained via

NewHandle. For this function to succeed, theHandle must not be

locked (see HLock), but it need not be purgeable (EmptyHandle

overrides the non-purgeable attribute).

Returns: none; the MemError function may return an Error Code of:

noErr (0) No error

memWZErr (-111) Illegal operation on a free block

memPurErr (-112) Illegal operation on a locked block

Notes: EmptyHandle preemptively discards the contents of theHandle. Note that

it (and ALL Handles with the same value) remain valid (meaning that there

is still a master pointer allocated for this handle), but empty (unlike

DisposHandle, which discards the master pointer).

Most routines that operate on handles will return a nilHandleErr if passed

an empty handle.

theHandle need not be purgeable, but it must not be locked.

The NewEmptyHandle function creates an empty handle.

You might use this to free space in a custom heap zone grow procedure (see

SetGrowZone). Typically, you would then use ReallocHandle to get

some space back later, making theHandle (and all copies) back into valid

handles that lead to a real data area.

EmptyHandle is not a Boolean, unlike EmptyRect and EmptyRgn.

Referenced by (8):