Memory Manager
 

 < Home   < Developers   < Development Support   < Documentation

39 Memory Manager


 Table of Contents  |  < Previous  |  Next >  |  Index
   
   

Title -
Palm OS® Programmer's API Reference

Part II: System Management

39 Memory Manager

Memory Manager Functions

MemCardInfo

MemCmp

MemDebugMode

MemHandleCardNo

MemHandleDataStorage

MemHandleFree

MemHandleHeapID

MemHandleLock

MemHandleNew

MemHandleResize

MemHandleSetOwner

MemHandleSize

MemHandleToLocalID

MemHandleUnlock

MemHeapCheck

MemHeapCompact

MemHeapDynamic

MemHeapFlags

MemHeapFreeBytes

MemHeapID

MemHeapScramble

MemHeapSize

MemLocalIDKind

MemLocalIDToGlobal

MemLocalIDToLockedPtr

MemLocalIDToPtr

MemMove

MemNumCards

MemNumHeaps

MemNumRAMHeaps

MemPtrCardNo

MemPtrDataStorage

MemPtrFree

MemPtrHeapID

MemPtrNew

MemPtrRecoverHandle

MemPtrResize

MemPtrSetOwner

MemPtrSize

MemPtrToLocalID

MemPtrUnlock

MemSet

MemSetDebugMode

MemStoreInfo

       

This chapter provides reference information for the memory manager. The memory manager API is declared in the header file MemoryMgr.h.

For more information on the memory manager, see the chapter "Memory" in the Palm OS Programmer's Companion, vol. I.

Memory Manager Functions

MemCardInfo

Purpose

Return information about a memory card.

Prototype

Err MemCardInfo (UInt16 cardNo, Char* cardNameP, Char* manufNameP, UInt16* versionP, UInt32* crDateP, UInt32* romSizeP, UInt32* ramSizeP, UInt32* freeBytesP)

Parameters

cardNoCard number.
cardNamePPointer to character array (32 bytes), or 0.
manufNamePPointer to character array (32 bytes), or 0.
versionPPointer to version variable, or 0.
crDatePPointer to creation date variable, or 0.
romSizePPointer to ROM size variable, or 0.
ramSizePPointer to RAM size variable, or 0.
freeBytesPPointer to free byte-count variable, or 0.

Result

Returns 0 if no error.

Comments

Pass 0 for those variables that you don't want returned.

MemCmp

Purpose

Compare two blocks of memory.


NOTE: Blocks are compared as unsigned bytes.

Prototype

Int16 MemCmp (const void* s1, const void* s2, Int32 numBytes)

Parameters

s1, s2Pointers to block of memory.
numBytesNumber of bytes to compare.

Result

Zero if they match, non-zero if not:

+ if s1 > s2

- if s1 < s2

Compatibility

Implemented only if 2.0 New Feature Set is present.

MemCmp can be used to test the equality of blocks in memory on all versions that support MemCmp; however, testing the sort ordering of blocks in memory works reliably only on Palm OS® versions 3.5 and higher. On versions earlier than 3.2, MemCmp always returns a positive value if the blocks are unequal. On versions 3.2 and 3.3, MemCmp reliably returns positive to indicate s1 > s2 and negative to indicate s1 < s2 only if the characters that differ are less than 128 apart. If the difference is greater than that, MemCmp may return positive when it should return negative and vice versa.

MemDebugMode

Purpose

Return the current debugging mode of the memory manager.

Prototype

UInt16 MemDebugMode (void)

Parameters

No parameters.

Result

Returns debug flags as described for MemSetDebugMode.

MemHandleCardNo

Purpose

Return the card number a chunk resides in.

Prototype

UInt16 MemHandleCardNo (MemHandle h)

Parameters

-> hChunk handle.

Result

Returns the card number.

Comments

Call this routine to retrieve the card number (0 or 1) a movable chunk resides on.

See Also

MemPtrCardNo

MemHandleDataStorage

Purpose

Return true if the given handle is part of a data storage heap. If not, it's a handle in the dynamic heap.

Prototype

Boolean MemHandleDataStorage (MemHandle h)

Parameters

-> hChunk handle.

Result

Returns true if the handle is part of a data storage heap.

Comments

Called by Fields package routines to determine if they need to worry about data storage write-protection when editing a text field.

See Also

MemPtrDataStorage

MemHandleFree

Purpose

Dispose of a movable chunk.

Prototype

Err MemHandleFree (MemHandle h)

Parameters

-> hChunk handle.

Result

Returns 0 if no error, or memErrInvalidParam if an error occurs.

Comments

Call this routine to dispose of a movable chunk.

See Also

MemHandleNew

MemHandleHeapID

Purpose

Return the heap ID of a chunk.

Prototype

UInt16 MemHandleHeapID (MemHandle h)

Parameters

-> hChunk handle.

Result

Returns the heap ID of a chunk.

Comments

Call this routine to get the heap ID of the heap a chunk resides in.

See Also

MemPtrHeapID

MemHandleLock

Purpose

Lock a chunk and obtain a pointer to the chunk's data.

Prototype

MemPtr MemHandleLock (MemHandle h)

Parameters

-> hChunk handle.

Result

Returns a pointer to the chunk.

Comments

Call this routine to lock a chunk and obtain a pointer to the chunk.

MemHandleLock and MemHandleUnlock should be used in pairs.

See Also

MemHandleNew, MemHandleUnlock

MemHandleNew

Purpose

Allocate a new movable chunk in the dynamic heap and returns a handle to it.

Prototype

MemHandle MemHandleNew (UInt32 size)

Parameters

-> sizeThe desired size of the chunk.

Result

Returns a handle to the new chunk, or 0 if unsuccessful.

Comments

Use this call to allocate dynamic memory. Before you can write data to the memory chunk that MemHandleNew allocates, you must call MemHandleLock to lock the chunk and get a pointer to it.

See Also

MemPtrFree, MemPtrNew, MemHandleFree, MemHandleLock

MemHandleResize

Purpose

Resize a chunk.

Prototype

Err MemHandleResize (MemHandle h, UInt32 newSize)

Parameters

-> hChunk handle.
-> newSizeThe new desired size.

Result

0No error.
memErrInvalidParamInvalid parameter passed.
memErrNotEnoughSpaceNot enough free space in heap to grow chunk.
memErrChunkLockedCan't grow chunk because it's locked.

Comments

Call this routine to resize a chunk. This routine is always successful when shrinking the size of a chunk, even if the chunk is locked. When growing a chunk, it first attempts to grab free space immediately following the chunk so that the chunk does not have to move. If the chunk has to move to another free area of the heap to grow, it must be movable and have a lock count of 0.

On devices running version 2.0 or earlier of Palm OS, the MemHandleResize function tries to resize the chunk only within the same heap, whereas DmResizeRecord will look for space in other data heaps if it can't find enough space in the original heap.

See Also

MemHandleNew, MemHandleSize

MemHandleSetOwner

Purpose

Set the owner ID of a chunk.

Prototype

Err MemHandleSetOwner (MemHandle h, UInt16 owner)

Parameters

-> hChunk handle.
-> ownerNew owner ID of the chunk. Specify 0 to set the owner to the operating system.

Result

Returns 0 if no error, or memErrInvalidParam if an error occurs.

Comments

When you allocate a parameter block to pass to SysUIAppSwitch or SysAppLaunch, you must call MemPtrSetOwner to grant ownership of the parameter block chunk to the OS (your application is originally set as the owner). If the parameter block structure references any chunks by handle, you also must call MemHandleSetOwner to grant ownership of those blocks to the OS. If you don't change the ownership of these chunks, they will get freed before the application you're launching has a chance to use them.

MemHandleSize

Purpose

Return the requested size of a chunk.

Prototype

UInt32 MemHandleSize (MemHandle h)

Parameters

-> hChunk handle.

Result

Returns the requested size of the chunk.

Comments

Call this routine to get the size originally requested for a chunk.

See Also

MemHandleResize

MemHandleToLocalID

Purpose

Convert a handle into a local chunk ID which is card relative.

Prototype

LocalID MemHandleToLocalID (MemHandle h)

Parameters

-> hChunk handle.

Result

Returns local ID, or NULL (0) if unsuccessful.

Comments

Call this routine to convert a chunk handle to a local ID.

See Also

MemLocalIDToGlobal, MemLocalIDToLockedPtr

MemHandleUnlock

Purpose

Unlock a chunk given a chunk handle.

Prototype

Err MemHandleUnlock (MemHandle h)

Parameters

-> hThe chunk handle.

Result

0No error.
memErrInvalidParamInvalid parameter passed.

Comments

Call this routine to decrement the lock count for a chunk.

MemHandleLock and MemHandleUnlock should be used in pairs.

See Also

MemHandleLock

MemHeapCheck

Purpose

Check validity of a given heap.

Prototype

Err MemHeapCheck (UInt16 heapID)

Parameters

heapIDID of heap to check.

Result

Returns 0 if no error.

See Also

MemDebugMode, MemSetDebugMode

MemHeapCompact

Purpose

Compact a heap.

Prototype

Err MemHeapCompact (UInt16 heapID)

Parameters

-> heapIDID of the heap to compact.

Result

Always returns 0.

Comments

Most applications never need to call this function explicitly. The system software calls this function at various times; for example, during memory allocation (if sufficient free space is not available) and during system reboot.

Call this routine to compact a heap and merge all free space. This routine attempts to move all movable chunks to the start of the heap and merge all free space in the center of the heap.

MemHeapDynamic

Purpose

Return true if the given heap is a dynamic heap.

Prototype

Boolean MemHeapDynamic (UInt16 heapID)

Parameters

heapID ID of the heap to be tested.

Result

Returns true if dynamic, false if not.

Comments

Dynamic heaps are used for volatile storage, application stacks, globals, and dynamically allocated memory.


NOTE: In Palm OS 3.5, the dynamic heap is sized based on the amount of memory available, and is generally larger than before.

See Also

MemNumHeaps, MemHeapID

MemHeapFlags

Purpose

Return the heap flags for a heap.

Prototype

UInt16 MemHeapFlags (UInt16 heapID)

Parameters

-> heapIDID of heap.

Result

Returns the heap flags.

Comments

Call this routine to retrieve the heap flags for a heap. The flags can be examined to determine if the heap is ROM based or not. ROM-based heaps have the memHeapFlagReadOnly bit set (the memHeapFlagReadOnly mask has a value of 0x0001).

See Also

MemNumHeaps, MemHeapID

MemHeapFreeBytes

Purpose

Return the total number of free bytes in a heap and the size of the largest free chunk in the heap.

Prototype

Err MemHeapFreeBytes (UInt16 heapID, UInt32* freeP, UInt32* maxP)

Parameters

-> heapIDID of heap.
<-> freePPointer to a variable of type UInt32 for free bytes.
<-> maxPPointer to a variable of type UInt32 for max free chunk size. Do not pass NULL for this argument.

Result

Always returns 0.

Comments

This routine doesn't compact the heap but may be used to determine in advance whether an allocation request will succeed. Before allocating memory, call this function and test the value returned in maxP to determine whether enough free space to fulfill your allocation request exists. If not, you may make more space available by calling the MemHeapCompact function. Note that both MemPtrNew and MemHandleNew automatically compact the heap if necessary.

See Also

MemHeapSize, MemHeapID, MemHeapCompact

MemHeapID

Purpose

Return the heap ID for a heap, given its index and the card number.

Prototype

UInt16 MemHeapID (UInt16 cardNo, UInt16 heapIndex)

Parameters

-> cardNoThe card number, either 0 or 1.
-> heapIndexThe heap index, anywhere from 0 to MemNumHeaps - 1.

Result

Returns the heap ID.

Comments

Call this routine to retrieve the heap ID of a heap, given the heap index and the card number. A heap ID must be used to obtain information on a heap such as its size, free bytes, etc., and is also passed to any routines which manipulate heaps.

See Also

MemNumHeaps

MemHeapScramble

Purpose

Scramble the specified heap.

Prototype

Err MemHeapScramble (UInt16 heapID)

Parameters

heapIDID of heap to scramble.

Comments

The system attempts to move each movable chunk.

Useful for debugging.

Result

Always returns 0.

See Also

MemDebugMode, MemSetDebugMode

MemHeapSize

Purpose

Return the total size of a heap including the heap header.

Prototype

UInt32 MemHeapSize (UInt16 heapID)

Parameters

-> heapIDID of heap.

Result

Returns the total size of the heap.

See Also

MemHeapFreeBytes, MemHeapID

MemLocalIDKind

Purpose

Return whether or not a local ID references a handle or a pointer.

Prototype

LocalIDKind MemLocalIDKind (LocalID local)

Parameters

-> localLocal ID to query

Result

Returns LocalIDKind, or a memIDHandle or memIDPtr (see MemoryMgr.h).

Comments

This routine determines if the given local ID is to a nonmovable (memIDPtr) or movable (memIDHandle) chunk.

MemLocalIDToGlobal

Purpose

Convert a local ID, which is card relative, into a global pointer in the designated card.

Prototype

MemPtr MemLocalIDToGlobal (LocalID local, UInt16 cardNo)

Parameters

-> localThe local ID to convert.
-> cardNoMemory card the chunk resides in.

Result

Returns pointer or handle to chunk.

See Also

MemLocalIDKind, MemLocalIDToLockedPtr

MemLocalIDToLockedPtr

Purpose

Return a pointer to a chunk given its local ID and card number.

If the local ID references a movable chunk handle, this routine automatically locks the chunk before returning.

Prototype

MemPtr MemLocalIDToLockedPtr (LocalID local, UInt16 cardNo)

Parameters

localLocal chunk ID.
cardNoCard number.

Result

Returns pointer to chunk, or 0 if an error occurs.

See Also

MemLocalIDToGlobal, MemLocalIDToPtr, MemLocalIDKind, MemPtrToLocalID, MemHandleToLocalID

MemLocalIDToPtr

Purpose

Return pointer to chunk, given the local ID and card number.

Prototype

MemPtr MemLocalIDToPtr (LocalID local, UInt16 cardNo)

Parameters

-> localLocal ID to query.
-> cardNoCard number the chunk resides in.

Result

Returns a pointer to the chunk, or 0 if error.

Comments

If the local ID references a movable chunk and that chunk is not locked, this function returns 0 to indicate an error.

See Also

MemLocalIDToGlobal, MemLocalIDToLockedPtr

MemMove

Purpose

Move a range of memory to another range in the dynamic heap.

Prototype

Err MemMove (void* dstP, const void* sP, Int32 numBytes)

Parameters

dstPPointer to destination.
sPPointer to source.
numBytesNumber of bytes to move.

Result

Always returns 0.

Comments

Handles overlapping ranges.

For operations where the destination is in a data heap, see DmSet, DmWrite, and related functions.

MemNumCards

Purpose

Return the number of memory card slots in the system. Not all slots need to be populated.

Prototype

UInt16 MemNumCards (void)

Parameters

None.

Result

Returns number of slots in the system.

MemNumHeaps

Purpose

Return the number of heaps available on a particular card.

Prototype

UInt16 MemNumHeaps (UInt16 cardNo)

Parameters

-> cardNoThe card number; either 0 or 1.

Result

Number of heaps available, including ROM- and RAM-based heaps.

Comments

Call this routine to retrieve the total number of heaps on a memory card. The information can be obtained by calling MemHeapSize, MemHeapFreeBytes, and MemHeapFlags on each heap using its heap ID. The heap ID is obtained by calling MemHeapID with the card number and the heap index, which can be any value from 0 to MemNumHeaps.

MemNumRAMHeaps

Purpose

Return the number of RAM heaps in the given card.

Prototype

UInt16 MemNumRAMHeaps (UInt16 cardNo)

Parameters

cardNoThe card number.

Result

Returns the number of RAM heaps.

See Also

MemNumCards

MemPtrCardNo

Purpose

Return the card number (0 or 1) a nonmovable chunk resides on.

Prototype

UInt16 MemPtrCardNo (MemPtr p)

Parameters

-> pPointer to the chunk.

Result

Returns the card number.

See Also

MemHandleCardNo

MemPtrDataStorage

Purpose

Return true if the given pointer is part of a data storage heap; if not, it is a pointer in the dynamic heap.

Prototype

Boolean MemPtrDataStorage (MemPtr p)

Parameters

pPointer to a chunk.

Result

Returns true if the chunk is part of a data storage heap.

Comments

Called by Fields package to determine if it needs to worry about data storage write-protection when editing a text field.

See Also

MemHeapDynamic

MemPtrFree

Purpose

Macro to dispose of a chunk.

Prototype

Err MemPtrFree (MemPtr p)

Parameters

-> pPointer to a chunk.

Result

0If no error or memErrInvalidParam (invalid parameter).

Comments

Call this routine to dispose of a nonmovable chunk.

MemPtrHeapID

Purpose

Return the heap ID of a chunk.

Prototype

UInt16 MemPtrHeapID (MemPtr p)

Parameters

-> pPointer to the chunk.

Result

Returns the heap ID of a chunk.

Comments

Call this routine to get the heap ID of the heap a chunk resides in.

MemPtrNew

Purpose

Allocate a new nonmovable chunk in the dynamic heap.

Prototype

MemPtr MemPtrNew (UInt32 size)

Parameters

-> sizeThe desired size of the chunk.

Result

Returns pointer to the new chunk, or 0 if unsuccessful.

Comments

This routine allocates a nonmovable chunk in the dynamic heap and returns a pointer to the chunk. Applications can use it when allocating dynamic memory.

In Palm OS 3.5, the dynamic heap is sized based on the amount of memory available, and is generally larger than before.


NOTE: You cannot allocate a zero-size reference block.

MemPtrRecoverHandle

Purpose

Recover the handle of a movable chunk, given a pointer to its data.

Prototype

MemHandle MemPtrRecoverHandle (MemPtr p)

Parameters

-> pPointer to the chunk.

Result

Returns the handle of the chunk, or 0 if unsuccessful.

Comments

Don't call this function for pointers in ROM or nonmovable data chunks.

MemPtrResize

Purpose

Resize a chunk.

Prototype

Err MemPtrResize (MemPtr p, UInt32 newSize)

Parameters

-> pPointer to the chunk.
-> newSizeThe new desired size.

Result

Returns 0 if no error, or memErrNotEnoughSpace memErrInvalidParam, or memErrChunkLocked if an error occurs.

Comments

Call this routine to resize a locked chunk. This routine is always successful when shrinking the size of a chunk. When growing a chunk, it attempts to use free space immediately following the chunk.

See Also

MemPtrSize, MemHandleResize

MemPtrSetOwner

Purpose

Set the owner ID of a chunk.

Prototype

Err MemPtrSetOwner (MemPtr p, UInt16 owner)

Parameters

-> pPointer to the chunk.
-> ownerNew owner ID of the chunk. Specify 0 to set the owner to the operating system.

Result

Returns 0 if no error, or memErrInvalidParam if an error occurs.

Comments

When you allocate a parameter block to pass to SysUIAppSwitch or SysAppLaunch, you must call MemPtrSetOwner or MemHandleSetOwner to grant ownership of the parameter block chunk, and any other chunks referenced in it, to the OS (your application is originally set as the owner). If you don't change the ownership of the parameter block, it will get freed before the application you're launching has a chance to use it.

MemPtrSize

Purpose

Return the size of a chunk.

Prototype

UInt32 MemPtrSize (MemPtr p)

Parameters

-> pPointer to the chunk.

Result

The requested size of the chunk.

Comments

Call this routine to get the original requested size of a chunk.

MemPtrToLocalID

Purpose

Convert a pointer into a card-relative local chunk ID.

Prototype

LocalID MemPtrToLocalID (MemPtr p)

Parameters

-> pPointer to a chunk.

Result

Returns the local ID of the chunk.

Comments

Call this routine to convert a chunk pointer to a local ID.

See Also

MemLocalIDToPtr

MemPtrUnlock

Purpose

Unlock a chunk, given a pointer to the chunk.

Prototype

Err MemPtrUnlock (MemPtr p)

Parameters

pPointer to a chunk.

Result

0 if no error, or memErrInvalidParam if an error occurs.

Comments

A chunk must not be unlocked more times than it was locked.

See Also

MemHandleLock

MemSet

Purpose

Set a memory range in a dynamic heap to a specific value.

Prototype

Err MemSet (void* dstP, Int32 numBytes, UInt8 value)

Parameters

dstPPointer to the destination.
numBytesNumber of bytes to set.
valueValue to set.

Result

Always returns 0.

Comments

For operations where the destination is in a data heap, see DmSet, DmWrite, and related functions.

MemSetDebugMode

Purpose

Set the debugging mode of the memory manager.

Prototype

Err MemSetDebugMode (UInt16 flags)

Parameters

flagsDebug flags.

Comments

Use the logical OR operator (|) to provide any combination of one, more, or none of the following flags:

memDebugModeCheckOnChange
memDebugModeCheckOnAll
memDebugModeScrambleOnChange
memDebugModeScrambleOnAll
memDebugModeFillFree
memDebugModeAllHeaps
memDebugModeRecordMinDynHeapFree

Result

Returns 0 if no error, or -1 if an error occurs.

MemStoreInfo

Purpose

Return information on either the RAM store or the ROM store for a memory card.

Prototype

Err MemStoreInfo (UInt16 cardNo, UInt16 storeNumber, UInt16* versionP, UInt16* flagsP, Char* nameP, UInt32* crDateP, UInt32* bckUpDateP, UInt32* heapListOffsetP, UInt32* initCodeOffset1P, UInt32* initCodeOffset2P, LocalID* databaseDirIDP)

Parameters

-> cardNoCard number, either 0 or 1.
-> storeNumberStore number; 0 for ROM, 1 for RAM.
<-> versionPPointer to version variable, or 0.
<-> flagsPPointer to flags variable, or 0.
<-> namePPointer to character array (32 bytes), or 0.
<-> crDatePPointer to creation date variable, or 0.
<-> bckUpDatePPointer to backup date variable, or 0.
<-> heapListOffsetPPointer to heapListOffset variable, or 0.
<-> initCodeOffset1PPointer to initCodeOffset1 variable, or 0.
<-> initCodeOffset2PPointer to initCodeOffset2 variable, or 0.
<-> databaseDirIDPPointer to database directory chunk ID variable, or 0.

Result

Returns 0 if no error, or memErrCardNotPresent, memErrRAMOnlyCard, or memErrInvalidStoreHeader if an error occurs.

Comments

Call this routine to retrieve any or all information on either the RAM store or the ROM store for a card. Pass 0 for variables that you don't wish returned.