Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Memory /: Chapter 2 - Memory Manager

Summary of the Memory Manager

Pascal Summary

Constants

CONST
   {Gestalt constants}
   gestaltOSAttr              = 'os  ';   {O/S attributes}
   gestaltTempMemSupport      = 4;        {temp memory support present}
   gestaltRealTempMemory      = 5;        {temp memory handles are real}
   gestaltTempMemTracked      = 6;        {temp memory handles tracked}
   maxSize                    = $800000;  {maximum size of a block}

Data Types

TYPE
   SignedByte           = -128..127;      {arbitrary byte of memory}
   Byte                 = 0..255;         {unsigned, arbitrary byte}
   Ptr                  = ^SignedByte;    {pointer to nonrelocatable block}
   Handle               = ^Ptr;           {handle to relocatable block}
   Str255               = STRING[255];    {Pascal string}
   StringPtr            = ^Str255;
   StringHandle         = ^StringPtr;
   ProcPtr              = Ptr;            {procedure pointer}

   Size                 = LongInt;        {size in bytes of block}
   Zone =
   RECORD
      bkLim:         Ptr;                 {first usable byte after zone}
      purgePtr:      Ptr;                 {used internally}
      hFstFree:      Ptr;                 {first free master pointer}
      zcbFree:       LongInt;             {number of free bytes}
      gzProc:        ProcPtr;             {grow-zone function}
      moreMast:      Integer;             {number of master ptrs to allocate}
      flags:         Integer;             {used internally}
      cntRel:        Integer;             {reserved}
      maxRel:        Integer;             {reserved}
      cntNRel:       Integer;             {reserved}
      maxNRel:       Integer;             {reserved}
      cntEmpty:      Integer;             {reserved}
      cntHandles:    Integer;             {reserved}
      minCBFree:     LongInt;             {reserved}
      purgeProc:     ProcPtr;             {purge-warning procedure}
      sparePtr:      Ptr;                 {used internally}
      allocPtr:      Ptr;                 {used internally}
      heapData:      Integer;             {first usable byte in zone}
   END;

   THz = ^Zone;                           {zone pointer}

Memory Manager Routines

Setting Up the Application Heap

PROCEDURE MaxApplZone;
PROCEDURE MoreMasters;

Allocating and Releasing Relocatable Blocks of Memory

FUNCTION NewHandle		(logicalSize: Size): Handle;
FUNCTION NewHandleSys		(logicalSize: Size): Handle;
FUNCTION NewHandleClear		(logicalSize: Size): Handle;
FUNCTION NewHandleSysClear	(logicalSize: Size): Handle;
FUNCTION NewEmptyHandle		: Handle;
FUNCTION NewEmptyHandleSys	: Handle;
PROCEDURE DisposeHandle		(h: Handle);

Allocating and Releasing Nonrelocatable Blocks of Memory

FUNCTION NewPtr			(logicalSize: Size): Ptr;
FUNCTION NewPtrSys		(logicalSize: Size): Ptr;
FUNCTION NewPtrClear		(logicalSize: Size): Ptr;
FUNCTION NewPtrSysClear		(logicalSize: Size): Ptr;
PROCEDURE DisposePtr		(p: Ptr);

Changing the Sizes of Relocatable and Nonrelocatable Blocks

FUNCTION GetHandleSize		(h: Handle): Size;
PROCEDURE SetHandleSize		(h: Handle; newSize: Size);
FUNCTION GetPtrSize		(p: Ptr): Size;
PROCEDURE SetPtrSize		(p: Ptr; newSize: Size);

Setting the Properties of Relocatable Blocks

FUNCTION HGetState			(h: Handle): SignedByte;
PROCEDURE HSetState			(h: Handle; flags: SignedByte);
PROCEDURE HLock				(h: Handle);
PROCEDURE HUnlock			(h: Handle);
PROCEDURE HPurge			(h: Handle);
PROCEDURE HNoPurge			(h: Handle);
PROCEDURE HSetRBit			(h: Handle);
PROCEDURE HClrRBit			(h: Handle);

Managing Relocatable Blocks

PROCEDURE EmptyHandle		(h: Handle);
PROCEDURE ReallocateHandle	(h: Handle; logicalSize: Size);
FUNCTION RecoverHandle		(p: Ptr): Handle;
PROCEDURE ReserveMem		(cbNeeded: Size);
PROCEDURE ReserveMemSys		(cbNeeded: Size);
PROCEDURE MoveHHi		(h: Handle);
PROCEDURE HLockHi		(h: Handle);

Manipulating Blocks of Memory

PROCEDURE BlockMove		(sourcePtr, destPtr: Ptr; byteCount: Size);
FUNCTION PtrToHand		(srcPtr: Ptr; VAR dstHndl: Handle; 
				size: LongInt): OSErr;
FUNCTION PtrToXHand		(srcPtr: Ptr; dstHndl: Handle; size: LongInt): 
				OSErr;
FUNCTION HandToHand		(VAR theHndl: Handle): OSErr;
FUNCTION HandAndHand		(aHndl, bHndl: Handle): OSErr;
FUNCTION PtrAndHand		(pntr: Ptr; hndl: Handle; size: LongInt): OSErr;

Assessing Memory Conditions

FUNCTION FreeMem		: LongInt;
FUNCTION FreeMemSys		: LongInt;
FUNCTION MaxBloc			k: LongInt;
FUNCTION MaxBlockSys		: LongInt;
PROCEDURE PurgeSpace		(VAR total: LongInt; VAR contig: LongInt);
FUNCTION StackSpace		: LongInt;
FUNCTION MemError		: OSErr;

Freeing Memory

FUNCTION CompactMem		(cbNeeded: Size): Size;
FUNCTION CompactMemSys		(cbNeeded: Size): Size;
PROCEDURE PurgeMem		(cbNeeded: Size);
PROCEDURE PurgeMemSys		(cbNeeded: Size);
FUNCTION MaxMem			(VAR grow: Size): Size;
FUNCTION MaxMemSys		(VAR grow: Size): Size;

Grow-Zone Operations

PROCEDURE SetGrowZone		(growZone: ProcPtr);
FUNCTION GZSaveHnd		: Handle;

Allocating Temporary Memory

FUNCTION TempNewHandle		(logicalSize: Size; VAR resultCode: OSErr): 
				Handle;
FUNCTION TempFreeMem		: LongInt;
FUNCTION TempMaxMem		(VAR grow: Size): Size;

Accessing Heap Zones

FUNCTION GetZone		: THz;
PROCEDURE SetZone		(hz: THz);
FUNCTION ApplicationZone	: THz;
FUNCTION SystemZone		: THz;
FUNCTION HandleZone		(h: Handle): THz;
FUNCTION PtrZone		(p: Ptr): THz;

Manipulating Heap Zones

FUNCTION GetApplLimit		: Ptr;
PROCEDURE SetApplLimit		(zoneLimit: Ptr);
FUNCTION TopMem			: Ptr;
PROCEDURE InitZone		(pGrowZone: ProcPtr; cMoreMasters: Integer; 
				limitPtr, startPtr: Ptr);
PROCEDURE InitApplZone;
PROCEDURE SetApplBase		(startPtr: Ptr);

Application-Defined Routines

Grow-Zone Functions

FUNCTION MyGrowZone		(cbNeeded: Size): LongInt;

Purge-Warning Procedures

PROCEDURE MyPurgeProc		(h: Handle);

C Summary

Constants

/*Gestalt constants*/
#define gestaltOSAttr            'os  ';     /*O/S attributes*/
#define gestaltTempMemSupport    4;          /*temp memory support present*/
#define gestaltRealTempMemory    5;          /*temp memory handles are real*/
#define gestaltTempMemTracked    6;          /*temp memory handles tracked*/
#define maxSize                  0x800000;   /*maximum size of a block*/

Data Types

typedef char SignedByte;               /*arbitrary byte of memory*/
typedef unsigned char Byte;            /*unsigned, arbitrary byte*/
typedef char *Ptr;                     /*pointer to nonrelocatable block*/
typedef Ptr *Handle;                   /*handle to relocatable block*/
typedef unsigned char Str255[256];     /*Pascal string*/
typedef unsigned char *StringPtr;
typedef unsigned char **StringHandle;
typedef long (*ProcPtr)();             /*procedure pointer*/
typedef long Size;                     /*size in bytes of block*/
struct Zone {
   Ptr               bkLim;            /*first usable byte after zone*/
   Ptr               purgePtr;         /*used internally*/
   Ptr               hFstFree;         /*first free master pointer*/
   long              zcbFree;          /*number of free bytes*/
   GrowZoneProcPtr   gzProc;           /*grow-zone function*/
   short             moreMast;         /*number of master ptrs to allocate*/
   short             flags;            /*used internally*/
   short             cntRel;           /*reserved*/
   short             maxRel;           /*reserved*/
   short             cntNRel;          /*reserved*/
   short             maxNRel;          /*reserved*/
   short             cntEmpty;         /*reserved*/
   short             cntHandles;       /*reserved*/
   long              minCBFree;        /*reserved*/
   ProcPtr           purgeProc;        /*purge-warning procedure*/
   Ptr               sparePtr;         /*used internally*/
   Ptr               allocPtr;         /*used internally*/
   short             heapData;         /*first usable byte in zone*/
};
typedef struct Zone Zone;
typedef Zone *THz;                     /*zone pointer*/

Memory Manager Routines

Setting Up the Application Heap

pascal void MaxApplZone		(void);
pascal void MoreMasters		(void);

Allocating and Releasing Relocatable Blocks of Memory

pascal Handle NewHandle		(Size byteCount);
pascal Handle NewHandleSys	(Size byteCount);
pascal Handle NewHandleClear	(Size byteCount);
pascal Handle NewHandleSysClear
   				(Size byteCount);
pascal Handle NewEmptyHandle	(void);
pascal Handle NewEmptyHandleSys
   				(void);
pascal void DisposeHandle	(Handle h);

Allocating and Releasing Nonrelocatable Blocks of Memory

pascal Ptr NewPtr		(Size byteCount);
pascal Ptr NewPtrSys		(Size byteCount);
pascal Ptr NewPtrClear		(Size byteCount);
pascal Ptr NewPtrSysClear	(Size byteCount);
pascal void DisposePtr		(Ptr p);

Changing the Sizes of Relocatable and Nonrelocatable Blocks

pascal Size GetHandleSize	(Handle h);
pascal void SetHandleSize	(Handle h, Size newSize);
pascal Size GetPtrSize		(Ptr p);
pascal void SetPtrSize		(Ptr p, Size newSize);

Setting the Properties of Relocatable Blocks

pascal char HGetState		(Handle h);
pascal void HSetState		(Handle h, char flags);
pascal void HLock		(Handle h);
pascal void HUnlock		(Handle h);
pascal void HPurge		(Handle h);
pascal void HNoPurge		(Handle h);
pascal void HSetRBit		(Handle h);
pascal void HClrRBit		(Handle h);

Managing Relocatable Blocks

pascal void EmptyHandle		(Handle h);
pascal void ReallocateHandle	(Handle h, Size byteCount);
pascal Handle RecoverHandle	(Ptr p);
pascal void ReserveMem		(Size cbNeeded);
pascal void ReserveMemSys	(Size cbNeeded);
pascal void MoveHHi		(Handle h);
pascal void HLockHi		(Handle h);

Manipulating Blocks of Memory

pascal void BlockMove		(const void *srcPtr, void *destPtr, 
				Size byteCount);
pascal OSErr PtrToHand		(Ptr srcPtr, Handle *dstHndl, long size);
pascal OSErr PtrToXHand		(Ptr srcPtr, Handle dstHndl, long size);
pascal OSErr HandToHand		(Handle *theHndl);
pascal OSErr HandAndHand	(Handle hand1, Handle hand2);
pascal OSErr PtrAndHand		(Ptr ptr1, Handle hand2, long size);

Assessing Memory Conditions

pascal long FreeMem		(void);
pascal long FreeMemSys		(void);
pascal long MaxBlock		(void);
pascal long MaxBlockSys		(void);
pascal void PurgeSpace		(long *total, long *contig);
pascal long StackSpace		(void);
#define MemError()		(* (OSErr*) 0x0220)

Freeing Memory

pascal Size CompactMem		(Size cbNeeded);
pascal Size CompactMemSys	(Size cbNeeded);
pascal void PurgeMem		(Size cbNeeded);
pascal void PurgeMemSys		(Size cbNeeded);
pascal Size MaxMem		(Size *grow);
pascal Size MaxMemSys		(Size *grow);

Grow-Zone Operations

pascal void SetGrowZone		(GrowZoneProcPtr growZone);
#define GZSaveHnd()		(* (Handle*) 0x0328)

Allocating Temporary Memory

pascal Handle TempNewHandle	(Size logicalSize, OSErr *resultCode);
pascal long TempFreeMem		(void);
pascal Size TempMaxMem		(Size *grow);

Accessing Heap Zones

pascal THz GetZone		(void);
pascal void SetZone		(THz hz);
#define ApplicationZone() 	(* (THz*) 0x02AA)
#define SystemZone() 		(* (THz*) 0x02A6)
pascal THz HandleZone		(Handle h);
pascal THz PtrZone		(Ptr p);

Manipulating Heap Zones

#define GetApplLimit() 		(* (Ptr*) 0x0130)
pascal void SetApplLimit	(void *zoneLimit);
#define TopMem() 		(* (Ptr*) 0x0108)
pascal void InitZone		(GrowZoneProcPtr pgrowZone, short cmoreMasters, 
				void *limitPtr, void *startPtr);
pascal void InitApplZone	(void);
pascal void SetApplBase		(void *startPtr);

Application-Defined Routines

Grow-Zone Functions

pascal long MyGrowZone		(Size cbNeeded);

Purge-Warning Procedures

pascal void MyPurgeProc		(Handle h);

Assembly-Language Summary

Constants

;flags in trap words
CLEAR             EQU      $200     ;set all bytes in block to 0
SYS               EQU      $400     ;use the system heap
;values for the tag byte of a block header
tyBkFree          EQU      0        ;free block
tyBkNRel          EQU      1        ;nonrelocatable block
tyBkRel           EQU      2        ;relocatable block
;flags for the high-order byte of a 24-bit master pointer
lock              EQU      7        ;lock bit
purge             EQU      6        ;purge bit
resource          EQU      5        ;resource bit

Data Structures

Zone Data Structure
0 bkLim long pointer to first usable byte after zone
4 purgePtr long used internally
8 hFstFree long first free master pointer
12 zcbFree 4 bytes number of free bytes in zone
16 gzProc long grow-zone function
20 mAllocCnt word number of master pointers to allocate
22 flags word used internally
24 cntRel word reserved
26 maxRel word reserved
28 cntNRel word reserved
30 maxNRel word reserved
32 cntEmpty word reserved
34 cntHandles word reserved
36 minCBFree long reserved
40 purgeProc long purge-warning procedure
44 sparePtr long used internally
48 allocPtr long used internally
52 heapData word first usable byte in zone

0	bkLim	long	pointer to first usable byte after zone
4	purgePtr	long	used internally
8	hFstFree	long	first free master pointer
12	zcbFree	4 bytes	number of free bytes in zone
16	gzProc	long	grow-zone function
20	mAllocCnt	word	number of master pointers to allocate
22	flags	word	used internally
24	cntRel	word	reserved
26	maxRel	word	reserved
28	cntNRel	word	reserved
30	maxNRel	word	reserved
32	cntEmpty	word	reserved
34	cntHandles	word	reserved
36	minCBFree	long	reserved
40	purgeProc	long	purge-warning procedure
44	sparePtr	long	used internally
48	allocPtr	long	used internally
52	heapData	word	first usable byte in zone

Parameter Block for `InitZone` Procedure
0 startPtr long first byte of new zone
4 limitPtr long first byte beyond new zone
8 cMoreMasters word number of master pointers to be allocated at a time
10 pGrowZone long pointer to grow-zone function for new zone

0	startPtr	long	first byte of new zone
4	limitPtr	long	first byte beyond new zone
8	cMoreMasters	word	number of master pointers to be allocated at a time
10	pGrowZone	long	pointer to grow-zone function for new zone

Trap Macros

Trap Macro Names
Pascal name Trap macro name
BlockMove _BlockMove
CompactMem _CompactMem
CompactMemSys _CompactMem
DisposeHandle _DisposeHandle
DisposePtr _DisposePtr
EmptyHandle _EmptyHandle
FreeMem _FreeMem
FreeMemSys _FreeMem
GetHandleSize _GetHandleSize
GetPtrSize _GetPtrSize
GetZone _GetZone
HandAndHand _HandAndHand
HandleZone _HandleZone
HandToHand _HandToHand
HClrRBit _HClrRBit
HGetState _HGetState
HLock _HLock
HNoPurge _HNoPurge
HPurge _HPurge
HSetRBit _HSetRBit
HSetState _HSetState
HUnlock _HUnlock
InitApplZone _InitApplZone
InitZone _InitZone
MaxApplZone _MaxApplZone
MaxBlock _MaxBlock
MaxBlockSys _MaxBlock
MaxMem _MaxMem
MaxMemSys _MaxMem
MoreMasters _MoreMasters
MoveHHi _MoveHHi
NewEmptyHandle _NewEmptyHandle
NewEmptyHandleSys _NewEmptyHandle
NewHandle _NewHandle
NewHandleClear _NewHandle
NewHandleSys _NewHandle
NewHandleSysClear _NewHandle
NewPtr _NewPtr
NewPtrClear _NewPtr
NewPtrSys _NewPtr
NewPtrSysClear _NewPtr
PtrAndHand _PtrAndHand
PtrToHand _PtrToHand
PtrToXHand _PtrToXHand
PtrZone _PtrZone
PurgeMem _PurgeMem
PurgeMemSys _PurgeMem
PurgeSpace _PurgeSpace
ReallocateHandle _ReallocHandle
RecoverHandle _RecoverHandle
ReserveMem _ResrvMem
ReserveMemSys _ResrvMem
SetApplBase _SetApplBase
SetApplLimit _SetApplLimit
SetGrowZone _SetGrowZone
SetHandleSize _SetHandleSize
SetPtrSize _SetPtrSize
SetZone _SetZone
StackSpace _StackSpace

Pascal name	Trap macro name
BlockMove	_BlockMove
CompactMem	_CompactMem
CompactMemSys	_CompactMem
DisposeHandle	_DisposeHandle
DisposePtr	_DisposePtr
EmptyHandle	_EmptyHandle
FreeMem	_FreeMem
FreeMemSys	_FreeMem
GetHandleSize	_GetHandleSize
GetPtrSize	_GetPtrSize
GetZone	_GetZone
HandAndHand	_HandAndHand
HandleZone	_HandleZone
HandToHand	_HandToHand
HClrRBit	_HClrRBit
HGetState	_HGetState
HLock	_HLock
HNoPurge	_HNoPurge
HPurge	_HPurge
HSetRBit	_HSetRBit
HSetState	_HSetState
HUnlock	_HUnlock
InitApplZone	_InitApplZone
InitZone	_InitZone
MaxApplZone	_MaxApplZone
MaxBlock	_MaxBlock
MaxBlockSys	_MaxBlock
MaxMem	_MaxMem
MaxMemSys	_MaxMem
MoreMasters	_MoreMasters
MoveHHi	_MoveHHi
NewEmptyHandle	_NewEmptyHandle
NewEmptyHandleSys	_NewEmptyHandle
NewHandle	_NewHandle
NewHandleClear	_NewHandle
NewHandleSys	_NewHandle
NewHandleSysClear	_NewHandle
NewPtr	_NewPtr
NewPtrClear	_NewPtr
NewPtrSys	_NewPtr
NewPtrSysClear	_NewPtr
PtrAndHand	_PtrAndHand
PtrToHand	_PtrToHand
PtrToXHand	_PtrToXHand
PtrZone	_PtrZone
PurgeMem	_PurgeMem
PurgeMemSys	_PurgeMem
PurgeSpace	_PurgeSpace
ReallocateHandle	_ReallocHandle
RecoverHandle	_RecoverHandle
ReserveMem	_ResrvMem
ReserveMemSys	_ResrvMem
SetApplBase	_SetApplBase
SetApplLimit	_SetApplLimit
SetGrowZone	_SetGrowZone
SetHandleSize	_SetHandleSize
SetPtrSize	_SetPtrSize
SetZone	_SetZone
StackSpace	_StackSpace

Trap Macro Requiring Routine Selectors

_OSDispatch
Selector Routine

$0015 TempMaxMem

$0018 TempFreeMem

$001D TempNewHandle

Global Variables
ApplLimit long The application heap limit, beyond which the heap cannot expand.
ApplZone long A pointer to the original application heap zone.
BufPtr long Address of highest byte of allocatable memory.
CurStackBase long Address of base of stack; start of application global variables.
GZRootHnd long A handle to a block that the grow-zone function must not move.
HeapEnd long Address of end of application heap zone.
MemErr word The current value that `MemError` would return.
MemTop long After startup time, the address at the end of an application's partition.
SysZone long A pointer to the system heap zone.
TheZone long A pointer to the current heap zone.

Result Codes
noErr 0 No error
paramErr -50 Error in parameter list
memROZErr -99 Operation on a read-only zone
memFullErr -108 Not enough memory
nilHandleErr -109 `NIL` master pointer
memWZErr -111 Attempt to operate on a free block
memPurErr -112 Attempt to purge a locked block
memBCErr -115 Block check failed
memLockedErr -117 Block is locked

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

Selector	Routine
$0015	TempMaxMem
$0018	TempFreeMem
$001D	TempNewHandle

ApplLimit	long	The application heap limit, beyond which the heap cannot expand.
ApplZone	long	A pointer to the original application heap zone.
BufPtr	long	Address of highest byte of allocatable memory.
CurStackBase	long	Address of base of stack; start of application global variables.
GZRootHnd	long	A handle to a block that the grow-zone function must not move.
HeapEnd	long	Address of end of application heap zone.
MemErr	word	The current value that `MemError` would return.
MemTop	long	After startup time, the address at the end of an application's partition.
SysZone	long	A pointer to the system heap zone.
TheZone	long	A pointer to the current heap zone.

noErr	0	No error
paramErr	-50	Error in parameter list
memROZErr	-99	Operation on a read-only zone
memFullErr	-108	Not enough memory
nilHandleErr	-109	`NIL` master pointer
memWZErr	-111	Attempt to operate on a free block
memPurErr	-112	Attempt to purge a locked block
memBCErr	-115	Block check failed
memLockedErr	-117	Block is locked

Legacy Document

Summary of the Memory Manager

Pascal Summary

Constants

Data Types

Memory Manager Routines

Setting Up the Application Heap

Allocating and Releasing Relocatable Blocks of Memory

Allocating and Releasing Nonrelocatable Blocks of Memory

Changing the Sizes of Relocatable and Nonrelocatable Blocks

Setting the Properties of Relocatable Blocks

Managing Relocatable Blocks

Manipulating Blocks of Memory

Assessing Memory Conditions

Freeing Memory

Grow-Zone Operations

Allocating Temporary Memory

Accessing Heap Zones

Manipulating Heap Zones

Application-Defined Routines

Grow-Zone Functions

Purge-Warning Procedures

C Summary

Constants

Data Types

Memory Manager Routines

Setting Up the Application Heap

Allocating and Releasing Relocatable Blocks of Memory

Allocating and Releasing Nonrelocatable Blocks of Memory

Changing the Sizes of Relocatable and Nonrelocatable Blocks

Setting the Properties of Relocatable Blocks

Managing Relocatable Blocks

Manipulating Blocks of Memory

Assessing Memory Conditions

Freeing Memory

Grow-Zone Operations

Allocating Temporary Memory

Accessing Heap Zones

Manipulating Heap Zones

Application-Defined Routines

Grow-Zone Functions

Purge-Warning Procedures

Assembly-Language Summary

Constants

Data Structures

Parameter Block for InitZone Procedure 0startPtrlongfirst byte of new zone 4limitPtrlongfirst byte beyond new zone 8cMoreMasterswordnumber of master pointers to be allocated at a time 10pGrowZonelongpointer to grow-zone function for new zone

Trap Macros

Trap Macro Requiring Routine Selectors

Parameter Block for `InitZone` Procedure
0 startPtr long first byte of new zone
4 limitPtr long first byte beyond new zone
8 cMoreMasters word number of master pointers to be allocated at a time
10 pGrowZone long pointer to grow-zone function for new zone