- Generated by
1.9.1
|
Mac OS 9
|
Memory Manager Interfaces. More...
Go to the source code of this file.
Data Structures | |
| struct | Zone |
| struct | MemoryBlock |
| struct | LogicalToPhysicalTable |
| struct | VolumeVirtualMemoryInfo |
Macros | |
| #define | NewGrowZoneUPP(userRoutine) |
| #define | NewPurgeUPP(userRoutine) |
| #define | NewUserFnUPP(userRoutine) |
| #define | DisposeGrowZoneUPP(userUPP) DisposeRoutineDescriptor(userUPP) |
| #define | DisposePurgeUPP(userUPP) DisposeRoutineDescriptor(userUPP) |
| #define | DisposeUserFnUPP(userUPP) DisposeRoutineDescriptor(userUPP) |
| #define | InvokeGrowZoneUPP(cbNeeded, userUPP) (long)CALL_ONE_PARAMETER_UPP((userUPP), uppGrowZoneProcInfo, (cbNeeded)) |
| #define | InvokePurgeUPP(blockToPurge, userUPP) CALL_ONE_PARAMETER_UPP((userUPP), uppPurgeProcInfo, (blockToPurge)) |
| #define | InvokeUserFnUPP(parameter, userUPP) CALL_ONE_PARAMETER_UPP((userUPP), uppUserFnProcInfo, (parameter)) |
| #define | NewGrowZoneProc(userRoutine) NewGrowZoneUPP(userRoutine) |
| #define | NewPurgeProc(userRoutine) NewPurgeUPP(userRoutine) |
| #define | NewUserFnProc(userRoutine) NewUserFnUPP(userRoutine) |
| #define | CallGrowZoneProc(userRoutine, cbNeeded) InvokeGrowZoneUPP(cbNeeded, userRoutine) |
| #define | CallPurgeProc(userRoutine, blockToPurge) InvokePurgeUPP(blockToPurge, userRoutine) |
| #define | CallUserFnProc(userRoutine, parameter) InvokeUserFnUPP(parameter, userRoutine) |
| #define | StripAddress(theAddress) ((Ptr)theAddress) |
| #define | Translate24To32(addr24) ((Ptr)addr24) |
Typedefs | |
| typedef struct Zone | Zone |
| typedef Zone * | THz |
| typedef THz * | THzPtr |
| typedef struct MemoryBlock | MemoryBlock |
| typedef struct LogicalToPhysicalTable | LogicalToPhysicalTable |
| typedef short | PageState |
| typedef short | StatusRegisterContents |
| typedef struct VolumeVirtualMemoryInfo | VolumeVirtualMemoryInfo |
| typedef VolumeVirtualMemoryInfo * | VolumeVirtualMemoryInfoPtr |
Functions | |
| typedef | CALLBACK_API (long, GrowZoneProcPtr)(Size cbNeeded) |
| typedef | CALLBACK_API (void, PurgeProcPtr)(Handle blockToPurge) |
| typedef | CALLBACK_API_REGISTER68K (void, UserFnProcPtr,(void *parameter)) |
| typedef | STACK_UPP_TYPE (GrowZoneProcPtr) GrowZoneUPP |
| typedef | STACK_UPP_TYPE (PurgeProcPtr) PurgeUPP |
| typedef | REGISTER_UPP_TYPE (UserFnProcPtr) UserFnUPP |
| GrowZoneUPP | NewGrowZoneUPP (GrowZoneProcPtr userRoutine) |
| PurgeUPP | NewPurgeUPP (PurgeProcPtr userRoutine) |
| UserFnUPP | NewUserFnUPP (UserFnProcPtr userRoutine) |
| void | DisposeGrowZoneUPP (GrowZoneUPP userUPP) |
| void | DisposePurgeUPP (PurgeUPP userUPP) |
| void | DisposeUserFnUPP (UserFnUPP userUPP) |
| long | InvokeGrowZoneUPP (Size cbNeeded, GrowZoneUPP userUPP) |
| void | InvokePurgeUPP (Handle blockToPurge, PurgeUPP userUPP) |
| void | InvokeUserFnUPP (void *parameter, UserFnUPP userUPP) |
| Ptr | GetApplLimit (void) |
| THz | SystemZone (void) |
| THz | ApplicationZone (void) |
| Handle | GZSaveHnd (void) |
| Ptr | TopMem (void) |
| if (MemErr) | |
| MoreMasters () | |
| Handle | NewHandle (Size byteCount) |
| Handle | NewHandleSys (Size byteCount) |
| Handle | NewHandleClear (Size byteCount) |
| Handle | NewHandleSysClear (Size byteCount) |
| THz | HandleZone (Handle h) |
| Find which heap zone owns relocatable block. More... | |
| Handle | RecoverHandle (Ptr p) |
| Handle | RecoverHandleSys (Ptr p) |
| Ptr | NewPtr (Size byteCount) |
| Ptr | NewPtrSys (Size byteCount) |
| Ptr | NewPtrClear (Size byteCount) |
| Ptr | NewPtrSysClear (Size byteCount) |
| THz | PtrZone (Ptr p) |
| Find which heap zone owns a nonrelocatable block. More... | |
| long | MaxBlock (void) |
| Get size of largest block (without compacting) More... | |
| long | MaxBlockSys (void) |
| long | StackSpace (void) |
| Obtain amount of unused space in the stack. More... | |
| Handle | NewEmptyHandle (void) |
| Handle | NewEmptyHandleSys (void) |
| HUnlock (myHandle) | |
| In the example the FrameRect function could cause a heap so the value of | msp (a pointer to the myHandle data area) could become invalid. By surrounding the sequence with HLock and HUnlock |
| void | HUnlock (Handle h) |
| Unlock a handle's data (allowing it to be moved) More... | |
| HPurge (myHandle) | |
| Make a relocatable block purgeable. More... | |
| HNoPurge (myHandle) | |
| void | HLockHi (Handle h) |
| Handle | TempNewHandle (Size logicalSize, OSErr *resultCode) |
| Size | TempMaxMem (Size *grow) |
| long | TempFreeMem (void) |
| void | InitZone (GrowZoneUPP pgrowZone, short cmoreMasters, void *limitPtr, void *startPtr) |
| SetZone (ApplicZone()) | |
| Size | CompactMem (Size cbNeeded) |
| Size | CompactMemSys (Size cbNeeded) |
| void | PurgeMem (Size cbNeeded) |
| void | PurgeMemSys (Size cbNeeded) |
| long | FreeMem (void) |
| long | FreeMemSys (void) |
| void | ReserveMem (Size cbNeeded) |
| void | ReserveMemSys (Size cbNeeded) |
| Size | MaxMem (Size *grow) |
| Size | MaxMemSys (Size *grow) |
| Attempt to free or unlock memory but don t alter saveHandle | return (0) |
| return (1) | |
| SetZone (whateverZone) | |
| SetGrowZone (MyGrowFn) | |
| On bytesNeeded is the required amount of including the block | header (i.e., the actual amount needed).The custom function should attempt to find places where the application can economize |
| e it can call EmptyHandle to purge transient data or it can write important data to a disk | file (for later recovery) and mark the block as purgeable(see HPurge). It can also unlock(HUnlock) blocks |
| GrowZoneUPP | GetGrowZone (void) |
| void | MoveHHi (Handle h) |
| void | DisposePtr (Ptr p) |
| Size | GetPtrSize (Ptr p) |
| Obtain the size of a nonrelocatable memory block. More... | |
| void | SetPtrSize (Ptr p, Size newSize) |
| void | DisposeHandle (Handle h) |
| void | SetHandleSize (Handle h, Size newSize) |
| Size | GetHandleSize (Handle h) |
| Get the size of a Handle's data area. More... | |
| Size | InlineGetHandleSize (Handle h) |
| void | ReallocateHandle (Handle h, Size byteCount) |
| void | ReallocateHandleSys (Handle h, Size byteCount) |
| void | EmptyHandle (Handle h) |
| void | HSetRBit (Handle h) |
| Tag block for treatment as a resource. More... | |
| void | HClrRBit (Handle h) |
| Clear relocatable block's resource tag. More... | |
| SInt8 | HGetState (Handle h) |
| Obtain the value of a relocatable block's tag byte. More... | |
| void | HSetState (Handle h, SInt8 flags) |
| void | PurgeSpace (long *total, long *contig) |
| long | PurgeSpaceTotal (void) |
| long | PurgeSpaceContiguous (void) |
| long | PurgeSpaceSysTotal (void) |
| long | PurgeSpaceSysContiguous (void) |
| void | BlockMove (const void *srcPtr, void *destPtr, Size byteCount) |
| Copy memory from one place to another. More... | |
| void | BlockMoveData (const void *srcPtr, void *destPtr, Size byteCount) |
| void | BlockMoveUncached (const void *srcPtr, void *destPtr, Size byteCount) |
| void | BlockMoveDataUncached (const void *srcPtr, void *destPtr, Size byteCount) |
| void | BlockZero (void *destPtr, Size byteCount) |
| void | BlockZeroUncached (void *destPtr, Size byteCount) |
| void | MaxApplZone (void) |
| Expand application heap to largest possible value. More... | |
| void | SetApplBase (void *startPtr) |
| void | MoreMasterPointers (UInt32 inCount) |
| void | SetApplLimit (void *zoneLimit) |
| Change the size of the application heap zone. More... | |
| void | InitApplZone (void) |
| void | TempHLock (Handle h, OSErr *resultCode) |
| Lock a specified relocatable block of temporary memory. More... | |
| void | TempHUnlock (Handle h, OSErr *resultCode) |
| Unlock a block of temporary memory. More... | |
| void | TempDisposeHandle (Handle h, OSErr *resultCode) |
| TempDisposeHandle Release the memory occupied by a temporary block. More... | |
| Ptr | TempTopMem (void) |
| Get address of top of application's memory partition. More... | |
| OSErr | HoldMemory (void *address, unsigned long count) |
| Make part of the address space resident in memory. More... | |
| OSErr | UnholdMemory (void *address, unsigned long count) |
| Make part of the address space eligible for paging. More... | |
| OSErr | LockMemory (void *address, unsigned long count) |
| Make part of the address space immovable. More... | |
| OSErr | LockMemoryForOutput (void *address, unsigned long count) |
| OSErr | LockMemoryContiguous (void *address, unsigned long count) |
| LockMemoryContiguous Make a contiguous block of the address space immovable. More... | |
| OSErr | UnlockMemory (void *address, unsigned long count) |
| Make a block of the address space movable. More... | |
| OSErr | MakeMemoryResident (void *address, unsigned long count) |
| OSErr | ReleaseMemoryData (void *address, unsigned long count) |
| OSErr | MakeMemoryNonResident (void *address, unsigned long count) |
| OSErr | FlushMemory (void *address, unsigned long count) |
| OSErr | GetPhysical (LogicalToPhysicalTable *addresses, unsigned long *physicalEntryCount) |
| Translate logical addresses to physical ones. More... | |
| OSErr | GetVolumeVirtualMemoryInfo (VolumeVirtualMemoryInfoPtr volVMInfo) |
| OSErr | DeferUserFn (UserFnUPP userFunction, void *argument) |
| Can code that might cause page faults be called safely? More... | |
| long | DebuggerGetMax (void) |
| Get the highest function number supported. More... | |
| void | DebuggerEnter (void) |
| Enter the debugger state. More... | |
| void | DebuggerExit (void) |
| Exit the debugger state. More... | |
| void | DebuggerPoll (void) |
| Poll for keyboard input. More... | |
| PageState | GetPageState (const void *address) |
| Get the state of a page of logical memory. More... | |
| Boolean | PageFaultFatal (void) |
| Capture all bus errors? More... | |
| OSErr | DebuggerLockMemory (void *address, unsigned long count) |
| DebuggerLockMemory Make part of the address space immovable. More... | |
| OSErr | DebuggerUnlockMemory (void *address, unsigned long count) |
| DebuggerUnlockMemory Make part of the address space movable. More... | |
| StatusRegisterContents | EnterSupervisorMode (void) |
| EnterSupervisorMode Switch caller into supervisor mode. More... | |
| Ptr | StripAddress (void *theAddress) |
| Strip the high order byte off an address if running in 24 bit mode. More... | |
| Ptr | Translate24To32 (void *addr24) |
| Translate 24-bit addresses into the 32-bit address space. More... | |
| OSErr | HandToHand (Handle *theHndl) |
| Create new Handle and copy Handle data to it. More... | |
| OSErr | PtrToXHand (const void *srcPtr, Handle dstHndl, long size) |
| OSErr | PtrToHand (const void *srcPtr, Handle *dstHndl, long size) |
| OSErr | HandAndHand (Handle hand1, Handle hand2) |
| OSErr | PtrAndHand (const void *ptr1, Handle hand2, long size) |
| Boolean | CheckAllHeaps (void) |
| Boolean | IsHeapValid (void) |
| Boolean | IsHandleValid (Handle h) |
| Boolean | IsPointerValid (Ptr p) |
Variables | |
| ASM programs can check for return code values in the low word of the D0 register(with some exceptions).</pre > *@par Copyright | oldMoreMast = TheZone->moreMast |
| Get address of the current heap zone. More... | |
| TheZone | moreMast = numMastPtrs |
| Use SetZone to make a different zone active</pre > *par | Copyright |
| FrameRect & | r |
| Lock a handle's data area (keep it from moving) More... | |
| x = msp->myField | |
| In the example | above |
| In the example the FrameRect function could cause a heap | compaction |
| In the example the FrameRect function could cause a heap so the value of you ensure that all pointers to a handle s data area remain valid If you are certain that no heap manipulation will take | place |
| In the example the FrameRect function could cause a heap so the value of you ensure that all pointers to a handle s data area remain valid If you are certain that no heap manipulation will take or if you make an effort to adjust for | it |
| In the example the FrameRect function could cause a heap so the value of you ensure that all pointers to a handle s data area remain valid If you are certain that no heap manipulation will take or if you make an effort to adjust for you need not lock the handle For | instance |
| In the example the FrameRect function could cause a heap so the value of you ensure that all pointers to a handle s data area remain valid If you are certain that no heap manipulation will take or if you make an effort to adjust for you need not lock the handle For in the following | sequence |
| In the example the FrameRect function could cause a heap so the value of you ensure that all pointers to a handle s data area remain valid If you are certain that no heap manipulation will take or if you make an effort to adjust for you need not lock the handle For in the following the values of x and y are assigned via double | indirection |
| In the example the FrameRect function could cause a heap so the value of you ensure that all pointers to a handle s data area remain valid If you are certain that no heap manipulation will take or if you make an effort to adjust for you need not lock the handle For in the following the values of x and y are assigned via double so even if FrameRect causes the data to | move |
| In the example the FrameRect function could cause a heap so the value of you ensure that all pointers to a handle s data area remain valid If you are certain that no heap manipulation will take or if you make an effort to adjust for you need not lock the handle For in the following the values of x and y are assigned via double so even if FrameRect causes the data to it will be found by both assignment statements | myHandle = NewHandle ( sizeof(myStruct) ) |
| __pad0__ | |
| __pad1__ | |
| __pad2__ | |
| MYH_SIZE | |
| myHandle | myField = myValue |
| On | entry |
| On bytesNeeded is the required amount of | memory |
| e | g |
| e it can call EmptyHandle to purge transient data or it can write important data to a disk in the hope that this will unfragment the | heap |
| e it can call EmptyHandle to purge transient data or it can write important data to a disk in the hope that this will unfragment the thus freeing a larger block | Note |
| e it can call EmptyHandle to purge transient data or it can write important data to a disk in the hope that this will unfragment the thus freeing a larger block the grow zone root handle should not be disturbed by your function See GZSaveHnd On | exit |
| *ter *par Mac OS | X |
Memory Manager Interfaces.
For bug reports, consult the following page on the World Wide Web:
http://developer.apple.com/bugreporter/
| #define NewGrowZoneUPP | ( | userRoutine | ) |
| #define NewPurgeUPP | ( | userRoutine | ) |
| #define NewUserFnUPP | ( | userRoutine | ) |
| THz ApplicationZone | ( | void | ) |
| void BlockMove | ( | const void * | srcPtr, |
| void * | destPtr, | ||
| Size | byteCount | ||
| ) |
Copy memory from one place to another.
| srcPtr | address of data to move |
| destPtr | address to move it to BlockMove copies a block of memory from one place to another. It works correctly, even if the source and destination overlap. srcPtris the address of the beginning of the block to copy. destPtris the address at which to copy the block. byteCount specifies the length of the block to copy. As a Size data type, it should be positive and less than 8MB (a 24-bit value). |
none
This is a generalized block-move or block-copy operation that, for medium to large blocks, is much faster than writing a loop in C. Also, BlockMove can handle overlapping data areas. For instance, the following example inserts one byte into the front of a 30-byte buffer: chartheBuf[30]; BlockMove ( &theBuf[0], &theBuf[1], 29 ); theBuf[0]='A'; Several higher-level tools exist for copying specific types of data: HandToHand create handle and copy handle data to it PtrToHand create handle and copy arbitrary data to it PtrToXHand copy arbitrary data to an existing handle HandAndHand concatenate handle data to another handle PtrAndHand concatenate arbitrary data to end of handle SetString copy handle data to a pascal-style string PackBits move and compress binary data Munger insert/replace data (usually text) GetScrap copy data from the scrap to a handle
| void BlockMoveData | ( | const void * | srcPtr, |
| void * | destPtr, | ||
| Size | byteCount | ||
| ) |
| void BlockMoveDataUncached | ( | const void * | srcPtr, |
| void * | destPtr, | ||
| Size | byteCount | ||
| ) |
| void BlockMoveUncached | ( | const void * | srcPtr, |
| void * | destPtr, | ||
| Size | byteCount | ||
| ) |
| void BlockZero | ( | void * | destPtr, |
| Size | byteCount | ||
| ) |
| void BlockZeroUncached | ( | void * | destPtr, |
| Size | byteCount | ||
| ) |
| Boolean CheckAllHeaps | ( | void | ) |
| Size CompactMem | ( | Size | cbNeeded | ) |
| Size CompactMemSys | ( | Size | cbNeeded | ) |
| void DebuggerEnter | ( | void | ) |
Enter the debugger state.
The two procedures DebuggerEnter and DebuggerExit allow you to enter and exit the debugger state. These calls allow the DebugUtil trap to make preparations for subsequent debugging calls and to clean up after all debugging calls are completed.
| void DebuggerExit | ( | void | ) |
Exit the debugger state.
The two procedures DebuggerEnter and DebuggerExit allow you to enter and exit the debugger state. These calls allow the DebugUtil trap to make preparations for subsequent debugging calls and to clean up after all debugging calls are completed.
| long DebuggerGetMax | ( | void | ) |
Get the highest function number supported.
The DebuggerGetMax function returns a long integer indicating the highest function number supported by the DebugUtil trap.
The returned value is the highest selector number of the debugger functions that are defined in terms of the DebugUtil trap. See the section, Debugger Support Under Virtual Memory for a complete list of these numbers.
| OSErr DebuggerLockMemory | ( | void * | address, |
| unsigned long | count | ||
| ) |
DebuggerLockMemory Make part of the address space immovable.
The DebuggerLockMemory function performs the same operations as LockMemory , except that it leaves data caching enabled on the affected pages. address is the start address of the range that is to be locked in RAM countis the size in bytes of that range Returns: an operating system Error Code . noErr (0) No error paramErr (-50)Error in parameter list notEnoughMemoryErr (-620)Insufficient physical memory
If the starting address parameter supplied to the DebuggerLockMemory function is not on a page boundary, then it is rounded down to the nearest page boundary. Similarly, if the specified range does not end on a page boundary, the length parameter is rounded up so that the entire range of memory is locked.
| void DebuggerPoll | ( | void | ) |
Poll for keyboard input.
A debugger can use the DebuggerPoll procedure to poll for keyboard input.The DebuggerPoll procedure can be used even if interrupts are disabled.
| OSErr DebuggerUnlockMemory | ( | void * | address, |
| unsigned long | count | ||
| ) |
DebuggerUnlockMemory Make part of the address space movable.
The DebuggerUnlockMemory function reverses the effects of DebuggerLockMemory . address is the start address of the range that is to be unlocked in RAM countis the size in bytes of that range Returns: an operating system Error Code . noErr (0) No error paramErr (-50)Error in parameter list notLockedErr (-623)Specified range of memory is not locked
DebuggerUnlockMemory makes the portion of the address space starting with address and continuing for count bytes movable in physical memory and eligible for paging again. Unlocking is applied to whole pages of the virtual address space. Unlocked pages are marked as cacheable.
| OSErr DeferUserFn | ( | UserFnUPP | userFunction, |
| void * | argument | ||
| ) |
Can code that might cause page faults be called safely?
You can use the DeferUserFn function to determine whether code that might cause page faults can safely be called immediately. If the code can be called safely, then it is called. If a page fault is in progress, however, the routine address and its parameter are saved, and the routine is deferred until page faults are again permitted. userFunction is the address of the routine that you want to run argument is a pointer to the argument to pass to the specified routine. Returns: an operating system Error Code . noErr (0) No error cannotDeferErr (-625)Unable to defer additional user functions
The specified routine is called with register A0 containing the value of the argument parameter to the DeferUserFn call. Note that the routine can be called immediately (before returning to the caller of DeferUserFn ). Deferred functions must follow the register conventions used by interrupt handlers: they may use registers A0-A3 and D0-D3, and must restore all other registers used.
| void DisposeGrowZoneUPP | ( | GrowZoneUPP | userUPP | ) |
| void DisposeHandle | ( | Handle | h | ) |
| void DisposePtr | ( | Ptr | p | ) |
| void DisposePurgeUPP | ( | PurgeUPP | userUPP | ) |
| void DisposeUserFnUPP | ( | UserFnUPP | userUPP | ) |
| void EmptyHandle | ( | Handle | h | ) |
| StatusRegisterContents EnterSupervisorMode | ( | void | ) |
EnterSupervisorMode Switch caller into supervisor mode.
accomplish this with EnterSupervisorMode .
| OSErr FlushMemory | ( | void * | address, |
| unsigned long | count | ||
| ) |
| long FreeMem | ( | void | ) |
| long FreeMemSys | ( | void | ) |
| Ptr GetApplLimit | ( | void | ) |
\brief Obtain current application heap limit <pre>GetApplLimit returns the address of the end of the application heap zone.
a Ptr; the address of the end (top) of the application heap +1.
You can get this same information by reading the global variable ApplLimit (at 0x0130). You might call GetApplLimit before reducing or expanding the application zone size via SetApplLimit .
| GrowZoneUPP GetGrowZone | ( | void | ) |
| Size GetHandleSize | ( | Handle | h | ) |
Get the size of a Handle's data area.
NOTE
GetHandleSize and GetPtrSize are documented in Inside Mac as returning 0 in case of an error, but the traps actually return an error code in D0. The glue sets D0 to 0 if an error occurred.
GetHandleSize returns the size, in bytes of a relocatable block of memory. theHandle is a Handle, leading to a relocatable block of memory.
the size of the data led to by a Handle (a 32-bit long), 0 may indicate an error occurred. The MemError function may return an Error Code of: noErr(0) No error nilHandleErr (-109) Illegal operation on empty handle memWZErr (-111) Illegal operation on a free block
You can use GetHandleSize to determine the size of objects (such as pictures) that may exceed the 64K or 32K maximum value of their historically-defined size. The returned value is the size of the allocated area available for data storage. The actual memory used by a Handle includes a block header and up to 12 bytes of filler.
| PageState GetPageState | ( | const void * | address | ) |
Get the state of a page of logical memory.
The GetPageState function returns the state of a page of logical memory. address specifies an address in the page whose state you want to determine. Returns: a constant: kPageInMemory //page is in RAM kPageOnDisk //page is on disk kNotPaged //address is not paged
| OSErr GetPhysical | ( | LogicalToPhysicalTable * | addresses, |
| unsigned long * | physicalEntryCount | ||
| ) |
Translate logical addresses to physical ones.
The GetPhysical function translates logical addresses into their corresponding physical addresses. addresses is a translation table, that is, an array of ordered pairs (address and count). physicalEntryCount specifies the number of physical entries to translate. Returns: an operating system Error Code . noErr (0) No error paramErr (-50) Error in parameter list notLockedErr (-623) Specified range of memory is not locked interruptsMaskedErr (-624) Called with interrupts masked
GetPhysical translates up to the size of the table or until the translation is completed, whichever comes first. If GetPhysical is called with a table size of 0, the number of table entries needed to translate the entire address range is returned. On exit from this function, the virtual information is updated to indicate the next virtual address and the number of bytes left to translate. The logical address range must be locked to ensure validity of the translation data.
| Size GetPtrSize | ( | Ptr | p | ) |
Obtain the size of a nonrelocatable memory block.
| thePtr | address of a nonrelocatable memory block GetPtrSize returns the size, in bytes of a specified nonrelocatable memory block. thePtris the address of a nonrelocatable memory block; i.e., the value obtained from a prior call to NewPtr . |
a 32-bit long; the current size of the memory block. This will always be less than 8MB (a 24-bit value).
| OSErr GetVolumeVirtualMemoryInfo | ( | VolumeVirtualMemoryInfoPtr | volVMInfo | ) |
| Handle GZSaveHnd | ( | void | ) |
\brief Get handle to data to not move during zone growth <pre>root" should NOT be moved. GZSaveHnd returns a handle leading to that data.
a generic Handle; it leads to data that should not be moved, unlocked, purged, etc.
GZSaveHnd should be used by applications that have a custom heap-zone grow function (see SetGrowZone ). That function should take care to avoid moving, unlocking, or purging the data led to by the returned handle. The global variable GZRootHnd (at 0x0328) contains this handle.
| OSErr HandAndHand | ( | Handle | hand1, |
| Handle | hand2 | ||
| ) |
| THz HandleZone | ( | Handle | h | ) |
Find which heap zone owns relocatable block.
HandleZone returns the address of the Zone structure at the base of the heap zone that owns a specified relocatable memory block. theHandle is a handle leading to a relocatable memory block; e.g., a value obtained via NewHandle .
the address of a Zone structure. It identifies the heap zone that contains the relocatable block addressed by theHandle . Use MemError to see if this return value is meaningful; it will return an Error Code of: noErr(0) No error memWZErr (-111) Illegal operation on a free block
If theHandle is an empty handle (i.e., it points to a NIL master pointer), then HandleZone will return a pointer to the current heap zone.
| OSErr HandToHand | ( | Handle * | theHndl | ) |
Create new Handle and copy Handle data to it.
HandToHand creates a new Handle (see NewHandle ) and copies data from an existing Handle into the new one. theHandle is the address of an existing Handle. On entry, it is a Handle leading to data you wish to copy. On return, it is overwritten by a newly-created Handle that leads to a relocatable block containing a copy of the data.
an OSErr; an integer Error Code . It will be one of: noErr(0) No error memFullErr (-108) Not enough room in heap for new Handle nilHandleErr (-109) theHandle was invalid on entry memWZErr (-111) Attempt to operate on a free block
Since HandToHand cleverly overwrites the original value of theHandle ,
the normal technique is to make a copy of the original before the call; e.g:
HandlesrcHandle, destHandle;
srcHandle= GetResource ( 'CURS', watchCursor );
destHandle = srcHandle;
if ( HandToHand ( &destHandle ) ) {
. . . an error occurred . . .
}. . . else, a copy of watchCursor is now in destHandle . . .
| void HClrRBit | ( | Handle | h | ) |
Clear relocatable block's resource tag.
HClrRBit clears bit 7 of the tag byte of a master pointer. This is normally used internally by the Resource Manager, to indicate that the block should not receive special treatment as a resource. theHandle is a handle leading to a relocatable memory block.
none; the MemError function may return one of: noErr(0) No error nilHandleErr (-109) theHandle has a NIL master pointer memWZErr (-111) Illegal operation on a free block
Rather than manipulating the high byte (the tag byte) of a master pointer, it is wise to use Memory Manager functions such as HLock and HPurge . If you need to manipulate the tag byte, you should use HGetState and HSetState to save and restore the original tag values.
| SInt8 HGetState | ( | Handle | h | ) |
Obtain the value of a relocatable block's tag byte.
HGetState lets you examine or save the current value of a relocatable block's master pointer tag byte. It includes the lock, purge, and resource attributes of the block. theHandle is a handle leading to a relocatable memory block.
a byte; the current tag settings for theHandle (as with all C char return values, this is actually a 16-bit value, with the low 8 bits significant). See HSetState for the bit layouts. The MemError function may return an Error Code of: noErr(0) No error nilHandleErr (-109) theHandle has a NIL master pointer memWZErr (-111) Illegal operation on a free block
Rather than manipulating the high byte (the tag byte) of a master pointer, it is wise to use Memory Manager functions such as HLock and HPurge .
| void HLockHi | ( | Handle | h | ) |
| OSErr HoldMemory | ( | void * | address, |
| unsigned long | count | ||
| ) |
Make part of the address space resident in memory.
The HoldMemory function makes a portion of the address space resident in physical memory and ineligible for paging. address is the start address of the range of memory that is to be held in RAM count is the size in bytes of that range. Returns: an operating system Error Code . noErr(0)No error paramErr (-50)Error in parameter list notEnoughMemoryErr (-620)Insufficient physical memory interruptsMaskedErr (-624)Called with interrupts masked
If the starting address parameter supplied to the HoldMemory function is not on a page boundary, then it is rounded down to the nearest page boundary. Similarly, if the specified range does not end on a page boundary, the count parameter is rounded up so that the entire range of memory is held.
| HPurge | ( | myHandle | ) |
Make a relocatable block purgeable.
HPurge sets the purge attribute of a relocatable memory block so that in a subsequent heap compaction, its data can be purged. theHandle is a handle leading to a relocatable memory block. It is typically a value obtained from NewHandle .
none; the MemError function may return an Error Code of: noErr(0) No error nilHandleErr (-109) Illegal operation on an empty handle memWZErr (-111) Illegal operation on a free block
If theHandle is currently locked (see HLock), it will remain locked and HPurge will have no effect until the handle is unlocked via HUnlock . Thereafter, theHandle will purged by the next general purge. After a purge, all handles marked as purgeable will point to NIL master pointers and their data area will be lost. Be very careful to check for such empty handles before accessing the data, e.g.: HandlemyHandle; myHandle = NewHandle ( 1000 ); /* allocate space
| void HSetRBit | ( | Handle | h | ) |
Tag block for treatment as a resource.
HSetRBit sets bit 7 of the tag byte of a master pointer. This is normally used internally by the Resource Manager, to mark the block for special treatment as a resource. theHandle is a handle leading to a relocatable memory block.
none; the MemError function may return an Error Code of: noErr(0) No error nilHandleErr (-109) theHandle has a NIL master pointer memWZErr (-111) Illegal operation on a free block
Rather than manipulating the high byte (the tag byte) of a master pointer, it is wise to use Memory Manager functions such as HLock and HPurge . Failure to use these routines virtually guarantees incompatibilities with future System Software. If you need to manipulate the tag byte, you should use HGetState and HSetState to save and restore the original tag values.
| void HSetState | ( | Handle | h, |
| SInt8 | flags | ||
| ) |
| void HUnlock | ( | Handle | h | ) |
Unlock a handle's data (allowing it to be moved)
HUnlock undoes the effect of HLock. It removes the relocation lock on a handle. In the event of a memory crunch, the Memory Manager will be able to move the handle's data to make room for other allocation blocks. theHandle is a handle leading to a relocatable memory block. It is typically a value obtained from NewHandle .
none; the MemError function may return an Error Code of: noErr(0) No error nilHandleErr (-109) Illegal operation on an empty handle memWZErr (-111) Illegal operation on a free block
To avoid heap fragmentation (i.e., to keep as much of the heap available as possible), use HUnlock as soon as possible after locking it via HLock. If you expect the handle to be locked for a long time, use MoveHHi to place it at the top of the heap, or use ResrvMem before allocating the handle to place it near the bottom of the heap. If the block is already unlocked (its default state upon allocation), HUnlock does nothing.
| if | ( | MemErr | ) |
\brief Return error code of last Memory Manager function <pre>MemError returns the OSErr code of the most recent call to a Memory
Manager function.
an OSErr (a.k.a. short). Common Error/Return Code returns: noErr(0) No error memFullErr (-108) No room in heap nilHandleErr (-109) Illegal operation on a NIL handle memWZErr (-111) Illegal operation on a free block memPurErr (-112) Illegal operation on a locked block memLockedErr (-117) Can't move a locked block
Before returning to an application, the Memory Manager stores an
error/return code into a global variable. If you call MemError , you get a
copy of that value. Note that this value is affected only by calls made
directly by the application (and not errors made indirectly; e.g. via a
toolbox function that calls the Memory Manager indirectly).
C programmers may access the global variable MemErr (at 0x0220)
directly. For instance:
HPurge ( myHandle );
if ( MemError () ) { . . . process the error . . . }
/* faster alternative . . .
| void InitApplZone | ( | void | ) |
| void InitZone | ( | GrowZoneUPP | pgrowZone, |
| short | cmoreMasters, | ||
| void * | limitPtr, | ||
| void * | startPtr | ||
| ) |
| Size InlineGetHandleSize | ( | Handle | h | ) |
| long InvokeGrowZoneUPP | ( | Size | cbNeeded, |
| GrowZoneUPP | userUPP | ||
| ) |
| void InvokePurgeUPP | ( | Handle | blockToPurge, |
| PurgeUPP | userUPP | ||
| ) |
| void InvokeUserFnUPP | ( | void * | parameter, |
| UserFnUPP | userUPP | ||
| ) |
| Boolean IsHandleValid | ( | Handle | h | ) |
| Boolean IsHeapValid | ( | void | ) |
| Boolean IsPointerValid | ( | Ptr | p | ) |
| OSErr LockMemory | ( | void * | address, |
| unsigned long | count | ||
| ) |
Make part of the address space immovable.
The LockMemory function makes a portion of the address space immovable in physical memory and ineligible for paging. address is the start address of the range that is to be locked in RAM count is the size in bytes of that range. Returns: an operating system Error Code . noErr(0)No error paramErr (-50)Error in parameter list notEnoughMemoryErr (-620)Insufficient physical memory interruptsMaskedErr (-624)Called with interrupts masked
If the starting address parameter supplied to the LockMemory function is not on a page boundary, then it is rounded down to the nearest page boundary. Similarly, if the specified range does not end on a page boundary, the count parameter is rounded up so that the entire range of memory is locked. Locked pages are marked noncacheable by the CPU.
| OSErr LockMemoryContiguous | ( | void * | address, |
| unsigned long | count | ||
| ) |
LockMemoryContiguous Make a contiguous block of the address space immovable.
The LockMemoryContiguous function is exactly like the LockMemory function, except that it attempts to obtain a contiguous block of physical memory associated with the logical address range specified. address is the start address of the range that is to be locked in RAM count is the size in bytes of that range. Returns: an operating system Error Code . noErr (0) No error paramErr (-50) Error in parameter list notEnoughMemoryErr (-620) Insufficient physical memory cannotMakeContiguousErr (-622) Cannot make specified range contiguous interruptsMaskedErr (-624) Called with interrupts masked
If the starting address parameter supplied to the LockMemoryContiguous function is not on a page boundary, then it is rounded down to the nearest page boundary. Similarly, if the specified range does not end on a page boundary, the count parameter is rounded up so that the entire range of memory is locked. Locked pages are marked noncacheable by the CPU.
| OSErr LockMemoryForOutput | ( | void * | address, |
| unsigned long | count | ||
| ) |
| OSErr MakeMemoryNonResident | ( | void * | address, |
| unsigned long | count | ||
| ) |
| OSErr MakeMemoryResident | ( | void * | address, |
| unsigned long | count | ||
| ) |
| void MaxApplZone | ( | void | ) |
Expand application heap to largest possible value.
MaxApplZone expands the application heap zone to include all available heap memory. It does not purge any current blocks in the application heap.
none
MaxApplZone is commonly called early in the application, followed by a call to MoreMasters (if necessary). If you are using multiple heap zones, be sure to call InitZone to create these zones before calling MaxApplZone .
| long MaxBlock | ( | void | ) |
Get size of largest block (without compacting)
MaxBlock returns the size of the largest block that would be available if heap compaction were to be performed, but does not actually perform the time-consuming compaction.
a long integer; the size of largest block available after compaction.
There is another routine, MaxBlockSys , which performs the equivalent operation to MaxBlock , but in the System heap zone. It takes the same parameters as MaxBlock . This works a little like CompactMem , except that it does not actually force heap compaction (compaction will be performed, if needed, when the handle gets allocated anyway). Use this before attempting an operation that will require allocation of large blocks of memory. Note that a block larger than returned may be available; i.e., if a memory purge takes place. If MaxBlock does not yield a large enough value, you could try PurgeMem , (another fast operation), followed by MaxBlock and check the result.
| long MaxBlockSys | ( | void | ) |
| Size MaxMem | ( | Size * | grow | ) |
| Size MaxMemSys | ( | Size * | grow | ) |
| void MoreMasterPointers | ( | UInt32 | inCount | ) |
| void MoreMasters | ( | void | ) |
| void MoveHHi | ( | Handle | h | ) |
| Handle NewEmptyHandle | ( | void | ) |
| Handle NewEmptyHandleSys | ( | void | ) |
| GrowZoneUPP NewGrowZoneUPP | ( | GrowZoneProcPtr | userRoutine | ) |
| Handle NewHandle | ( | Size | byteCount | ) |
| Handle NewHandleClear | ( | Size | byteCount | ) |
| Handle NewHandleSys | ( | Size | byteCount | ) |
| Handle NewHandleSysClear | ( | Size | byteCount | ) |
| Ptr NewPtr | ( | Size | byteCount | ) |
| Ptr NewPtrClear | ( | Size | byteCount | ) |
| Ptr NewPtrSys | ( | Size | byteCount | ) |
| Ptr NewPtrSysClear | ( | Size | byteCount | ) |
| PurgeUPP NewPurgeUPP | ( | PurgeProcPtr | userRoutine | ) |
| UserFnUPP NewUserFnUPP | ( | UserFnProcPtr | userRoutine | ) |
| Boolean PageFaultFatal | ( | void | ) |
Capture all bus errors?
A debugger can use the PageFaultFatal function to determine whether it should capture all bus errors or whether it is safe to allow them to flow through to virtual memory. When paging is safe, the debugger can allow virtual memory to continue to service page faults, thus allowing the user to view all of memory.
If this function returns TRUE, then the debugger should not allow the virtual memory's bus error handler to detect any page faults.
| OSErr PtrAndHand | ( | const void * | ptr1, |
| Handle | hand2, | ||
| long | size | ||
| ) |
| OSErr PtrToHand | ( | const void * | srcPtr, |
| Handle * | dstHndl, | ||
| long | size | ||
| ) |
| OSErr PtrToXHand | ( | const void * | srcPtr, |
| Handle | dstHndl, | ||
| long | size | ||
| ) |
| THz PtrZone | ( | Ptr | p | ) |
Find which heap zone owns a nonrelocatable block.
| thePtr | address of a nonrelocatable memory block Given the address of a nonrelocatable memory block, PtrZone tells you in which heap zone that block resides. thePtris the address of a nonrelocatable memory block; i.e., the value obtained from a prior call to NewPtr . |
the address of a Zone structure. It identifies the heap zone that contains the relocatable block addressed by thePtr. Use MemError to see if this return value is meaningful; it will return an Error Code of: noErr(0) No error memWZErr (-111) Illegal operation on a free block
| void PurgeMem | ( | Size | cbNeeded | ) |
| void PurgeMemSys | ( | Size | cbNeeded | ) |
| void PurgeSpace | ( | long * | total, |
| long * | contig | ||
| ) |
| long PurgeSpaceContiguous | ( | void | ) |
| long PurgeSpaceSysContiguous | ( | void | ) |
| long PurgeSpaceSysTotal | ( | void | ) |
| long PurgeSpaceTotal | ( | void | ) |
PurgeSpaceTotal and PurgeSpaceContiguous are currently only implement on classic 68K. The are the same as PurgeSpace() but return just one value (either total space purgable or contiguous space purgable). Begining in Mac OS 8.5 they are available in InterfaceLib. PurgeSpaceTotal()
| void ReallocateHandle | ( | Handle | h, |
| Size | byteCount | ||
| ) |
| void ReallocateHandleSys | ( | Handle | h, |
| Size | byteCount | ||
| ) |
| Handle RecoverHandle | ( | Ptr | p | ) |
| Handle RecoverHandleSys | ( | Ptr | p | ) |
| OSErr ReleaseMemoryData | ( | void * | address, |
| unsigned long | count | ||
| ) |
| void ReserveMem | ( | Size | cbNeeded | ) |
| void ReserveMemSys | ( | Size | cbNeeded | ) |
| Attempt to free or unlock memory but don t alter saveHandle return | ( | 0 | ) |
\brief Install custom heap zone growing procedure
<pre>SetGrowZone installs a custom procedure that will be called after
exhausting all other avenues available for obtaining a requested block of memory. This affects the current heap zone. growProc is the address of a Pascal-style function in the format described below. It can be as simple as displaying a message indicating "out of memory" or complex, as in swapping data to disk and releasing memory.
none
This function does NOT set the grow zone - it sets the address of a function
into Zone.gzProc of the current heap zone.
The custom grow procedure should expect a Size (a.k.a. long) type
parameter on entry and should return a 32-bit long. It should be in the
following format:
pascal long MyGrowFn( Size bytesNeeded )
{
HandlesaveHandle;
saveHandle = GZSaveHnd ( ); /* always call this
| void SetApplBase | ( | void * | startPtr | ) |
| void SetApplLimit | ( | void * | zoneLimit | ) |
Change the size of the application heap zone.
SetApplLimit sets the size of the application heap by selecting the address beyond which it may not expand. limitPtr is an address. It specifies an address one byte beyond the desired end of the application heap zone. If the heap has already grown beyond this limit, the current size is used instead.
none; the MemError function may return an Error Code of: noErr(0) No error memFullErr (-108) Can't expand that far
SetApplLimit expands/contracts only the application heap zone (not any additional zones created via InitZone ). The new limit is stored in the global variable ApplLimit (at 0x0130). You might call GetApplLimit before making this call, then add a specified amount to the return value. e.g., to increase the current size by 16K, use: SetApplLimit ( GetApplLimit () - 16384 ); Note that you need to subtract (not add) to increase the size of the stack. A more common operation is to call MaxApplZone early in your program to provide the largest possible size for the application heap.
| void SetHandleSize | ( | Handle | h, |
| Size | newSize | ||
| ) |
| void SetPtrSize | ( | Ptr | p, |
| Size | newSize | ||
| ) |
| long StackSpace | ( | void | ) |
Obtain amount of unused space in the stack.
StackSpace checks how close your application is to peril. It can also be used before creating a heap zone in the stack (to squeeze a few extra bytes out of the system). The return value is transient - the stack can grow a lot very quickly.
a long integer; the amount of space between the base of the stack and the current value of the stack pointer.
One trick for getting some additional memory is to carve a zone out of the bottom of the stack (at a place where the stack is not being used). The default stack is about 8K, and it is best to leave at least 4K to 6K there. So at most you can create about a 2K heap zone. Of course you should use StackSpace beforehand, to check if this is a feasible approach. One instance where you might need a temporary zone is in a routine to handle a serious memory-full crunch. For instance, creating an alert or dialog window takes some heap space. See InitZone for details of creating a zone. The global variables CurStackBase (at 0x0908) and MemTop (at 0x0108) may be of some help.
| Ptr StripAddress | ( | void * | theAddress | ) |
Strip the high order byte off an address if running in 24 bit mode.
StripAddress will clear the high order byte of an address if the machine is running in 24 bit mode. This action is identical in function to the global variable Lo3Bytes . However, if the machine is running in 32 bit mode, the address is returned unchanged. addressthe address to be stripped.
the new, stripped address.
| THz SystemZone | ( | void | ) |
\brief Get address of the start of the system heap zone <pre>SystemZone returns the address of the start of the Zone structure of the
system heap. This is the same as the value stored in the global variable SysZone (at 0x02A6).
a pointer to a Zone structure; the address of the start of the system heap zone.
| void TempDisposeHandle | ( | Handle | h, |
| OSErr * | resultCode | ||
| ) |
TempDisposeHandle Release the memory occupied by a temporary block.
You can use TempDisposeHandle to release the memory occupied by a relocatable temporary memory block. The resultCode parameter will return one of the following error codes: noErr(0)No error memWZErr (-111)Attempt to operate on a free block
In system 7.0, you can use the Memory Manager routine DisposHandle to free temporary memory blocks.
| long TempFreeMem | ( | void | ) |
\brief Find out how much temporary memory is available
<pre>The TempFreeMem function returns the state of a page of logical memory.
Returns: the total amount of free memory available for temporary allocation using TempNewHandle . The returned value is a long integer that indicates the total number of bytes free.
| void TempHLock | ( | Handle | h, |
| OSErr * | resultCode | ||
| ) |
Lock a specified relocatable block of temporary memory.
You can use TempHLock to lock a specified relocatable block of temporary memory, thereby preventing it from being moved within the heap zone. The resultCode parameter will return one of the following error codes: noErr(0)No error nilHandleErr (-109)Nil master pointer memWZErr (-111)Attempt to operate on a free block
In system 7.0, you can use the Memory Manager routine HLock to lock temporary memory blocks.
| void TempHUnlock | ( | Handle | h, |
| OSErr * | resultCode | ||
| ) |
Unlock a block of temporary memory.
You can use TempHUnlock to unlock a block of temporary memory. Once it is unlocked, that block is allowed to move memory locations as needed to compact the heap. The resultCode parameter will return one of the following error codes: noErr(0)No error nilHandleErr (-109)Nil master pointer memWZErr (-111)Attempt to operate on a free block
Under system 7.0, you can use the Memory Manager routine HUnlock to unlock temporary memory blocks.
| Size TempMaxMem | ( | Size * | grow | ) |
\brief Find the largest contiguous block available
<pre>TempMaxMem compacts the heap zone and returns the size of the largest
contiguous block available for temporary allocation. growalways contains 0 after the function call because the temporary memory does not come from the application's heap.
| Handle TempNewHandle | ( | Size | logicalSize, |
| OSErr * | resultCode | ||
| ) |
\brief Allocate a new relocatable block of temporary memory
<pre>You use TempNewHandle to allocate a new relocatable block of temporary
memory. TempNewHandle returns a handle to a block of size Size. The first parameter indicates how many bytes you wish the block to contain. The second parameter contains the result code from the function call. The resultCode parameter will return one of the following error codes: noErr(0)No error memFullErr (-108)Not enough memory
| Ptr TempTopMem | ( | void | ) |
Get address of top of application's memory partition.
TempTopMem returns a pointer to the top of your application's memory partition. Don't use this call to calculate the size of your application's memory partition.
pointer to top of application memory.
| Ptr TopMem | ( | void | ) |
\brief Get address of end of RAM <pre>TopMem returns a pointer to the first byte beyond the end of physical RAM,
or to the end of memory available for applications.
a Ptr; the highest RAM address accessible.
The global variable MemTop (at 0x0108) carries this same information. The Environs and SysEnvirons functions provide a lot of information about the equipment you are running. Other Memory Manager global variables include: MemTop 0x108 Address of end of RAM BufPtr 0x10C Address of end of jump table HeapEnd 0x114 Address of end of application heap zone TheZone 0x118 Address of current heap zone ApplLimit 0x130 Application heap limit SysZone 0x2A6 Address of system heap zone ApplZone 0x2AA Address of application heap zone ROMBase 0x2AE Address of start of ROM RAMBase 0x2B2 Trap dispatch base for RAM routines ScrnBase 0x824 Address of main screen buffer CurrentA5 0x904 Start of application globals CurStackBase 0x908 Address of the base of the stack
| Ptr Translate24To32 | ( | void * | addr24 | ) |
Translate 24-bit addresses into the 32-bit address space.
You can use the Translate24To32 function to translate 24-bit addresses into the 32-bit address space. Unlike the StripAddress function, this function does not necessarily return an address that is meaningful to the 24-bit Memory Manager . addr24the address to be translated.
the new, translated address.
| OSErr UnholdMemory | ( | void * | address, |
| unsigned long | count | ||
| ) |
Make part of the address space eligible for paging.
The UnholdMemory function makes eligible for paging again a portion of the address space that is currently held. This function reverses the effects of HoldMemory . address is the start address of the range of memory that is to be let go. count is the size in bytes of that range. Returns: an operating system Error Code . noErr(0)No error paramErr (-50)Error in parameter list notHeldErr (-621)Specified range of memory is not held interruptsMaskedErr (-624)Called with interrupts masked
If the starting address parameter supplied to the UnholdMemory function is not on a page boundary, then it is rounded down to the nearest page boundary. Similarly, if the specified range does not end on a page boundary, the count parameter is rounded up so that the entire range of memory is let go.
| OSErr UnlockMemory | ( | void * | address, |
| unsigned long | count | ||
| ) |
Make a block of the address space movable.
The UnlockMemory function makes a portion of the address space movable in real memory and eligible for paging again. It undoes the effects of both LockMemory and LockMemoryContiguous . address is the start address of the range that is to be unlocked count is the size in bytes of that range. Returns: an operating system Error Code . noErr (0) No error paramErr (-50) Error in parameter list notLockedErr (-623) Specified range of memory is not locked interruptsMaskedErr (-624) Called with interrupts masked
If the specified address is not on a page boundary, it is rounded down to the nearest page boundary. Similarly, if the specified range does not end on a page boundary, the length parameter is rounded up so that the entire range of memory is unlocked..
| __pad2__ |
\brief Disallow purging of relocatable data block
<pre>HNoPurge tags a handle as unpurgeable. If the handle is already unpurgeable
(the default for newly-allocated handles), this function has no effect. theHandle is a handle leading to a relocatable memory block. It is typically a value obtained from NewHandle .
none; the MemError function may return and Error Code of: noErr(0) No error nilHandleErr (-109) Illegal operation on an empty handle memWZErr (-111) Illegal operation on a free block
Use HNoPurge to reverse the effect of a previous call to HPurge . Take care to check that theHandle has not already been purged before calling this function, e.g.: HPurge ( myHandle ); /* allow purge
| myHandle = NewHandle ( sizeof(myStruct) ) |
\brief Select a heap zone as the "current zone"
<pre>SetZone activates (makes current) a desired heap zone. Most Memory
Manager functions operate on the current heap zone. heapZone is the address of a 64-byte Zone structure. It is either the application zone (global variable ApplZone at 0x02AA), the system heap (global variable SysZone at 0x02A6) or a value used as the startPtr parameter in a previous call to InitZone .
none (call MemError to check for an error)
As an expedient alternative to SetZone , you can simply store a THz (pointer to a Zone structure) in the global variable TheZone (at 0x0118). SetZone is needed by applications that maintain multiple heap zones, or in the rare case where you may want to allocate an object in the system heap. You may use SystemZone , or ApplicZone (or access the global variables SysZone or ApplZone ) to obtain a valid value for heapZone . You can use HandleZone or PtrZone to learn which zone owns a particular handle or pointer. For instance, to allocate some data in the system heap (which is guaranteed to be there on a subsequent invocation of your application), you might use the following sequence: SetZone ( SystemZone () ); /*make system heap current
| ASM programs can check for return code values in the low word of the D0 register (with some exceptions). </pre> * @par Copyright oldMoreMast = TheZone->moreMast |
Get address of the current heap zone.
GetZone returns the address of the start of the current heap zone.
a 4-byte pointer; the address of a 62-byte Zone record for that current active heap zone.
Another method is to access the global variable TheZone (at 0x0118). For instance, to change the number of master pointers to be allocated via MoreMasters (i.e., modify a field of the current Zone structure), you could use: void MyMoreMasters( numMastPtrs ) short numMastPtrs; { shortoldMoreMast; /* saved value of moreMast
| FrameRect& r |
Lock a handle's data area (keep it from moving)
HLock sets the lock attribute of a relocatable block, preventing it from being moved during heap compaction. You should lock a handle before you dereference it in order to access its data. theHandle is a handle leading to a relocatable allocation block. It is typically a value obtained via NewHandle .
none; the MemError function may return one of: noErr(0) No error nilHandleErr (-109) Illegal operation on an empty handle memWZErr (-111) Illegal operation on a free block
Many Toolbox functions end up compacting the heap, causing data to be moved around. See About the Moves Memory Icon for more on determining when memory may move. By default, new handles are not locked and must be explicitly locked if you must prevent the data from being moved. Thus, before accessing a handle's data area, be sure to lock the handle; e.g.: HandlemyHandle; structmyStruct msp; short x; Rect r; myHandle = NewHandle ( sizeof(myStruct) ); HLock( myHandle ); msp = *myHandle; / msp points to the data, but...
1.9.1