Legacy Document

Inside Macintosh: QuickDraw GX Environment and Utilities /

Chapter 2 - QuickDraw GX Memory Management / Additional Memory Management Topics

Low-Memory Conditions

QuickDraw GX may post memory-related errors, warnings, and notices while trying to allocate additional memory. These notifications indicate the status of QuickDraw GX memory management operations and, in some cases, provide the opportunity for your application to respond accordingly.

Freeing Up Already Allocated Memory

When QuickDraw GX needs one or more additional memory blocks for a graphics client heap, it responds to the situation by performing one or more of the following sequential steps. If insufficient memory is freed in one step, QuickDraw GX proceeds to the next step in the sequence. When sufficient memory blocks are freed, QuickDraw GX allocates the memory blocks and processing continues. QuickDraw GX memory management steps 1 through 4 affect memory blocks that have already been allocated.

1. QuickDraw GX disposes of dead caches: A QuickDraw GX cache is temporary memory used by QuickDraw GX. A cache that contains out of date, and therefore invalid, information is called a dead cache. If it disposes of dead caches, QuickDraw GX posts a disposed_dead_caches notice in the debugging init when the operation is complete. This notice is posted once per graphics client. This notice is a one-time-only alert indicating that your graphics client heap is low on memory.
2. QuickDraw GX unloads objects in pictures that have the gxDiskShape shape attribute: All of the objects within the picture are unloaded before any other objects are unloaded. The picture object is not unloaded. The gxDiskShape shape attribute is described in the chapter "Shape Objects" in Inside Macintosh: QuickDraw GX Objects.
3. QuickDraw GX disposes of live caches: A QuickDraw GX cache that contains current valid drawing information is called a live cache. After live caches are disposed of, they need to be rebuilt before the next time you draw the object. QuickDraw GX posts a disposed_live_caches notice in the debugging init when the operation is complete. This notice is only posted once per graphics client. This notice is a one-time-only alert indicating that your graphics client heap is low on memory.
4. QuickDraw GX relocates bit images: Bit images are moved in memory in order to free memory space adjacent to them. No memory error, warning, or notice is posted to notify you of this step.

Allocating New Memory and Unloading Objects

If QuickDraw GX has not released sufficient memory after step 4, it attempts to add additional memory blocks to the graphics client heap. If sufficient memory is not available after step 5, QuickDraw GX begins to unload objects to disk storage.

1. QuickDraw GX adds additional memory blocks: QuickDraw GX adds additional memory blocks to the graphics client heap. Prior to adding memory blocks, QuickDraw GX posts an about_to_grow_heap warning. If the gxStaticHeapClient attribute is set for the graphics client heap, QuickDraw GX does not perform this step.
2. QuickDraw GX unloads objects: Prior to unloading objects, QuickDraw GX posts an about_to_unload_objects warning. First, shapes with the gxDiskShape shape attribute are unloaded. Then, objects without either the gxDiskShape or the gxMemoryShape attributes are unloaded. Finally, shapes with the gxMemoryShape attribute are unloaded. Unlike disposing of caches, unloading occurs without information loss, but it does take time and disk space. For additional information about object loading and unloading, see the section "Loading and Unloading Objects" beginning on page 2-12. If an object cannot be unloaded, QuickDraw GX posts a could_not_create_backing_store error or the appropriate system error.

When your application has received the about_to_grow_heap warning or the could_not_create_backing_store error, you can decide to free up some memory before GX does. However, you must be very careful if you decide to dispose of a GX object. You cannot dispose of anything that is currently in use. The only way to determine if something is in use would be by carefully tracking the GX objects used within your application. Most likely, you would only want to dispose of off-screen worlds used by your application and let GX free up memory by releasing other blocks. GX knows what is and is not busy.

If steps 1 through 6 fail to release sufficient memory to accommodate the allocation of the required additional blocks of memory, QuickDraw GX posts an out_of_memory error.

Functions That Create Additional Memory Demands

Individual QuickDraw GX functions have different memory-allocation consequences:

• Many QuickDraw GX functions explicitly allocate memory. For example, the GXNewShape, GXCopyToShape, and GetShapeParts functions allocate memory. An out_of_memory error may be posted when a memory allocation fails.
• Most QuickDraw GX functions can implicitly allocate memory to load a required object. For example, the GXGetShapeAttributes function may need to load a shape into memory to retrieve its attributes. QuickDraw GX loads objects automatically and does not post an error, warning, or notice. The exception is when QuickDraw GX posts an out_of_memory error when a memory allocation fails or a disk error occurs.
• Some functions do not allocate memory explicitly or implicitly. These functions might require a graphics client heap and do not post an out_of_memory error. These include math routines, error routines, and the GXCloneObject, GXDisposeObject, GXUnloadObject, GXValidateObject function sets and all of the functions listed in the second part of Table 2-1 on page 2-14.

The GraphicsBug utility is useful in debugging memory problems. This utility is described in the chapter "QuickDraw GX Debugging" in this book.

QuickDraw GX errors, warnings, and notices are described in the chapter "Errors, Warnings, and Notices" in this book.