Local Memory: 3.4 Using Local Memory Heaps: Example of LMem Usage

GEOS SDK TechDocs

3.3 Contracting the LMem Heap

4 Special LMem Uses

At first, the local memory techniques can seem tricky. This section contains an example of LMem usage in Goc. The example shows the basic principles of LMem usage.

Code Display 16-1 LMem Usage in GOC

/*
 * Declarations
 */

/* We'll want to have a fixed data area at the start of the block. That area will
 * have to start with an LMemBlockHeader, but after that, we can put whatever we
 * want. To make it easy to access the fixed data, we define a structure.
 */
typedef struct {
	LMemBlockHeader		MLMBH_standardHeader;
	float		MLMBH_someData;
	float		MLMBH_someMoreData;
	char		MLMBH_someChars[10];
} MyLMemBlockHeader;

MyLMemBlockHeader 			*thisHeapsHeader;
MemHandle			thisHeapsHandle;
ChunkHandle			firstChH, secondChH;
char 			*firstChPtr, *secondChPtr;
int			i;

/*
 * Code
 */

/* We have to create the LMem heap. First, we create the block: */
thisHeapsHandle = MemAlloc(					/* MemAlloc returns the block handle */
			2048,		/* Allocate 2K; can grow as necessary */
			HF_SWAPABLE,		/* Make block swapable. LMemInitHeap()
					 * will add the flag HF_LMEM. */
			HAF_ZERO_INIT | HAF_LOCK); 				/* Zero & lock the block
							 * upon allocation */

LMemInitHeap(thisHeapsHandle,					/* Pass handle of locked block */
		LMEM_TYPE_GENERAL,			/* Allocate a general heap */
		0,			/* Don't pass any flags */
		sizeof(MyLMemBlockHeader), 	/* Offset to leave room for header */
		STD_INIT_HANDLES,			/* Standard # of starter handles */
		STD_INIT_HEAP);		/* Allocate standard amt. of empty heap */

/* The block is still locked; we can initialize the fixed data section. */
thisHeapsHeader = (MyLMemBlockHeader *) MemDeref(thisHeapsHandle);
thisHeapsHeader->MLMBH_someData = 3.1415926;

/* Now, we allocate some chunks. This invalidates pointers to this heap (such as 
 * thisHeapsHeader), since chunk allocation may cause the heap to be resized (and
 * thus moved). The block must be locked when we do this.
 */
firstChH = LMemAlloc(					/* LMemAlloc returns a chunk handle */
		thisHeapsHandle,			/* Pass handle of block . . . */
		100);			/* . . . and number of bytes in chunk */

secondChH = LMemAlloc(thisHeapsHandle, 50);

/* Now, we start writing data to a chunk: */
firstChPtr = (char *) LMemDerefHandles(thisHeapsHandle, firstChH);
for(i = 0; i <= 30; i++)
   firstChPtr[i] = 'x';

/* We can insert 10 bytes into the middle of the second chunk. This may cause the
 * chunks or blocks to be shuffled; all pointers are invalidated
 */
LMemInsertAtHandles(thisHeapsHandle, secondChH, 						/* Block & chunk handles */
		20,				/* Insert after 20th byte */
		30);				/* Insert 30 null bytes */

/* If we want to access the first chunk, we need to dereference its handle again:
 */
firstChPtr = (char *) LMemDeref(thisHeapsHandle, firstChH);
for(i = 1; i <= 15; i++)
    firstChPtr[(i<<1)] = 'o';

/* When we're done with a chunk, we should free it. This does not invalidate 
 * any pointers to other chunks.
 */
LMemFreeHandles(thisHeapsHandle, firstChH);

/* If we won't be using an LMem heap for a while, we should unlock it the way we 
 * would any block: */
MemUnlock(thisHeapsHandle);

/* When we're done with the LMem heap, we can just free it. */
MemFree(thisHeapsHandle);

GEOS SDK TechDocs

3.3 Contracting the LMem Heap

4 Special LMem Uses