This Technote discusses known errors and omissions in Inside Macintosh: Memory.

[Aug 01 1998]

This note should be added to the introduction:

The intent of Inside Macintosh:Memory is to cover all Macintosh models existing or foreseeable at time of print, except for a few early models with the 64K ROMs, which are no longer supported:

• The original Macintosh (64KB ROM, 128KB, or 512KB RAM)
• Macintosh XL (Lisa hardware emulating an original Macintosh)

Inside Macintosh:Memory does apply to the Macintosh 512K enhanced (featuring the same 128K ROM as the Macintosh Plus) and all Macintoshes at time of print, including Performa, PowerBook, Power Macintosh, and Mac OS-compatible PowerPC machines.

This is a bad example. A better example is MemError vs. MemErr.

The paragraph on page 1-6 should read:

In general, it is best to avoid reading or writing low-memory system global variables. Most of these variables are undocumented, and the results of changing their values can be unpredictable. Usually, when the value of a low-memory global variable is likely to be useful to applications, the system software provides a routine that you can use to read or write that value. For example, you can get the current value of the MemErr global variable by calling the MemError function.

The paragraph on page 2-7 should read:

Even when Inside Macintosh does document a particular system global variable, you should use any available routines to access that variable's value instead of examining it directly. For example, you should use the MemError function to find the last error returned by the Memory Manager instead of examining the MemErr global variable directly.

The description of Figure 1-7 is incorrect. The paragraph immediately following Figure 1-7 should read: "In Figure 1-7, Application 2 has almost exhausted its application heap. As a result, it has requested and received a large block of temporary memory. Application 2 can use the temporary memory in whatever manner it desires."

The documentation states that by default the stack can grow to "32KB on computers with Color QuickDraw" (page 1-40). The actual default stack size on machines with Color QuickDraw is 24KB. In addition, the default stack size for a background-only application (or a "faceless background process") is 2KB, not 8KB as claimed on page 1-40.

However, the default stack size may change in the future and should never be assumed.

The description of the SetApplLimit routine should mention that SetApplLimit enforces a minimum stack size equal to DefltStack. For example, calling SetApplLimit on a background-only application running on a Color QuickDraw machine will result in a minimum stack size of 24KB, regardless of the value passed to SetApplLimit. The partition of the background-only application must be large enough to accommodate a stack of that size.

The application-defined function NewPtrCushion (defined in Listing 1-7) should return a value of type Ptr, not of type Handle.

The Assembly-Language Information for the NewPtr function states that on entry register A0 contains the number of logical bytes requested. In fact, register D0 should contain the number of logical bytes requested.

There is a problem introduced with MultiFinder. It is well documented in Technote ME14-The New Memory Manager and You, under A5 World Problems and Heap Callback Procedures (but the workaround suggested in this technote is unusable).

The problem: when a heap is low on memory or a Handle is going the be purged, the GrowZone or PurgeProc function is called without an A5 world switch. This means that the GrowZone or PurgeProc function is called with CurrentA5 set, according to the A5 world of the application that did the call generating the low-memory or Handle purge condition, rather than the value of A5 for which the application the GrowZone or PurgeProc function belongs. As the Technote says, this "[will] cause all hell to break loose". This may occur, for example, when the active and frontmost application closes a window. The update region of windows belonging to other applications need to be updated, which often involves extending the update region Handle, which can cause a GrowZone procedure to be called, but since the window being updated is in the background, the value of A5 is wrong with respect to the GrowZone or PurgeProc function.

The safe workaround, which is needed only in 680x0 code, involves saving A5 explicitly, and recovering it using PC-relative addressing. Going forward to Mac OS X and Carbon, GrowZone and PurgeProc functions will not be needed, so this problem will gradually go away.

[...] you must never lock temporary memory across calls to GetNextEvent or WaitNextEvent [...]

[...] you should avoid locking temporary memory across calls to GetNextEvent or WaitNextEvent [...]

TempMemCallsAvailable := BAND(myRsp, gestaltTempMemSupport) <> 0;

TempMemCallsAvailable := BTst(myRsp, gestaltTempMemSupport);

The documentation implies (page 2-13) that system extensions running under System 7.0 and later do not need to have 'sysz' resources to indicate their system heap memory requirements. This statement is misleading. 'sysz' resources are effective on all versions of system software.

Furthermore, the generic term "system extension" is ambiguous in this context. Many items in the Extensions folder, such as components and native drivers ('ndrv's), are labeled as "system extensions" by the Finder. However, 'sysz' resources are only applicable to files that may contain 'INIT' resources. This includes control panels, system extensions of file type 'INIT', and application extensions with an 'INIT' resource. [Radar ID 1245268]

Before executing an 'INIT' resource from a file, the Start Manager first checks to see whether the system heap has X bytes of free space, where X is the maximum of 16KB or the value in the file's 'sysz' resource. If less than X bytes of free space is available, the Start Manager grows the system heap such that X bytes are available for the 'INIT's use.

Note that in System 7.0 and later, the system heap can grow after the startup process has completed. The 'sysz' resource only controls the system heap expansion at startup time.

The documentation states that "on computers containing the MC68020, MC68030, or MC68040 microprocessors, blocks are padded to 4-byte boundaries." This is incorrect for 68040 and PowerPC machines, where blocks are always aligned on 16-byte boundaries.

Starting with Mac OS 7.5, all memory blocks, regardless of the runtime CPU, are aligned to 16-byte boundaries.

Figures 2-1 (page 2-22) and 2-2 (page 2-23) might be misleading. Remember that Inside Macintosh typically draws memory diagrams with the low-memory addresses nearest to the bottom of the diagram. (Compare Figure 1-1 on page 1-5, where the low-memory end of the diagram is explicitly labeled.) The long word containing the block type and size correction is the first long word in the 24-bit zone header. Similarly, the long word containing the block type and unused space is the first long word in the 32-bit zone header.

Figure 2-2 (page 2-23) claims that a block type of "11" signifies a relocatable block. This is incorrect. The correct type indicator for a relocatable block is "10".

The dstHndl parameter is not an input parameter; therefore, the statement "The dstHndl parameter must be a handle variable that is not empty and is not a handle to an allocated block of size 0" is misleading in that it implies that you may have to allocate the handle yourself. This is not the case. PtrToHand will allocate a handle of the requested size and return it to you in the dstHndl parameter. If no error occurs, on exit dstHndl is an unlocked, non-purgeable Handle of the requested size, allocated from the current heap zone.

The statement:

"The new relocatable block is created in the same heap zone as the original block (which might not be the current heap zone)."

is incorrect.

The correct description is that the new relocatable block is created in the current heap zone, regardless of the zone of the original relocatable block. During HandToHand, the original Handle is made non-purgeable while the new one is allocated. The original Handle is then returned to its original state. It is safe to call HandToHand on purgeable handles, but not on a purged handle.

The warning is no longer needed and only applied to Macs which use the original 64K ROMs.

It is safe to call HandAndHand on purgeable handles, but not on handles that have been purged.

The description for A1's value should read "Handle to relocatable block to which the data will be appended."

size, the "Number of bytes to append", is passed in D0, not A2.

Before Assessing Memory Conditions, there should be this note:

In the description of PtrToHand, PtrToXHand, and PtrAndHand, Ptr or "pointer" refers to a memory address, not necessarily to a Memory Manager Ptr as returned by NewPtr. Handle does refer to a Memory Manager Handle, allocated by routines such as NewHandle or NewEmptyHandle.

You should not call StackSpace at interrupt time, because it sets the value returned by MemError and therefore may cause the interrupted application to fail.

In 680x0 code, calling a function in an unloaded segment will zero MemErr when the segment loader loads the segment into memory, causing MemError to return noErr. Therefore, you should always call MemError right after the Memory Manager function that may have caused an error.

There is a problem introduced with MultiFinder. It is well documented in Technote ME14-The New Memory Manager and You, under A5 World Problems and Heap Callback Procedures (but the workaround suggested in this technote is unusable).

The problem: when a heap is low on memory or a Handle is going the be purged, the GrowZone or PurgeProc function is called without an A5 world switch. This means that the GrowZone or PurgeProc function is called with CurrentA5 set according to the A5 world of the application that did the call generating the low-memory or Handle purge condition, rather than the value of A5 for which the application the GrowZone or PurgeProc function belongs. As the Technote says, this "[will] cause all hell to break loose". This may occur, for example, when the active and frontmost application closes a window. The update region of windows belonging to other applications need to be updated, which often involves extending the update region Handle, which can cause a GrowZone procedure to be called, but since the window being updated is in the background, the value of A5 is wrong with respect to the GrowZone or PurgeProc function.

The safe workaround, which is needed only in 680x0 code, involves saving A5 explicitly, and recovering it using PC-relative addressing. Going forward to Mac OS X and Carbon, GrowZone and PurgeProc functions will not be needed, so this problem will gradually go away.

The Assembly-Language Information for the LockMemoryContiguous function states that on entry register A1 contains the "number of bytes to unlock." In fact, register A1 contains the number of bytes to lock.

The description of DebuggerGetMax states (page 3-34): "Of course, you should use the Gestalt function to check whether virtual memory is available at all before you call the DebuggerGetMax function." To see if virtual memory is available from a debugger, it is preferable to check to see whether the _DebugUtil trap is available rather than call Gestalt.

The Assembly-Language Information for the DebuggerLockMemory function (page 3-37) lists the trap macro as _DebuggerLockMemory. The correct trap macro should be _DebugUtil. Furthermore, the Assembly-Language Information for the DebuggerLockMemory function states that on entry register A1 contains the "number of bytes to hold." In fact, register A1 contains the number of bytes to lock.

The Assembly-Language Information for the DebuggerUnlockMemory function (page 3-38) states that on entry register A1 contains the "number of bytes to hold." In fact, register A1 contains the number of bytes to unlock.

The sentence:

"However, the A5 register always points to the last of these global variables, thePort."

should read:

"However, the A5 register always contains the address of a pointer to the last of these global variables, thePort."

Acrobat version of this Note (56K)

Download