Local Memory: 3.1 Using Local Memory Heaps: Creating a Local Heap

GEOS SDK TechDocs

3 Using Local Memory Heaps

3.2 Using Chunks

LMemInitHeap(), MemAllocLMem()

Before you create a local heap, you must first allocate and lock a block on the global heap using MemAlloc() and MemLock() . (Alternatively, you can allocate a fixed block.) Then, you must call LMemInitHeap() . (If you are creating a local heap to hold objects, you should use the UserAllocObjBlock() routine instead; it's much simpler to use.)

LMemInitHeap() creates and initializes a local memory heap. It must be passed several arguments:

• The handle of a locked or fixed block which will contain the local memory heap. It may be moveable, discardable, both, or neither; it should not have the flag HF_LMEM set. If the LMem heap will be resizable, the block may be of any size; the LMem routines will enlarge it if necessary. If the heap will not be resizable (i.e. LMF_NO_ENLARGE is passed), it must be created large enough to accommodate the heap.
• The offset within the block where the local heap's handle table will begin. The local heap will fill the space to the end of the block; any data between the LMemBlockHeader and the indicated offset will be zero-initialized. If an application will not need a fixed data space, it should specify an offset of zero; the handle table will then be put immediately after the LMemBlockHeader . If the created block will be an object block, then it will need room for an ObjLMemBlockHeader structure. Often, when an application needs a fixed data space, it will define a special structure, the first element of which is an LMemBlockHeader , and will pass the size of that structure as the offset. It can then access the fixed data by using the fields of the structure. If the offset specified is less than the size of an LMemBlockHeader , LMemInitHeap() will return an error.
• A member of the LMemType enumerated type, specifying the type of block to be created (see 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 wil ).
• A word of LocalMemoryFlags for the heap. (See 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 .)
• A word specifying the number of chunk handles to leave room for in the starter handle table. When these chunks have all been allocated, the local memory manager will expand the LMem handle table to create more chunk handles. No matter how big the starter handle table is, the heap will initially contain just one chunk (whose size is specified by the next argument). Applications should generally pass the constant STD_INIT_HANDLES.
• A word specifying the amount of space to be assigned to the chunk created when the heap is initialized. When more space is needed, the chunks will expand to the end of the block, and (if necessary) the block itself will be expanded. Applications should generally pass the constant STD_INIT_HEAP.

LMemInitHeap() creates the LMemBlockHeader and the chunk handle table. It also creates a single free chunk; more chunks will automatically be created as needed. It may resize the block passed (unless the flag LMF_NO_ENLARGE is passed); therefore, any pointers to the block may become invalid. It does not return anything.

If you want to create a memory block and initialize it as an LMem heap in one operation, call MemAllocLMem() . This routine takes two arguments: a member of the LMemType enumerated type, and the amount of space to leave for the header (again, a zero size indicates that the default header size should be used). MemAllocLMem() allocates a movable, swapable block in the global heap, then initializes an LMem heap in that block. If you specify an LMemType of LMEM_TYPE_OBJ_BLOCK, MemAllocLMem() will pass the STD_LMEM_OBJECT_FLAGS flags; otherwise, it will pass a clear LocalMemoryFlags record.

GEOS SDK TechDocs

3 Using Local Memory Heaps

3.2 Using Chunks