MemThreadGrab()

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

MemThreadGrab() is used in conjunction with MemThreadGrabNB() and MemThreadRelease() to maintain data-access synchronization. If several threads will all have access to the same global memory block, they should use data-acess synchronization routines to make sure that their activities do not conflict. If a thread uses MemThreadGrab() and no other thread has grabbed the block in question, the routine will increment the "grab count," lock the block, and return its address. It can do this even if the calling thread has already grabbed the block. If another thread has grabbed the block, MemThreadGrab() will put the calling thread in a queue to get the block; the thread will sleep until it gets the block, then MemThreadGrab() will grab the block, lock it, and return its address.

If the block has been discarded, MemThreadGrab() grabs the block and returns a null pointer; you can then reallocate memory for the block.

Include: heap.h

Be Sure To: Make sure that all threads using the block use the MemThread...() routines to access it (not other data-acess synchronization routines). Do not change the HM_otherInfo word of the block's handle table entry (the routines use that word as a semaphore).

Warnings: If you try to grab a block which is owned by a different geode and is non-sharable, the routine will fatal-error.

Never Use Situations:
Never use MemThreadGrab() with a fixed block. It will try to lock the block, and fixed blocks cannot be locked. If you need data-access synchronization for a fixed block, use the HandleP() and HandleV() routines.

See Also: MemThreadGrabNB(), MemThreadRelease().

MemThreadGrabNB()

void	* MemThreadGrabNB(
        MemHandle		mh); /* handle of block to grab */

This is a data-synchronization routine to be used in conjunction with MemThreadGrab() and MemThreadRelease() . It is exactly the same as MemThreadGrab() , except that if it cannot grab the global memory block because another thread has it, the routine returns an error instead of blocking.

If successful, MemThreadGrabNB() returns a pointer to the block. If the block has been discarded, it grabs the block and returns a null pointer; you can then reallocate memory for the block. If the block has been grabbed by another thread, MemThreadGrab() returns the constant BLOCK_GRABBED.

Include: heap.h

Tips and Tricks: 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.

Warnings: If you try to grab a block that is owned by a different geode and is non-sharable, the routine will fatal-error.

Never Use Situations:
Never use MemThreadGrabNB() with a fixed block. It will try to lock the block, and fixed blocks cannot be locked. If you need synchronization for a fixed block, use the HandleP() and HandleV() routines.

See Also: MemThreadGrab(), MemThreadRelease().

MemThreadRelease()

void	MemThreadRelease(
        MemHandle		mh); /* handle of locked block to release */

Use this routine to release a global memory block which you have grabbed with MemThreadGrab() or MemThreadGrabNB() . The routine decrements the grab count; if the grab count reaches zero, the routine unlocks the block.

Include: heap.h

Be Sure To: Make sure that all threads using the block use the MemThread...() routines to access the block (not other data-access synchronization routines). Do not change the HM_otherInfo word of the block's handle table entry (the routines use that word as a semaphore). Make sure to release the block once for every time you grab it; the block is not unlocked until each of your grabs is released.

Warnings: If you try to release a block that you have not successfully grabbed, the routine will fatal-error.

See Also: MemThreadGrab(), MemThreadGrabNB().