| GEOS SDK TechDocs | | MemDowngradeExclLock() ... | MemModifyFlags() ...

---

MemLock()

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

This routine locks a global memory block on the global heap. If the block is swapped, the memory manager swaps it back into the global heap; it then increments the lock count (up to a maximum of 255). The block will not be moved, swapped, or discarded until the lock count reaches zero. This routine returns a pointer to the start of the block, or a null pointer if block has been discarded. To get the address of a block without locking it, use MemDeref() .

Include: heap.h

Warnings: If you try to lock a bad handle, the routine may fatal-error. This routine does not check for synchronization problems; if the block is used by several threads, you should use the synchronization routines.

Never Use Situations:
Never lock a fixed block.

See Also: MemDeref().

MemLockExcl()

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

If several different threads will be accessing the same global memory block, they should use data-access synchronization routines. MemLockExcl() belongs to one such set of routines. Often, several threads will need access to the same block; however, most of the time, they will not need to change the block. There is no synchronization problem if several threads read the same block at once, as long as none of them alters the block (by resizing it, writing to it, etc.) However, if a thread needs to change a block, no other thread should have access at that time.

The routines MemLockExcl() , MemLockShared() , MemUnlockShared() , and MemUnlockExcl() take advantage of this situation. They maintain a queue of threads requesting access to a block. When the block is not being used, they awaken the highest priority thread on the queue. If that thread requested exclusive access, the other threads sleep until it relinquishes access (via MemUnlockExcl() ). If it requested shared access, the routines awaken every other thread which requested shared access; the other threads on the queue will sleep until every active thread relinquishes access (via MemUnlockShared() ).

MemLockExcl() requests exclusive access to the block. If the block is not being accessed, the routine will grab exclusive access for the block, lock the block, and return the block's address. If the block is being accessed, the routine will sleep on the queue until it can get access; it will then awaken, lock the block, and return its address.

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 routines accessing the block get access with MemLockExcl() or MemLockShared() . The routines use the block's HM_otherInfo word; you must not alter it. When you are done accessing the block, make sure to relinquish access by calling MemUnlockExcl() .

Warnings: If a thread calls MemLockExcl() when it already has shared or exclusive access, it will deadlock; it will sleep until access is relinquished, but it cannot relinquish access while it is sleeping. 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 MemLockExcl() or MemLockShared() on a fixed block. It will attempt to lock the block, and fixed blocks cannot be locked. Instead, use the HandleP() and HandleV() routines.

See Also: MemLockShared(), MemUnlockExcl(), MemUnlockShared().

MemLockFixedOrMovable()

void	* MemLockFixedOrMovable(
        void	* ptr);		/* virtual segment */

Given a virtual segment, this routine locks it (if it was movable). A virtual segment is an opaque pointer to a block that an application views as locked or fixed--the memory manager can actually swap locked or fixed blocks and will designate them as virtual segments.

Include: heap.h

MemLockShared()

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

MemLockShared() requests shared access to the passed block. If the block is not being accessed, or if it is held for shared access and the queue is empty, the routine gets access, locks the block, and returns the block's address. Otherwise it sleeps on the queue until the shared requests are awakened; it then locks the block and returns the block's address.

Include: heap.h

Be Sure To: Make sure that all routines accessing the block get access with MemLockExcl() or MemLockShared() . The routines use the block's HM _otherInfo word; you must not alter it. When you are done accessing the block, make sure to relinquish access by calling MemUnlockExcl() .

Warnings: If a thread calls MemLockShared() when it already has exclusive access, it will deadlock; it will sleep until access is relinquished, but it cannot relinquish access while it is sleeping. The thread must be careful not to take actions which could change the block, such as resizing it or writing to it. The routine will not enforce this. 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 MemLockExcl() or MemLockShared() on a fixed block. It will attempt to lock the block, and fixed blocks cannot be locked. Instead, use the HandleP() and HandleV() routines.

See Also: MemLockExcl(), MemUnlockExcl(), MemUnlockShared().