MemModifyFlags()

void	MemModifyFlags(
        MemHandle		mh,					/* Handle of block to modify */
        HeapFlags		bitsToSet,					/* HeapFlags to turn on */
        HeapFlags		bitsToClear);					/* HeapFlags to turn off */

MemModifyFlags() changes the HeapFlags record of the global memory block specified. Not all flags can be changed after the block is created; only the flags HF_SHARABLE, HF_DISCARDABLE, HF_SWAPABLE, and HF_LMEM can be changed.

The routine uses the handle table entry of the block specified; it does not need to look at the actual block. The routine performs normally whether or not the block is locked, fixed, or discarded.

Include: heap.h

Warnings: If the handle is not a global memory handle, results are unpredictable; the routine will change inappropriate bits of the handle table entry.

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

MemModifyOtherInfo()

void	MemModifyOtherInfo(
        MemHandle		mh,				/* Handle of block to modify */
        word		otherInfo);				/* New value of HM_otherInfo word */

Use this routine to change the value of the global memory block's HM_otherInfo word. Some blocks need this word left alone; for example, data-access synchronization routines use this word. Object blocks use this space to store the handle of the burden thread.

Include: heap.h

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

MemPLock()

void	* MemPLock(
        MemHandle		mh);		/* Handle of block to lock */

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

If the threads are using the MemPLock() family, then whenever a thread needs access to the block in question, it can call MemPLock() . This routine calls HandleP() to get control of the block; it then locks the block and returns its address. If the block has been discarded, it grabs the block and returns a null pointer; you can then reallocate the block. When the thread is done with the block, it should release it with MemUnlockV() .

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.

Be Sure To: Make sure that all threads accessing the block use MemPLock() and/or HandleP() to grab the block. These routines use the HM_otherInfo field of the block's 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 MemPLock() when it already has control of the block, it will deadlock. MemThreadGrab() avoids this conflict. If you try to grab a non-sharable block owned by another thread, MemPLock() will fatal-error.

Never Use Situations:
Never use MemPLock() with a fixed block. It will try to lock the block, and fixed blocks cannot be locked. Instead, use HandleP() .

See Also: HandleP(), MemUnlockV(), HandleV().

MemReAlloc()

MemHandle 	MemReAlloc(
        MemHandle		mh,					/* Handle of block */
        word		byteSize,					/* New size of the block */
        HeapAllocFlags		heapAllocFlags);					/* How to reallocate block */

This routine reallocates a global memory block. It can be used to resize a block; it can also be used to reallocate memory for a discarded block. Locked and fixed blocks can be reallocated; however, they may move on the global heap, so all pointers within the block must be adjusted. Note, however, that if the new size is smaller than the old size, the block is guaranteed not to move. The reallocated block may be larger than the size requested, as the block size is rounded up to the next even paragraph (one paragraph equals sixteen bytes). If you request that the block be expanded, but this is impossible, then the routine will return NullHandle.

The routine is passed a record of HeapAllocFlags . Only the flags HAF_ZERO_INIT, HAF_LOCK, and HAF_NO_ERR may be passed.

If necessary, the routine will automatically compact the heap.

Include: heap.h

Warnings: If HAF_LOCK is passed, the lock count will be incremented even if the block is already locked by this thread. The routine does not care whether the block has been locked by another thread (possibly belonging to another geode); thus, if the block is being used by more than one thread, it is important to use the synchronization routines.

See Also: MemAlloc(), MemDeref().

MemModifyFlags()

MemModifyOtherInfo()

MemOwner()

MemPLock()

MemPtrToHandle()

MemReAlloc()