Memory Management: 3.7 Using Global Memory: Retrieving Block Information

| Up: GEOS SDK TechDocs | Up | Prev: 3.6 Data-Access Synchronization | Next: 3.8 The Reference Count 
MemDeref(), MemPtrToHandle(), MemGetInfo(), MemOwner(), MemModifyFlags(), HandleModifyOwner(), MemModifyOtherInfo()

GEOS offers several routines to retrieve and change information about a block. Each of these routines has a full entry in the Routine Reference Book.

MemDeref() is passed the handle of a block on the global heap; it returns the block's address on the global heap. As noted above, this routine is useful when you allocate a fixed or locked block. If the block has been discarded, it returns a null pointer.

MemPtrToHandle() , passed a pointer to a locked block, finds the handle of that memory block.

MemGetInfo() is a general-purpose block information routine. It is passed two arguments: the handle of the block, and a member of the MemGetInfoType enumerated type. The return value is always word-length; however, its significance depends on the MemGetInfoType value passed:

MGIT_SIZE
Returns the size of the memory block (in bytes).
MGIT_FLAGS_AND_LOCK_COUNT
Upper byte is the number of locks on the block; lower eight bits are the block's HeapFlags record (see HF_FIXED The block will not move from its place in the global heap until it is freed. If this flag is off, the memory manager may move the block when it is unlocked. If it is on, the block may not be locked. This flag cannot be changed after the ).
MGIT_OWNER_OR_VM_FILE_HANDLE
If the block is attached to a GEOS Virtual Memory file, MemGetInfo() returns the VM file handle. Otherwise, it returns the GeodeHandle of the owning thread.
The MemOwner() routine also returns the owning geode of the passed block; however, if the block belongs to a VM file, the file's owner will be returned instead of the file handle.
MGIT_ADDRESS
Returns the block's segment address, if it is on the global heap; otherwise, it returns zero. If the block is resized or is not locked, the address may change without warning. Note that the segment address is returned as a word, not as a pointer; this is of limited utility in C.
MGIT_OTHER_INFO
Returns the HM_otherInfo word from the block's handle table entry. The usage of this word varies depending on the block's nature; for example, object blocks store the handle of their burden thread here.
MGIT_EXEC_THREAD
This is useful for object blocks only. Returns the handle of the thread executing methods for objects in the block.

MemModifyFlags() is used to change a block's HeapFlags record. It takes three arguments: The handle of the block, the HeapFlags to turn on, and the HeapFlags to clear. It returns nothing. Not all HeapFlags can be changed after a block is created; only HF_SHARABLE, HF_DISCARDABLE, HF_SWAPABLE, and HF_LMEM can be so changed.

HandleModifyOwner() changes the geode owning a given block. It takes two arguments, namely the handle of the block and the handle of the new owner. It returns nothing. If the block is not sharable, only the owner of a block can change the block's owner.

MemModifyOtherInfo() changes the HM_otherInfo word of the block's handle table entry. It takes two arguments: The handle of the block, and one word of data to store in the HM_otherInfo field. It returns nothing.

| Up: GEOS SDK TechDocs | Up | Prev: 3.6 Data-Access Synchronization | Next: 3.8 The Reference Count