Memory Manager Reference (Legacy)

Framework
CoreServices/CoreServices.h
Declared in
MacMemory.h

Overview

The Memory Manager was the memory management solution for versions of the Macintosh operating system prior to Mac OS X. It remains available for compatibility with legacy applications and for new applications that must work with legacy Carbon code that requires handles.

In previous versions of the Macintosh operating system, developers used the Memory Manager to set up an application’s memory partition at launch time, to manage an application’s heap, to minimize application memory fragmentation, and to implement a scheme to avoid low-memory conditions. All of these operations are now handled transparently by Mac OS X.

In the Mac OS X Memory Manager, many functions are deprecated, the callbacks are not functional, and the data types and constants are not used. In Mac OS X there is no need to set up or manage an application memory partition or to manage pointers. To allocate memory, in most cases you simply use the C functions malloc or calloc. Mac OS X ensures that every application has access to as much memory as it needs—up to 4 gigabytes of addressable space per 32-bit process.

Mac OS X does not support functions for accessing the system heap, as the system heap is unavailable to applications in Mac OS X. Starting with Mac OS X v10.3, Memory Manager is thread safe, and the MemError function now returns error codes on a per-thread basis.

For information on memory management issues when porting a legacy Macintosh application to Mac OS X, refer to the Carbon Porting Guide and to Technical Note 2130, Memory Allocation Recommendations on Mac OS X.

Functions by Task

Allocating and Releasing Nonrelocatable Blocks of Memory

Allocating and Releasing Relocatable Blocks of Memory

Allocating Temporary Memory

Assessing Memory Conditions

Changing the Sizes of Relocatable and Nonrelocatable Blocks

Managing Relocatable Blocks

Manipulating Blocks of Memory

Setting the Properties of Relocatable Blocks

Miscellaneous

Deprecated Functions

You should avoid using the functions listed in this section.

Functions

BlockMove

Copies a sequence of bytes from one location in memory to another.

static void BlockMove (
   const void *srcPtr,
   void *destPtr,
   Size byteCount
);
Parameters
srcPtr

The address of the first byte to copy.

destPtr

The destination address.

byteCount

The number of bytes to copy. If the value of byteCount is 0, BlockMove does nothing.

Discussion

The BlockMove function copies the specified number of bytes from the address designated by srcPtr to that designated by destPtr. It updates no pointers.

The BlockMove function works correctly even if the source and destination blocks overlap.

You can safely call BlockMove at interrupt time. Even though it moves memory, BlockMove does not move relocatable blocks, but simply copies bytes.

Call the function MemError to get the result code. See “Memory Manager Result Codes.”

The BlockMove function currently flushes the processor caches whenever it moves more than 12 bytes. This behavior can adversely affect your application’s performance. You might want to avoid calling BlockMove to move small amounts of data in memory if there is no possibility of moving stale data or instructions. For more information about stale data and instructions, see the discussion of the processor caches in the chapter “Memory Management Utilities” in Inside Macintosh: Memory.

Special Considerations

Beginning in Mac OS X v10.4, the BlockMove function is inlined to a direct call to the POSIX memmove function. For more information, see the header file MacMemory.h.

Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
MacMemory.h

BlockMoveData

static void BlockMoveData (
   const void *srcPtr,
   void *destPtr,
   Size byteCount
);
Parameters
srcPtr
destPtr
byteCount
Discussion

You should not make any assumptions about the state of the destination memory while BlockMoveData is executing. In the intermediate state, values may be present that are neither the original nor the final ones. For example, this function may use the 'dcbz' instruction. If the underlying memory is not cacheable, if the memory is write-through instead of copy-back, or if the cache block is flushed for some reason, the 'dcbz' instruction will write zeros to the destination. You can avoid the use of the 'dcbz' instruction by calling BlockMoveDataUncached, but even that function makes no other guarantees about the memory block's intermediate state.

Special Considerations

Beginning in Mac OS X v10.4, the BlockMoveData function is inlined to a direct call to the POSIX memmove function. For more information, see the header file MacMemory.h.

Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
MacMemory.h

BlockMoveDataUncached

static void BlockMoveDataUncached (
   const void *srcPtr,
   void *destPtr,
   Size byteCount
);
Parameters
srcPtr
destPtr
byteCount
Discussion

You should not make any assumptions about the state of the destination memory while BlockMoveDataUncached is executing. In the intermediate state, values may be present that are neither the original nor the final ones.

Special Considerations

Beginning in Mac OS X v10.4, the BlockMoveDataUncached function is inlined to a direct call to the POSIX memmove function. For more information, see the header file MacMemory.h.

Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
MacMemory.h

BlockMoveUncached

static void BlockMoveUncached (
   const void *srcPtr,
   void *destPtr,
   Size byteCount
);
Parameters
srcPtr
destPtr
byteCount
Special Considerations

Beginning in Mac OS X v10.4, the BlockMoveUncached function is inlined to a direct call to the POSIX memmove function. For more information, see the header file MacMemory.h.

Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
MacMemory.h

BlockZero

static void BlockZero (
   void *destPtr,
   Size byteCount
);
Parameters
destPtr
byteCount
Special Considerations

Beginning in Mac OS X v10.4, the BlockZero function is inlined to a direct call to the POSIX bzero function. For more information, see the header file MacMemory.h.

Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
MacMemory.h

BlockZeroUncached

static void BlockZeroUncached (
   void *destPtr,
   Size byteCount
);
Parameters
destPtr
byteCount
Special Considerations

Beginning in Mac OS X v10.4, the BlockZeroUncached function is inlined to a direct call to the POSIX bzero function. For more information, see the header file MacMemory.h.

Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
MacMemory.h

Callbacks

All Memory Manager callbacks are deprecated in Mac OS X. They are non-functional.

GrowZoneProcPtr

Deprecated.

typedef long (*GrowZoneProcPtr) (
   Size cbNeeded
);

If you name your function MyGrowZoneProc, you would declare it like this:

long MyGrowZoneProc (
   Size cbNeeded
);

Parameters
cbNeeded

The physical size, in bytes, of the needed block, including the block header. The grow-zone function should attempt to create a free block of at least this size.

Return Value

The number of bytes of memory the function has freed.

Discussion

User-defined function that creates free space in the heap.

Whenever the Memory Manager has exhausted all available means of creating space within your application heap—including purging, compacting, and (if possible) expanding the heap—it calls your application-defined grow-zone function. The grow-zone function can do whatever is necessary to create free space in the heap. Typically, a grow-zone function marks some unneeded blocks as purgeable or releases an emergency memory reserve maintained by your application.

The grow-zone function should return a nonzero value equal to the number of bytes of memory it has freed, or zero if it is unable to free any. When the function returns a nonzero value, the Memory Manager once again purges and compacts the heap zone and tries to reallocate memory. If there is still insufficient memory, the Memory Manager calls the grow-zone function again (but only if the function returned a nonzero value the previous time it was called). This mechanism allows your grow-zone function to release just a little bit of memory at a time. If the amount it releases at any time is not enough, the Memory Manager calls it again and gives it the opportunity to take more drastic measures.

The Memory Manager might designate a particular relocatable block in the heap as protected; your grow-zone function should not move or purge that block. You can determine which block, if any, the Memory Manager has protected by calling the GZSaveHnd function in your grow-zone function.

Remember that the Memory Manager calls a grow-zone function while attempting to allocate memory. As a result, your grow-zone function should not allocate memory itself or perform any other actions that might indirectly cause memory allocation (such as calling functions in unloaded code segments or displaying dialog boxes).

You install a grow-zone function by passing its address to the InitZone function when you create a new heap zone or by calling the SetGrowZone function at any other time.

Your grow-zone function might be called at a time when the system is attempting to allocate memory and the value in the A5 register is not correct. If your function accesses your application’s A5 world or makes any trap calls, you need to set up and later restore the A5 register by calling SetCurrentA5 and SetA5. See the chapter “Memory Management Utilities” in this book for a description of these two functions.

Because of the optimizations performed by some compilers, the actual work of the grow-zone function and the setting and restoring of the A5 register might have to be placed in separate functions.

See the chapter “Introduction to Memory Management” for a definition of a sample grow-zone function.

Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
MacMemory.h

PurgeProcPtr

Deprecated.

typedef void (*PurgeProcPtr) (
   Handle blockToPurge
);

If you name your function MyPurgeProc, you would declare it like this:

void MyPurgeProc (
   Handle blockToPurge
);

Parameters
blockToPurge

A handle to the block that is about to be purged.

Discussion

User-defined function called when the Memory Manager needs to purge a block or allocate memory.

Whenever the Memory Manager needs to purge a block from the application heap, it first calls any application-defined purge-warning function that you have installed. The purge-warning function can, if necessary, save the contents of that block or otherwise respond to the warning.

Your purge-warning function is called during a memory-allocation request. As a result, you should not call any functions that might cause memory to be moved or purged. In particular, if you save the data of the block in a file, the file should already be open when your purge-warning function is called, and you should write the data synchronously.

You should not dispose of or change the purgeable status of the block whose handle is passed to your function.

To install a purge-warning function, you need to assign its address to the purgeProc field of the associated zone header.

Note that if you call the Resource Manager function SetResPurge with the parameter TRUE, any existing purge-warning function is replaced by a purge-warning function installed by the Resource Manager. You can execute both warning functions by calling SetResPurge, saving the existing value of the purgeProc field of the zone header, and then reinstalling your purge-warning function. Your purge-warning function should call the Resource Manager’s purge-warning function internally.

Your purge-warning function might be called at a time when the system is attempting to allocate memory and the value in the A5 register is not correct. If your function accesses your application’s A5 world or makes any trap calls, you need to set up and later restore the A5 register by calling SetCurrentA5 and SetA5.

Because of the optimizations performed by some compilers, the actual work of the purge-warning function and the setting and restoring of the A5 register might have to be placed in separate functions.

The Memory Manager calls your purge-warning function for every handle that is about to be purged (not necessarily for every purgeable handle in your heap, however). Your function should be able to determine quickly whether the handle that the Memory Manager is about to purge points to data you need to save or otherwise process.

Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
MacMemory.h

UserFnProcPtr

Deprecated.

typedef void (*UserFnProcPtr) (
   void *parameter
);

If you name your function MyUserFnProc, you would declare it like this:

void MyUserFnProc (
   void * parameter
);

Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
MacMemory.h

Data Types

All Memory Manager data types are deprecated in Mac OS X. They are not used.

BackingFileID

Deprecated.

typedef struct * BackingFileID;
Special Considerations

FileViewAccess

Deprecated.

typedef UInt32 FileViewAccess;
enum {
   kFileViewAccessReadBit = 0,
   kFileViewAccessWriteBit = 1,
   kFileViewAccessExecuteBit = 2,
   kFileViewAccessReadMask = 1,
   kFileViewAccessWriteMask = 2,
   kFileViewAccessExecuteMask = 4,
   kFileViewAccessExcluded = 0,
   kFileViewAccessReadOnly = 5,
   kFileViewAccessReadWrite = 7
};
Special Considerations

FileViewID

Deprecated.

typedef struct * FileViewID;
Special Considerations

FileViewInformation

Deprecated.

struct FileViewInformation {
   ProcessSerialNumber owningProcess;
   LogicalAddress viewBase;
   ByteCount viewLength;
   BackingFileID backingFile;
   UInt64 backingBase;
   FileViewAccess access;
   ByteCount guardLength;
   FileViewOptions options;
};

FileViewOptions

Deprecated.

typedef OptionBits FileViewOptions;

GrowZoneUPP

Deprecated.

typedef GrowZoneProcPtr GrowZoneUPP;
Discussion

For more information, see the description of the GrowZoneUPP () callback function.

Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
MacMemory.h

LogicalToPhysicalTable

Deprecated.

struct LogicalToPhysicalTable {
   MemoryBlock logical;
   MemoryBlock physical[8];
};
typedef struct LogicalToPhysicalTable LogicalToPhysicalTable;
Fields
logical

A logical block of memory whose corresponding physical blocks are to be determined.

physical

A physical translation table that identifies the blocks of physical memory corresponding to the logical block identified in the logical field.

Discussion

The GetPhysical function uses a translation table to hold information about a logical address range and its corresponding physical addresses. A translation table is defined by the data type LogicalToPhysicalTable.

Special Considerations
Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
MacMemory.h

MappedFileAttributes

Deprecated.

typedef UInt32 MappedFileAttributes;
enum {
   kIsMappedScratchFile = 1
};

MappedFileInformation

Deprecated.

struct MappedFileInformation {
   ProcessSerialNumber owningProcess;
   FSRef *ref;
   HFSUniStr255 *forkName;
   MappingPrivileges privileges;
   UInt64 currentSize;
   MappedFileAttributes attributes;
};

MappingPrivileges

Deprecated.

typedef UInt32 MappingPrivileges;
enum {
   kInvalidMappedPrivileges = 0,
   kCanReadMappedFile = 1,
   kCanWriteMappedFile = 2,
   kNoProcessMappedFile = -2147483648,
   kValidMappingPrivilegesMask = -2147483645
};
Special Considerations

MemoryBlock

Deprecated.

struct MemoryBlock {
   void * address;
   unsigned long count;
};
typedef struct MemoryBlock MemoryBlock;
Fields
address

A pointer to the beginning of a block of memory.

count

The number of bytes in the block of memory.

Discussion

The GetPhysical function uses a structure of type MemoryBlock to hold information about a block of memory, either logical or physical.

Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
MacMemory.h

PurgeUPP

Deprecated.

typedef PurgeProcPtr PurgeUPP;
Discussion

For more information, see the description of the PurgeUPP () callback function.

Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
MacMemory.h

StatusRegisterContents

Deprecated.

typedef  StatusRegisterContents;
Special Considerations
Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
MacMemory.h

UserFnUPP

Deprecated.

typedef UserFnProcPtr UserFnUPP;
Discussion

For more information, see the description of the UserFnUPP () callback function.

Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
MacMemory.h

VolumeVirtualMemoryInfo

Deprecated.

struct VolumeVirtualMemoryInfo {
   PBVersion version;
   SInt16 volumeRefNum;
   Boolean inUse;
   UInt8 _fill;
   UInt32 vmOptions;
};
typedef struct VolumeVirtualMemoryInfo VolumeVirtualMemoryInfo;
   typedef VolumeVirtualMemoryInfo * VolumeVirtualMemoryInfoPtr;
Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
MacMemory.h

Zone

Deprecated.

struct Zone {
   Ptr bkLim;
   Ptr purgePtr;
   Ptr hFstFree;
   long zcbFree;
   GrowZoneUPP gzProc;
   short moreMast;
   short flags;
   short cntRel;
   short maxRel;
   short cntNRel;
   SInt8 heapType;
   SInt8 unused;
   short cntEmpty;
   short cntHandles;
   long minCBFree;
   PurgeUPP purgeProc;
   Ptr sparePtr;
   Ptr allocPtr;
   short heapData;
};
typedef struct Zone Zone;
   typedef Zone * THz;
Availability
  • Available in OS X v10.0 and later.
  • Not available to 64-bit applications.
Declared In
MacMemory.h

Constants

All Memory Manager constants are deprecated in Mac OS X. They are not used.

Default Physical Entry Count Constant

Deprecated.

enum {
   defaultPhysicalEntryCount = 8
};
Discussion

The defaultPhysicalEntryCount constant represents the default number of physical blocks in a table.

k32BitHeap

Deprecated.

enum {
   k32BitHeap = 1,
   kNewStyleHeap = 2,
   kNewDebugHeap = 4
};

kFileViewInformationVersion1

Deprecated.

enum {
   kFileViewInformationVersion1 = 1
};

kHandleIsResourceBit

Deprecated.

enum {
   kHandleIsResourceBit = 5,
   kHandlePurgeableBit = 6,
   kHandleLockedBit = 7
};

kHandleIsResourceMask

Deprecated.

enum {
   kHandleIsResourceMask = 0x20,
   kHandlePurgeableMask = 0x40,
   kHandleLockedMask = 0x80
};

kMapEntireFork

Deprecated.

enum {
   kMapEntireFork = -1
};
Constants
kMapEntireFork

kMappedFileInformationVersion1

Deprecated.

enum {
   kMappedFileInformationVersion1 = 1
};

kPageInMemory

Deprecated.

typedef short PageState;
enum {
   kPageInMemory = 0,
   kPageOnDisk = 1,
   kNotPaged = 2
};
Discussion

The GetPageState function obtains the state value of a page of logical memory. The PageState data type defines constants that represent these possible state values.

Debuggers need a way to display the contents of memory without paging or to display the contents of pages currently on disk. The GetPageState function obtains a constant from the PageState data type to specify the state of a page containing a virtual address. A debugger can use this information to determine whether certain memory addresses should be referenced. Note that ROM and I/O space are not pageable and therefore are considered not paged.

kVolumeVirtualMemoryInfoVersion1

Deprecated.

enum {
   kVolumeVirtualMemoryInfoVersion1 = 1
};

maxSize

Deprecated.

enum {
   maxSize = 0x7FFFFFF0
};

Result Codes

The most common result codes returned by the Memory Manager are listed below.

Result CodeValueDescription
menuPrgErr 84

A menu was purged.

Available in OS X v10.0 and later.

negZcbFreeErr 33

A heap has been corrupted.

Available in OS X v10.0 and later.

memROZErr -99

Operation on a read-only zone. This result code is not relevant in Mac OS X.

Available in OS X v10.0 and later.

memFullErr -108

Not enough memory in heap.

Available in OS X v10.0 and later.

nilHandleErr -109

Handle argument is NULL.

Available in OS X v10.0 and later.

memAdrErr -110

Address is odd or out of range.

Available in OS X v10.0 and later.

memWZErr -111

Attempt to operate on a free block.

Available in OS X v10.0 and later.

memPurErr -112

Attempt to purge a locked or unpurgeable block.

Available in OS X v10.0 and later.

memAZErr-113

Address in zone check failed.

Available in OS X v10.0 and later.

memPCErr-114

Pointer check failed.

Available in OS X v10.0 and later.

memBCErr -115

Block check failed.

Available in OS X v10.0 and later.

memSCErr-116

Size check failed.

Available in OS X v10.0 and later.

memLockedErr -117

Block is locked.

Available in OS X v10.0 and later.