![]() |
GrowZoneProcPtr |
||||
Header: | MacMemory.h | Carbon status: | Supported | |
User-defined function that creates free space in the heap.
typedef SInt32(* GrowZoneProcPtr) ( Size cbNeeded );
You would declare your function like this if you were to name it MyGrowZoneCallback:
SInt32 MyGrowZoneCallback ( Size 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.
The number of bytes of memory the function has freed.0
Whenever the Memory Manager has exhausted all available means of creating space within your application heapincluding purging, compacting, and (if possible) expanding the heapit 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 applications 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.
Supported in Carbon.