| GEOS SDK TechDocs | | GSSetSubscriptAttr() ... | HandleV() ...

---

HAL_COUNT()

word	HAL_COUNT(
        dword	val);

This macro is provided for use with HugeArrayLock() . It extracts the lower word of the HugeArrayLock() return value. This is the number of elements in the Huge Array block after the locked one (counting that locked one).

HAL_PREV

word	HAL_PREV(
        dword	val);

This macro is provided for use with HugeArrayLock() . It extracts the upper word of the HugeArrayLock() return value. This is the number of elements in the Huge Array block before the locked one (counting that locked one).

HandleModifyOwner()

void	HandleModifyOwner(
        MemHandle		mh,			/* Handle of block to modify */
        GeodeHandle		owner);			/* Handle of block's new owner */

This routine changes the owner of the indicated global memory block. Note that this routine can be called only by a thread belonging to the block's original owner; that is, you can only use this routine to transfer ownership of a block from yourself to some other geode.

Include: heap.h

Never Use Situations:
Never use this unless the block already belongs to you and you are giving up ownership.

See Also: MemGetInfo(), MemModifyFlags(), MemModifyOtherInfo().

HandleP()

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

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. HandleP() is part of one set of synchronization routines.

If the threads are using this family of routines, then whenever a thread needs access to the block in question, it can call HandleP() . This routine checks whether any thread has grabbed the block with HandleP() (or MemPLock() ). If no thread has the block, it grabs the block for the calling thread and returns (it does not lock the block on the global heap). If a thread has the block, HandleP() puts the thread on a priority queue and sleeps. When the block is free for it to take, it awakens, grabs the block, and returns.When the thread is done with the block, it should release it with MemUnlockV() or HandleV() .

Include: heap.h

Tips and Tricks: If you will be locking the block after you grab it, use the routine MemPLock() (which calls HandleP() and then locks the block with MemLock() ). 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() and/or MemPLock() to access the block. The routines use the HM_otherInfo field of the handle table entry; do not alter this field. Release the block with HandleV() or MemUnlockV() when you are done with it.

Warnings: If a thread calls HandleP() when it already has control of the block, it will deadlock; HandleP() will put the thread to sleep until the thread releases the block, but the thread will not be able to release the block because it's sleeping. MemThreadGrab() avoids this conflict. If you try to grab a non-sharable block owned by another thread, HandleP() will fatal-error.

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

HandleToOptr()

optr	HandleToOptr(
        Handle 	han;

This macro casts any handle to an optr, leaving the chunk handle portion of the resultant optr to be zero.

See Also: ConstructOptr(), OptrToHandle(), OptrToChunk().