| GEOS SDK TechDocs | | CCB() ... | ChunkArrayDelete() ...

---

CFatalError()

void	CFatalError(
        word	code)

This routine generates a fatal error. It stores an error code passed for use by the debugger.

ChunkArrayAppend()

void *	ChunkArrayAppend(
        optr	array,				/* optr to chunk array */
        word	elementSize)				/* Size of new element (ignored if 
						 * elements are uniform-sized) */

This routine adds a new element to the end of a chunk array. It automatically expands the chunk to make room for the element and updates the ChunkArrayHeader . It returns a pointer to the new element.

One of the arguments is the size of the new element. This argument is significant if the array contains variable-sized elements. If the elements are uniform-sized, this argument is ignored. The array is specified with an optr.

Include: chunkarr.h

Be Sure To: Lock the block on the global heap (if it is not fixed).

Warnings: This routine resizes the chunk, which means it can cause heap compaction or resizing. Therefore, all existing pointers to within the LMem heap are invalidated.

See Also: ChunkArrayInsertAt(), ChunkArrayDelete().

ChunkArrayAppendHandles()

void *	ChunkArrayAppendHandles(
        MemHandle		mh,				/* Handle of LMem heap's block */
        ChunkHandle		ch,				/* Handle of chunk array */
        word		size)				/* Size of new element (ignored if 
							 * elements are uniform-sized) */

This routine is exactly like ChunkArrayAppend() , except that the chunk array is specified by its global and local handles instead of by an optr.

Include: chunkarr.h

Be Sure To: Lock the block on the global heap (if it is not fixed).

Warnings: This routine resizes the chunk, which means it can cause heap compaction or resizing. Therefore, all existing pointers to within the LMem heap are invalidated.

See Also: ChunkArrayInsertAt(), ChunkArrayDelete().

ChunkArrayCreate()

ChunkHandle	 ChunkArrayCreate(
        MemHandle 	mh,	/* Handle of LMem heap's block */
        word	elementSize,	/* Size of each element (or zero if elements are
			 * variable-sized) */

        word	headerSize,	/* Amount of chunk to use for header (or zero for
		 	 * default size) */

        ObjChunkFlags ocf);

This routine sets up a chunk array in the specified LMem heap. The heap must have already been initialized normally. The routine allocates a chunk and sets up a chunk array in it. It returns the chunk's handle. If it cannot create the chunk array, it returns a null handle.

If the chunk array will have uniform-size elements, you must specify the element size when you create the chunk array. You will not be able to change this. If the array will have variable-sized elements, pass an element size of zero.

The chunk array always begins with a ChunkArrayHeader . You can specify the total header size; this is useful if you want to begin the chunk array with a special header containing some extra data. However, the header must be large enough to accommodate a ChunkArrayHeader , which will begin the chunk. If you define a header structure, make sure that its first element is a ChunkArrayHeader . Only the chunk array code should access the actual ChunkArrayHeader . If you pass a headerSize of zero, the default header size will be used (namely, sizeof(ChunkArrayHeader) ). If you pass a non-zero headerSize , any space between the ChunkArrayHeader and the heap will be zero-initialized.

To free a chunk array, call LMemFree() as you would for any chunk.

Include: chunkarr.h

Be Sure To: Lock the LMem heap's block on the global heap (unless it is fixed).

Warnings: Results are unpredictable if you pass a non-zero headerSize argument which is smaller than sizeof(ChunkArrayHeader) . Since the routine allocates a chunk, it can cause heap compaction or resizing; all pointers to within the block are invalidated.

ChunkArrayCreateAt()

ChunkHandle 	ChunkArrayCreateAt(
        optr	array,	/* Create chunk array in this chunk */
        word	elementSize,	/* Size of each element (or zero if elements are
			 * variable-sized) */

        word	headerSize,	/* Amount of chunk to use for header (or zero for
			 * default size) */

        ObjChunkFlags ocf);

This routine is exactly like ChunkArrayCreate() , except that you specify the chunk which will be made into a chunk array. The chunk is specified with an optr. Note that any data already existing in the chunk will be overwritten.

Warnings: The chunk may be resized, which invalidates all pointers to within the LMem heap.

Include: chunkarr.h

ChunkArrayCreateAtHandles()

ChunkHandle 	ChunkArrayCreateAtHandles(
        MemHandle 		mh,
        ChunkHandle 		ch,
        word		elementSize,
        word		headerSize,
        ObjChunkFlags		ocf);

This routine is exactly like ChunkArrayCreate() , except that the chunk is specified with its global and chunk handles instead of with an optr.

Tips and Tricks: If you pass a null chunk handle, a new chunk will be allocated.

Warnings: The chunk may be resized, which would invalidate all pointers to within the LMem heap.

Include: chunkarr.h