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

---

MemAlloc()

MemHandle MemAlloc(
        word		byteSize,				/* Size of block in bytes */
        HeapFlags		hfFlags,				/* Type of block */
        HeapAllocFlags		haFlags);				/* How to allocate block */

This routine allocates a global memory block and creates an entry for it in the global handle table. The properties of the block are determined by the HeapFlags record passed; the way the block should be allocated is determined by the HeapAllocFlags record. Both sets of flags are described below. The routine returns the block's handle. If it could not allocate the block, it returns a null handle. The block allocated may be larger than the size requested, as the block size is rounded up to the next even paragraph (one paragraph equals sixteen bytes).

HeapFlags are stored in the block's handle table entry. They can be retrieved with the routine MemGetInfo() ; some of them can be changed with the routine MemModifyFlags() . The following flags are available:

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 while it is unlocked. If the flag is on, the block may not be locked, and HF_DISCARDABLE and HF_SWAPABLE must be off.

HF_SHARABLE

The block may be locked by threads belonging to geodes other than the block's owner.

HF_DISCARDABLE

The block may be discarded when unlocked.

HF_SWAPABLE

The block may be swapped to extended/expanded memory or to the disk swap space when it is unlocked.

HF_LMEM

The block contains a local memory heap. This flag is set automatically by LMemInitHeap() and VMAllocLMem() ; applications should not need to set this flag.

HF_DISCARDED

The memory manager turns this bit on when it discards a block. The bit is turned off when the block is reallocated.

HF_SWAPPED

The memory manager turns this bit on when it swaps a block to extended/expanded memory or to the disk swap space. It turns the bit off when it swaps the block back into the global heap.

HeapAllocFlags indicate how the block should be allocated and initialized. They are not stored and can not be retrieved. Some of the flags can be passed with MemReAlloc() . The following flags are available:

HAF_ZERO_INIT

The memory manager should initialize the block to null bytes. This flag may be passed to MemReAlloc() to cause new memory to be zero-initialized.

HAF_LOCK

The memory manager should lock the block after allocating it. To get the block's address, call MemDeref() . This flag may be passed to MemReAlloc() .

HAF_NO_ERR

The memory manager should not return errors. If it cannot allocate block, GEOS will crash. Use of this flag is strongly discouraged. This flag may be passed to MemReAlloc() .

HAF_UI

If both HAF_OBJECT_RESOURCE and HAF_UI are set, this block will be run by the application's UI thread.

HAF_READ_ONLY

The block's data will not be modified. Useful for the debugger.

HAF_OBJECT_RESOURCE

This block will be an object block.

HAF_CODE

This block contains executable code.

HAF_CONFORMING

If the block contains code, the code may be run by a less privileged entity. If the block contains data, the data may be accessed or altered by a less privileged entity.

If necessary, this routine will automatically compact the heap to find enough space to allocated the desired sized block.

Include: heap.h

See Also: MemAllocSetOwner(), MemReAlloc(), MemDeref().

MemAllocLMem()

MemHandle MemAllocLMem(
        LMemType		type,				/* type of LMem block */
        word		headerSize);				/* size of header structure */

This routine allocates and initializes a local memory block; it can be used to simplify this procedure from the two-step process of MemAlloc() followed by LMemInitHeap() . Pass an LMem type indicating what will be stored in the block, along with the size of the header structure to use. If the block is to have the standard header, pass zero in headerSize .

This routine returns the handle of the unlocked, newly allocated block. The block will contain two LMem handles and 64 bytes allocated for the LMem heap.

Include: lmem.h

See Also: LMemInitHeap().

MemAllocSetOwner()

MemHandle MemAllocSetOwner(
        GeodeHandle		owner,				/* Handle of block's owner */
        word		byteSize,				/* Size of block in bytes */
        HeapFlags		hfFlags,				/* Type of block */
        HeapAllocFlags		haFlags);				/* How to allocate block */

This routine is the same as MemAlloc() except that you can specify the owner of the global memory block created.

Include: heap.h

See Also: MemAlloc().

MemDecRefCount()

void	MemDecRefCount(
        MemHandle		mh);				/* handle of affected block */

This routine decrements the reference count of a global memory block (the reference count is stored in HM _otherInfo ). If the reference count reaches zero, MemDecRefCount() will free the block.

Warnings: This routine assumes that a reference count is stored in HM _otherInfo . You may only use this routine if the block has had a reference count set up with MemInitRefCount() .

Include: heap.h

MemDeref()

void	* MemDeref(
        MemHandle		mh);		/* Handle of locked block to dereference */

This routine takes one argument, the handle of a global memory block; it returns the address of the block on the global heap. If the block has been discarded, or if the handle is not a memory handle, it returns a null pointer. It gets this information by reading the block's handle table entry; it does not need to actually access the block.

Note that if the handle is of an unlocked, moveable block, MemDeref() will return the block's address with out any warning; however, the address will be unreliable, since the memory manager can move the block at any time.

Include: heap.h

Tips and Tricks: This is very useful when you allocate a fixed or locked block, and need to get the block's address without calling MemLock() .

Warnings: This routine, if given an unlocked, moveable block, will return the pointer without a warning, even though that block may move at any time.

See Also: MemGetInfo(), MemModifyFlags().