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 Function
Purpose
Return information about a memory card.
Declared In
MemoryMgr.h
Prototype
Err MemCardInfo ( UInt16 cardNo, Char *cardNameP, Char *manufNameP, UInt16 *versionP, UInt32 *crDateP, UInt32 *romSizeP, UInt32 *ramSizeP, UInt32 *freeBytesP )
Parameters
-
cardNo
- Card number.
-
cardNameP
- Pointer to character array (32 bytes), or 0.
-
manufNameP
- Pointer to character array (32 bytes), or 0.
-
versionP
- Pointer to version variable, or 0.
-
crDateP
- Pointer to creation date variable, or 0.
-
romSizeP
- Pointer to ROM size variable, or 0.
-
ramSizeP
- Pointer to RAM size variable, or 0.
-
freeBytesP
- Pointer to free byte-count variable, or 0.
Returns
Comments
Pass 0 for those variables that you don't want returned.
MemCmp Function
Purpose
Declared In
MemoryMgr.h
Prototype
Int16 MemCmp ( const void *s1, const void *s2, Int32 numBytes )
Parameters
Returns
Zero if they match, non-zero if not:
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 Function
Purpose
Return the current debugging mode of the memory manager.
Declared In
MemoryMgr.h
Prototype
UInt16 MemDebugMode ( void )
Parameters
Returns
Returns debug flags as described for MemSetDebugMode()
.
MemHandleCardNo Function
Purpose
Return the card number a chunk resides in.
Declared In
MemoryMgr.h
Prototype
UInt16 MemHandleCardNo ( MemHandle h )
Parameters
Returns
Comments
Call this routine to retrieve the card number (0 or 1) a movable chunk resides on.
See Also
MemHandleDataStorage Function
Purpose
Return true
if the given handle is part of a data storage heap. If not, it's a handle in the dynamic heap.
Declared In
MemoryMgr.h
Prototype
Boolean MemHandleDataStorage ( MemHandle h )
Parameters
Returns
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
MemHandleFree Function
Purpose
Declared In
MemoryMgr.h
Prototype
Err MemHandleFree ( MemHandle h )
Parameters
Returns
Returns 0 if no error, or memErrInvalidParam
if an error occurs.
Comments
Call this routine to dispose of a movable chunk.
See Also
MemHandleHeapID Function
Purpose
Return the heap ID of a chunk.
Declared In
MemoryMgr.h
Prototype
UInt16 MemHandleHeapID ( MemHandle h )
Parameters
Returns
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
MemHandleLock Function
Purpose
Lock a chunk and obtain a pointer to the chunk's data.
Declared In
MemoryMgr.h
Prototype
MemPtr MemHandleLock ( MemHandle h )
Parameters
Returns
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 Function
Purpose
Allocate a new movable chunk in the dynamic heap and returns a handle to it.
Declared In
MemoryMgr.h
Prototype
MemHandle MemHandleNew ( UInt32 size )
Parameters
Returns
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 Function
Purpose
Declared In
MemoryMgr.h
Prototype
Err MemHandleResize ( MemHandle h, UInt32 newSize )
Parameters
Returns
-
0
- No error.
-
memErrInvalidParam
- Invalid parameter passed.
-
memErrNotEnoughSpace
- Not enough free space in heap to grow chunk.
-
memErrChunkLocked
- Can'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 Function
Purpose
Declared In
MemoryMgr.h
Prototype
Err MemHandleSetOwner ( MemHandle h, UInt16 owner )
Parameters
-
→
h
- Chunk handle.
-
→
owner
- New owner ID of the chunk. Specify 0 to set the owner to the operating system.
Returns
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.
IMPORTANT: Once you have granted ownership of a memory chunk to the system, do not attempt to free it yourself. The operating system will free it when the application invoked with
SysUIAppSwitch()
or SysAppLaunch()
quits.
MemHandleSize Function
Purpose
Return the requested size of a chunk.
Declared In
MemoryMgr.h
Prototype
UInt32 MemHandleSize ( MemHandle h )
Parameters
Returns
Returns the requested size of the chunk.
Comments
Call this routine to get the size originally requested for a chunk.
See Also
MemHandleToLocalID Function
Purpose
Convert a handle into a local chunk ID which is card relative.
Declared In
MemoryMgr.h
Prototype
LocalID MemHandleToLocalID ( MemHandle h )
Parameters
Returns
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 Function
Purpose
Unlock a chunk given a chunk handle.
Declared In
MemoryMgr.h
Prototype
Err MemHandleUnlock ( MemHandle h )
Parameters
Returns
Comments
Call this routine to decrement the lock count for a chunk.
MemHandleLock
and MemHandleUnlock
should be used in pairs.
See Also
MemHeapCheck Function
Purpose
Check validity of a given heap.
Declared In
MemoryMgr.h
Prototype
Err MemHeapCheck ( UInt16 heapID )
Parameters
Returns
See Also
MemDebugMode()
, MemSetDebugMode()
MemHeapCompact Function
Purpose
Declared In
MemoryMgr.h
Prototype
Err MemHeapCompact ( UInt16 heapID )
Parameters
Returns
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 Function
Purpose
Return true
if the given heap is a dynamic heap.
Declared In
MemoryMgr.h
Prototype
Boolean MemHeapDynamic ( UInt16 heapID )
Parameters
Returns
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
MemHeapFlags Function
Purpose
Return the heap flags for a heap.
Declared In
MemoryMgr.h
Prototype
UInt16 MemHeapFlags ( UInt16 heapID )
Parameters
Returns
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
MemHeapFreeBytes Function
Purpose
Return the total number of free bytes in a heap and the size of the largest free chunk in the heap.
Declared In
MemoryMgr.h
Prototype
Err MemHeapFreeBytes ( UInt16 heapID, UInt32 *freeP, UInt32 *maxP )
Parameters
-
→
heapID
- ID of heap.
-
↔
freeP
- Pointer to a variable of type
UInt32
for free bytes. -
↔
maxP
- Pointer to a variable of type
UInt32
for max free chunk size. Do not passNULL
for this argument.
Returns
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 Function
Purpose
Return the heap ID for a heap, given its index and the card number.
Declared In
MemoryMgr.h
Prototype
UInt16 MemHeapID ( UInt16 cardNo, UInt16 heapIndex )
Parameters
-
→
cardNo
- The card number, either 0 or 1.
-
→
heapIndex
- The heap index, anywhere from 0 to
MemNumHeaps()
- 1.
Returns
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
MemHeapScramble Function
Purpose
Declared In
MemoryMgr.h
Prototype
Err MemHeapScramble ( UInt16 heapID )
Parameters
Comments
The system attempts to move each movable chunk.
Returns
See Also
MemDebugMode()
, MemSetDebugMode()
MemHeapSize Function
Purpose
Return the total size of a heap including the heap header.
Declared In
MemoryMgr.h
Prototype
UInt32 MemHeapSize ( UInt16 heapID )
Parameters
Returns
Returns the total size of the heap.
See Also
MemHeapFreeBytes()
, MemHeapID()
MemLocalIDKind Function
Purpose
Return whether or not a local ID references a handle or a pointer.
Declared In
MemoryMgr.h
Prototype
LocalIDKind MemLocalIDKind ( LocalID local )
Parameters
Returns
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 Function
Purpose
Convert a local ID, which is card relative, into a global pointer in the designated card.
Declared In
MemoryMgr.h
Prototype
MemPtr MemLocalIDToGlobal ( LocalID local, UInt16 cardNo )
Parameters
Returns
Returns pointer or handle to chunk.
See Also
MemLocalIDKind()
, MemLocalIDToLockedPtr()
MemLocalIDToLockedPtr Function
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.
Declared In
MemoryMgr.h
Prototype
MemPtr MemLocalIDToLockedPtr ( LocalID local, UInt16 cardNo )
Parameters
Returns
Returns pointer to chunk, or 0 if an error occurs.
See Also
MemLocalIDToGlobal()
, MemLocalIDToPtr()
, MemLocalIDKind()
, MemPtrToLocalID()
, MemHandleToLocalID()
MemLocalIDToPtr Function
Purpose
Return pointer to chunk, given the local ID and card number.
Declared In
MemoryMgr.h
Prototype
MemPtr MemLocalIDToPtr ( LocalID local, UInt16 cardNo )
Parameters
Returns
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 Function
Purpose
Copy a number of bytes from one location to another in the dynamic heap.
Declared In
MemoryMgr.h
Prototype
Err MemMove ( void *destP, const void *sourceP, Int32 numBytes )
Parameters
Returns
Comments
Like the ISO C libary call memmove
, this function copies numBytes bytes from the object pointed to by sourceP into the object pointed to by destP. The source and destination may overlap; the copy is always done in a non-destructive manner.
For operations where the destination is in a data heap, see DmSet()
, DmWrite()
, and related functions.
MemNumCards Function
Purpose
Return the number of memory card slots in the system. Not all slots need to be populated.
Declared In
MemoryMgr.h
Prototype
UInt16 MemNumCards ( void )
Parameters
Returns
Returns number of slots in the system.
MemNumHeaps Function
Purpose
Return the number of heaps available on a particular card.
Declared In
MemoryMgr.h
Prototype
UInt16 MemNumHeaps ( UInt16 cardNo )
Parameters
Returns
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 Function
Purpose
Return the number of RAM heaps in the given card.
Declared In
MemoryMgr.h
Prototype
UInt16 MemNumRAMHeaps ( UInt16 cardNo )
Parameters
Returns
Returns the number of RAM heaps.
See Also
MemPtrCardNo Function
Purpose
Return the card number (0 or 1) a nonmovable chunk resides on.
Declared In
MemoryMgr.h
Prototype
UInt16 MemPtrCardNo ( MemPtr p )
Parameters
Returns
See Also
MemPtrDataStorage Function
Purpose
Return true
if the given pointer is part of a data storage heap; if not, it is a pointer in the dynamic heap.
Declared In
MemoryMgr.h
Prototype
Boolean MemPtrDataStorage ( MemPtr p )
Parameters
Returns
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
MemPtrFree Macro
Purpose
Declared In
MemoryMgr.h
Prototype
#define MemPtrFree ( p )
Parameters
Returns
Comments
Call this routine to dispose of a nonmovable chunk.
MemPtrHeapID Function
Purpose
Return the heap ID of a chunk.
Declared In
MemoryMgr.h
Prototype
UInt16 MemPtrHeapID ( MemPtr p )
Parameters
Returns
Returns the heap ID of a chunk.
Comments
Call this routine to get the heap ID of the heap a chunk resides in.
MemPtrNew Function
Purpose
Allocate a new nonmovable chunk in the dynamic heap.
Declared In
MemoryMgr.h
Prototype
MemPtr MemPtrNew ( UInt32 size )
Parameters
Returns
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. Note that chunks range in size from 1 byte to slightly less than 64KB; you cannot allocate a single chunk larger than this.
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
MemPtrRecoverHandle Function
Purpose
Recover the handle of a movable chunk, given a pointer to its data.
Declared In
MemoryMgr.h
Prototype
MemHandle MemPtrRecoverHandle ( MemPtr p )
Parameters
Returns
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 Function
Purpose
Declared In
MemoryMgr.h
Prototype
Err MemPtrResize ( MemPtr p, UInt32 newSize )
Parameters
Returns
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 Function
Purpose
Declared In
MemoryMgr.h
Prototype
Err MemPtrSetOwner ( MemPtr p, UInt16 owner )
Parameters
-
→
p
- Pointer to the chunk.
-
→
owner
- New owner ID of the chunk. Specify 0 to set the owner to the operating system.
Returns
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.
IMPORTANT: Once you have granted ownership of a memory chunk to the system, do not attempt to free it yourself. The operating system will free it when the application invoked with
SysUIAppSwitch()
or SysAppLaunch()
quits.
MemPtrSize Function
Purpose
Declared In
MemoryMgr.h
Prototype
UInt32 MemPtrSize ( MemPtr p )
Parameters
Returns
The requested size of the chunk.
Comments
Call this routine to get the original requested size of a chunk.
MemPtrToLocalID Function
Purpose
Convert a pointer into a card-relative local chunk ID.
Declared In
MemoryMgr.h
Prototype
LocalID MemPtrToLocalID ( MemPtr p )
Parameters
Returns
Returns the local ID of the chunk.
Comments
Call this routine to convert a chunk pointer to a local ID.
See Also
MemPtrUnlock Function
Purpose
Unlock a chunk, given a pointer to the chunk.
Declared In
MemoryMgr.h
Prototype
Err MemPtrUnlock ( MemPtr p )
Parameters
Returns
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
MemSet Function
Purpose
Set a memory range in a dynamic heap to a specific value.
Declared In
MemoryMgr.h
Prototype
Err MemSet ( void *dstP, Int32 numBytes, UInt8 value )
Parameters
Returns
Comments
For operations where the destination is in a data heap, see DmSet()
, DmWrite()
, and related functions.
MemSetDebugMode Function
Purpose
Set the debugging mode of the memory manager.
Declared In
MemoryMgr.h
Prototype
Err MemSetDebugMode ( UInt16 flags )
Parameters
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
Returns
Returns 0 if no error, or -1 if an error occurs.
MemStoreInfo Function
Purpose
Return information on either the RAM store or the ROM store for a memory card.
Declared In
MemoryMgr.h
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
-
→
cardNo
- Card number, either 0 or 1.
-
→
storeNumber
- Store number; 0 for ROM, 1 for RAM.
-
↔
versionP
- Pointer to version variable, or 0.
-
↔
flagsP
- Pointer to flags variable, or 0.
-
↔
nameP
- Pointer to character array (32 bytes), or 0.
-
↔
crDateP
- Pointer to creation date variable, or 0.
-
↔
bckUpDateP
- Pointer to backup date variable, or 0.
-
↔
heapListOffsetP
- Pointer to
heapListOffset
variable, or 0. -
↔
initCodeOffset1P
- Pointer to
initCodeOffset1
variable, or 0. -
↔
initCodeOffset2P
- Pointer to
initCodeOffset2
variable, or 0. -
↔
databaseDirIDP
- Pointer to database directory chunk ID variable, or 0.
Returns
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.