LMemInitHeap()

void	LMemInitHeap(
        MemHandle		mh,				/* Handle of (locked or fixed)
						 * block which will contain heap 	*/

        LMemType		type,				/* Type of heap to create */
        LocalMemoryFlags		flags,				/* Record of LocalMemoryFlags */
        word		lmemOffset,				/* Offset of first chunk in heap */
        word		numHandles,				/* Size of starter handle table */
        word		freeSpace);				/* Size of first free chunk 
						 * created */

This routine creates an LMem heap in a global memory block. The block must be locked or fixed in memory. The routine initializes the LMemBlockHeader , creates a handle table, allocates a single free chunk, and turns on the HF_LMEM flag for the block. The block will be reallocated if necessary to make room for the heap. The routine takes six arguments:

mh: The memory block's handle
type: A member of the LMemType enumerated type, specifying the kind of block to create. For most applications, this will be LMEM_TYPE_GENERAL.
flags: A record of LocalMemoryFlags , specifying certain properties of the heap. Most applications will pass a null record.
lmemOffset: The offset within the block at which to start the heap. This must be larger than the size of the LMemBlockHeader structure which begins every heap block. Any space between the LMemBlockHeader and the heap is left untouched by all LMem routines. Usually you can just pass sizeof(LMemBlockHeader ) as this argument, or sizeof(ObjLMemBlockHeader ) for object blocks.
numHandles: The number of entries to create in the block's chunk handle table. The chunk handle table will grow automatically when all entries have been used up. Applications should generally pass the constant STD_INIT_HANDLES; they should definitely pass a positive number.
freeSpace: The amount of space to allocate to the first free chunk. Applications should generally pass the constant STD_INIT_HEAP; they should definitely pass a positive number.

To destroy an LMem heap, call MemFree() to free the block containing the heap.

Structures: There are two special data types used by this routine: LMemType and LocalMemoryFlags .

LMem heaps are created for many different purposes. Some of these purposes require the heap to have special functionality. For this reason, you must pass a member of the LMemType enumerated type to specify the kind of heap to create. The following types can be used; other types exist but should not be used with LMemInitHeap() .

LMEM_TYPE_GENERAL: Ordinary heap. Most application LMem heaps will be of this type.
LMEM_TYPE_OBJ_BLOCK: The heap will contain object instance chunks.

When an LMem heap is created, you must pass a record of flags to LMemInitHeap() to indicate how the heap should be treated. Most of the LocalMemoryFlags are only passed by system routines; the flags available for this routine are: LMF_HAS_FLAGS, LMF_DETACHABLE, LMF_NO_ENLARGE, LMF_RETURN_ERRORS. The flags can be read by examining the LMemBlockHeader structure at the beginning of the block. Ordinarily, general LMem heaps will have all flags cleared.

Tips and Tricks: If you want a fixed data space after the header, declare a structure whose first element is an LMemBlockHeader and whose other fields are for the data you will store in the fixed data space. Pass the size of this structure as the LMemOffset argument. You can now access the fixed data area by using the fields of the structure.

Be Sure To: Pass an offset at least as large as sizeof(LMemBlockHeader) . If you pass an offset that is too small, the results are undefined. Lock the block on the global heap before calling this routine (unless the block is fixed).

Warnings: The block may be relocated, if its initial size is too small to accommodate the heap. This is true even for fixed blocks. If the flag LMF_NO_ENLARGE is set, the block will never be relocated; however, you must make sure it starts out large enough to accommodate the entire heap.

Include: lmem.h

See Also: LMemBlockHeader, LMemType, LocalMemoryFlags, MemAlloc(), MemAllocLMem(), MemFree(), VMAllocLMem().

LMemInsertAt()

void	LMemInsertAt(
        optr	chunk,				/* optr of chunk to resize */
        word	insertOffset,				/* Offset within chunk of first byte
					 * to be added */

        word	insertCount);				/* # of bytes to add */

This routine inserts space in the middle of a chunk and zero-initializes the new space. The first new byte will be at the specified offset within the chunk.

Be Sure To: Lock the block on the global heap (unless it is fixed). Make sure the offset is within the specified chunk.

Warnings: This routine may resize or compact the heap; thus, all pointers to data within the block are invalidated.

You must pass an insertOffset that is actually within the chunk; if the offset is out-of-bounds, results are undefined.

Include: lmem.h

See Also: LMemReAlloc(), LMemDeleteAt(), LMemInsertAtHandles().

LMemGetChunkSize()

LMemGetChunkSizeHandles()

LMemInitHeap()

LMemInsertAt()

LMemInsertAtHandles()