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

---

ArrayQuickSort()

void	ArrayQuickSort(
        void	*array,	/* Pointer to start of array */
        word	count,	/* Number of elements in array */
        word	elementSize,	/* Size of each element (in bytes) */
        word	valueForCallback, 		/* Passed to callback routine */
        QuickSortParameters *parameters);

This routine sorts an array of uniform-sized elements. It uses a modified QuickSort algorithm, using an insertion sort for subarrays below a certain size. The routine calls a callback routine to actually compare elements.

ArrayQuickSort() is passed five arguments: A pointer to the first element of the array, the number of elements in the array, the size of each element in bytes, a word of data (which is passed to all callback routines), and a pointer to a QuickSortParameters structure.

Before ArrayQuickSort() examines or changes any element, it calls a locking routine specified by the QuickSortParameters structure. This routine locks the element, if necessary, and takes any necessary prepatory steps. Similarly, after ArrayQuickSort() is finished with a routine, it calls an unlocking routine in the QuickSortParameters . Each of these routines is passed a pointer to the element and the word of callback data which was passed to ArrayQuickSort() .

The sort routine does not compare elements. Rather, it calls a comparison callback routine specified by the QuickSortParameters . This callback routine should be declared _pascal. Whenever ArrayQuickSort() needs to compare two elements, it calls the callback routine, passing the addresses of the elements and the valueForCallback word which was passed to ChunkArraySort() . The callback routine's return value determines which element will come first in the sorted array:

• If element el1 ought to come before el2 in the sorted array, the callback routine should return a negative integer.
• If element el1 ought to come after el2 in the sorted array, the callback routine should return a positive integer.
• If it doesn't matter whether el1 comes before or after el2 in the array, the callback routine should return zero.

Include: chunkarr.h

Tips and Tricks: You may need to sort an array based on different criteria at different times. The simplest way to do this is to write one general-purpose callback routine and have the valueForCallback word determine how the sort is done. For example, the same callback routine could sort the array in ascending or descending order, depending on the valueForCallback .

Be Sure To: Lock the array on the global heap (unless it is in fixed memory).

Warnings: Do not have the callback routine do anything which might invalidate pointers to the array. For example, if the array is in a chunk, do not resize the chunks or allocate other chunks in the same LMem heap.

See Also: QuickSortParameters, ChunkArraySort().

BlockFromTransferBlockID

VMBlockHandle BlockFromTransferBlockID(id);
        TransferBlockID	 	id;

This macro extracts the VMBlockHandle from a TransferBlockID .

BlockIDFromFileAndBlock

TransferBlockID BlockIDFromFileAndBlock(file, block);
        VMFileHandle 		file;
        VMBlockHandle 		block;

This macro creates the dword type TransferBlockID from a VMFileHandle and a VMBlockHandle.

bsearch()

extern void *_pascal bsearch(
        const void 		*key, 
        const void 		*array,
        word 		count, 
        word 		elementSize,
        PCB(int, compare, (const void *, const void *)));

This is a standard binary search routine. The callback routine must be declared _pascal.

calloc()

void *	calloc(
        word		n,			/* number of structures to allocate */
        size_t		size);			/* size of each structure in bytes */

The malloc() family of routines is provided for Standard C compatibility. If a geode needs a small amount of fixed memory, it can call one of the routines. The kernel will allocate a fixed block to satisfy the geode's malloc() requests; it will allocate memory from this block. When the block is filled, it will allocate another fixed malloc-block. When all the memory in the block is freed, the memory manager will automatically free the block.

When a geode calls calloc() , it will be allocated a contiguous section of memory large enough for the specified number of structures of the specified size. The memory will be allocated out of its malloc-block, and the address of the start of the memory will be returned. The memory will be zero-initialized. If the request cannot be satisfied, calloc() will return a null pointer. The memory is guaranteed not to be moved until it is freed (with free() ) or resized (with realloc() ). When GEOS shuts down, all fixed blocks are freed, and any memory allocated with calloc() is lost.

Tips and Tricks: You can allocate memory in another geode's malloc-block by calling GeoMalloc() . However, that block will be freed when the other geode exits.

Be Sure To: Request a size small enough to fit in a malloc-block; that is, the size of the structure times the number of structures requested must be somewhat smaller than 64K.

Warnings: All memory allocated with calloc() is freed when GEOS shuts down.

See Also: malloc(), free(), GeoMalloc(), realloc().