Local Memory: 2.3 Structure of a Local Memory Heap: Types of LMem Heaps

LMemType, LMemFlags

In addition to being used for general memory needs, local memory heaps perform many specific functions in the GEOS system. When an LMem heap is created, a member of the LMemType enumerated type is passed, indicating to what use the LMem heap will be put. Several types are available:

LMEM_TYPE_GENERAL: The LMem heap will be used for general data storage, possibly including a chunk, name, or element array. When an application creates an LMem heap, it will almost always be of type "General" or "Object."
LMEM_TYPE_WINDOW: Windows are stored in memory as LMem heaps. The header contains information about the window; each region in the window is stored as a chunk. Applications will not directly create Window heaps.
LMEM_TYPE_OBJ_BLOCK: Objects are stored in object blocks, which are LMem heaps. An object block has some extra header information and contains one chunk which contains only flags. All the objects in the block are stored as chunks on the heap. Applications can directly create object blocks; for more information, see the GEOS Programming chapter.
LMEM_TYPE_GSTATE
A GState is an LMem heap. The GState information is in the header, and the application clip-rectangle is stored in a chunk. Applications do not directly create GState blocks; rather, they call a GState creation routine, which creates the block. (See the Graphics Environment chapter.)
LMEM_TYPE_FONT_BLOCK Font blocks are stored as LMem heaps. Applications do not create font blocks directly.
LMEM_TYPE_GSTRING: Whenever a GString is created or loaded, a GString LMem heap is created, and elements are added as chunks. The heap is created automatically by the GString routines; applications should not create GString blocks. (See the Graphics Environment chapter.)
LMEM_TYPE_DB_ITEMS
The Virtual Memory mechanism provides routines to create and manage database items

, short pieces of data which are dynamically allocated and are saved with the VM file. These items are stored in special database LMem heaps, which are created in special database blocks in the VM file. Applications do not directly allocate DB blocks; rather, they call DB routines, which see to it that the blocks are created. (See the Database chapter.)

When an LMem heap is allocated, certain flags are passed to indicate properties the heap should have. Some of these flags are passed only for system-created heaps. The flags are stored in a word-length record (LocalMemoryFlags ); the record also contains flags indicating the current state of the heap. The LocalMemoryFlags are listed below:

LMF_HAS_FLAGS Set if the block has a chunk containing only flags. This flag is set for object blocks; it is usually cleared for general LMem heaps.
LMF_IN_RESOURCE: Set if the block has just been loaded from a resource and has not been changed since being loaded. This flag is set only for object blocks created by the compiler.
LMF_DETACHABLE: Set if the block is an object block which can be saved to a state file.
LMF_DUPLICATED: Set if block is an object block created by the ObjDuplicateResource() routine. This flag should not be set by applications.
LMF_RELOCATED: Set if all the objects in the block have been relocated. The object system sets this when it has relocated all the objects in the block.
LMF_AUTO_FREE: This flag is used by several object routines. It indicates that if the block's in-use count drops to zero, the block may be freed. This flag should not be set by applications.
LMF_IN_MEM_ALLOC: This flag is used in error-checking code to prevent the heap from being validated while a chunk is being allocated. For internal use only--do not modify .
LMF_IS_VM: Set if LMem heap is in a VM block and the block should be marked dirty whenever a chunk is marked dirty. This flag is automatically set by the VM code when an LMem heap is created in or attached to a VM file. This flag should not be set by applications.
LMF_NO_HANDLES: Set if block does not use chunk handles. A block can be set to simulate the C malloc() routine; in this case, chunks are not relocated after being created, so chunk handles are not needed. Ordinarily, these blocks are created by the malloc() routine, not by applications. (See the discussion of malloc() in the Memory Management chapter.)
LMF_NO_ENLARGE
Indicates that the local-memory routines should not enlarge this block to fulfill chunk requests. This guarantees that the block will not be moved by a chunk allocation request; however, it makes these requests more likely to fail.
LMF_RETURN_ERRORS Set if local memory routines should return errors when allocation requests cannot be fulfilled. If the flag is not set, allocation routines will fatal-error if they cannot comply with requests. This flag is generally clear for expandable LMem blocks, since many system routines (such as ObjInstantiate() ) are optimized in such a way that they cannot deal with LMem allocation errors.
LMF_DEATH_COUNT: This field occupies the least significant three bits of the flag field. It means nothing if the value is zero. If it is non-zero, it indicates the number of remove-block messages left which must hit BlockDeathCommon before it will free the block. This flag is used some error-checking code in the kernel.
STD_LMEM_OBJECT_FLAGS: This is a constant which combines the LMF_HAS_FLAGS and LMF_RELOCATED flags. These flags should be set for all object blocks.

GEOS SDK TechDocs |

2.2 Chunks and Chunk Handles | Next:

3 Using Local Memory Heaps