HandleV()

void	HandleV(
        MemHandle		mh);		/* Handle of block to grab */

HandleV() is part of a set of synchronization routines. If several different threads will be accessing the same global memory block, they need to make sure their activities will not conflict. The way they do that is to use synchronization routines to get control of a block. HandleV() is part of one set of synchronization routines.

If a block is being accessed via these synchronization routines, then a thread will not access a block until it has "grabbed" it with HandleP() or MemPLock() . When a thread is done with the block, it can release it for use by the other threads by calling HandleV() . Note that HandleV() does not unlock the block; it just changes the block's semaphore so other threads can grab it.

Include: heap.h

Tips and Tricks: If you need to unlock the thread just before releasing it, use the routine MemUnlockV() , which first unlocks the thread, and then calls HandleV() to release it. You can find out if the block is being accessed by looking at the HM_otherInfo word (with MemGetInfo() ). If HM_otherInfo equals one, the block is not grabbed; if it equals zero, it is grabbed, but no threads are queued; otherwise, it equals the handle of the first thread queued.

Be Sure To: Make sure that all threads accessing the block use HandleP() or MemPLock() to access the thread. The routines use theHM_otherInfo field of the handle table entry; do not alter this field.

Warnings: Do not use this on a block unless you have grabbed it. The routine does not check to see that you have grabbed the thread; it just clears the semaphore and returns.

See Also: MemThreadGrab(), MemThreadGrabNB(), MemThreadRelease(), HandleV(), HandleP(), MemPLock(), MemUnlockV().

HelpSendHelpNotification()

void 	HelpSendHelpNotification(
        word 		HelpType, 
        const char 		*contextname, 
        const char 		*filename);

Use this routine to bring up on-line help on the fly or to dynamically change the context presently showing in on-line help.

HugeArrayAppend()

dword	HugeArrayAppend(
        VMFileHandle		file,
        VMBlockhandle		vmBlock,				/* Handle of directory block */
        word		numElem,				/* # of elements to add to end of 
						 * array */

        const void *		initData);				/* Copy into new element(s) */

This routine appends one or more elements to a Huge Array. If initData is a null pointer, the elements will be uninitialized.

If the Huge Array contains variable sized elements, this routine will append a single element; this element will be numElem bytes long. The single element will be initialized to hold initData .

If the Huge Array contains constant-sized elements, then initData will be treated as an array of element-sized structures. initData [0] will be the initial value of the first element, initData [1] will be the initial value of the second, and so on.

The return value is the element number of the element added. If more than one element was added; this will be the number of the first element added.

Include: hugearr.h

HugeArrayCompressBlocks()

void	HugeArrayCompressBlocks(
        VMFileHandle		vmFile,			/* File containing Huge Array */
        VMBlockHandle		vmBlock);			/* handle of directory block */

This routine compacts a Huge Array, resizing every block to be just as large as necessary to accommodate its elements. It does not change any of the data in the Huge Array.

Include: hugearr.h

HugeArrayContract()

word	HugeArrayContract(
        void **		elemPtr,				/* **elemPtr is first element to
 						 * delete */

        word		numElem);				/* # of elements to delete */

Delete a number of elements starting at an address in a Huge Array. The routine will fix up the pointer so it points to the first element after the deleted elements. The routine automatically locks and unlocks Huge Array blocks as necessary.

Include: hugearr.h

HugeArrayCreate()

VMBlockhandle 	HugeArrayCreate(
        VMFileHandle		vmFile,				/* Create in this VM file */
        word		elemSize,				/* Pass zero for variable-size
						 * elements */

        word		headerSize);				/* Pass zero for default header */

This routine creates and initializes a Huge Array in the specified file. It returns the handle of the Huge Array's directory block.

Include: hugearr.h

HugeArrayDelete()

void	HugeArrayDelete(
        VMFileHandle		vmFile,
        VMBlockHandle		vmBlock,			/* handle of directory block */
        word		numElem,			/* # of elements to delete */
        dword		elemNum);			/* Index of first element to delete */

This routine deletes one or more elements from a Huge Array. It contracts and frees blocks as necessary.

Include: hugearr.h

HugeArrayDirty()

void	HugeArrayDirty(
        const void *		elemPtr);				/* Element in dirty block */

This routine marks a block in a Huge Array as dirty. The routine is passed a pointer to anywhere in a dirty element; that element's block will be dirtied.

Include: hugearr.h

Warnings: Be sure to call this routine before you unlock the element; otherwise, the block may be discarded before you can dirty it.