Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

6    Memory Manager

Memory, Databases, and Files

Exploring Palm OS®

This chapter describes the Memory Manager APIs. You use these APIs to manipulate memory chunks and memory heaps within Palm OS®.

Note that many of the APIs provided by the Memory Manager exist to simplify the process of porting an application from an earlier version of Palm OS. Palm OS Cobalt applications can make use of the standard C memory management functions—functions such as malloc(), realloc(), and free()—instead.

This chapter is organized as follows:

Memory Manager Structures and Types
Memory Manager Constants
Memory Manager Functions and Macros

The header file MemoryMgr.h declares the API that this chapter describes.

For more information on the Memory Manager, see Chapter 1, "Memory."

Memory Manager Structures and Types ^TOP^

LocalID Typedef ^TOP^

Purpose

Chunk identifier.

Declared In

MemoryMgr.h

Prototype

typedef uint32_t LocalID

MemHeapInfoType Struct ^TOP^

Purpose

Contains information about a dynamic heap.

Declared In

MemoryMgr.h

Prototype

typedef struct MemHeapInfoType {
   uint32_t maxBlockSize;
   uint32_t defaultAlignment;
   void *basePtr;
   uint32_t maxSize;
   uint32_t physMem;
   uint32_t physMemUsed;
   uint32_t physMemUnused;
   uint32_t chunksNum;
   uint32_t memAllocated;
   uint32_t chunksFree;
   uint32_t freeSpace;
   uint32_t freeBytes;
   uint32_t largestBlock;
   uint32_t largestCommitted;
   uint32_t statMaxAllocated;
} MemHeapInfoType
typedef MemHeapInfoType *MemHeapInfoPtr

Fields

maxBlockSize
The size of the largest chunk that could be potentially allocated.
defaultAlignment
The default alignment of memory chunks.
basePtr
The base address of the dynamic heap.
maxSize
The amount of virtual address space reserved for the heap.
physMem
The amount of physical memory that could be used to extend the pool of memory chunks.
physMemUsed
The amount of physical memory being used by the dynamic heap.
physMemUnused
The amount of physical memory that could be returned to the operating system.
chunksNum
The number of chunks allocated from the heap.
memAllocated
The amount of memory used by chunks that are not free.
chunksFree
The number of chunks in the dynamic heap that are free.
freeSpace
The amount of uncommitted virtual address space reserved for chunks.
freeBytes
The total number of bytes that could potentially be used to allocate chunks.
largestBlock
The size of the largest memory block that could be allocated from the dynamic heap.
largestCommitted
the size of the largest memory block that could be allocated from the dynamic heap without using additional kernel memory.
statMaxAllocated

Comments

Use MemDynHeapGetInfo() to obtain this information.

Memory Manager Constants ^TOP^

Debug Mode Flags ^TOP^

Purpose

These flags indicate or specify the current debug mode for the instance of the Heap Manager local to the calling process.

Declared In

MemoryMgr.h

Constants

#define memDebugModeAllHeaps 0x0020
Obsolete flag. Provided for compatibility purposes only.
#define memDebugModeCheckOnAll 0x0002
#define memDebugModeCheckOnChange 0x0001
#define memDebugModeFillFree 0x0010
When a memory chunk is freed (with either MemPtrFree() or MemHandleFree()), unused memory will be filled with a default value (currently, 0x55). Note that only memory that is accessible will be filled: the first 32 bits of free chunk data are reserved for internal use and will never be filled.
#define memDebugModeNoDMCall 0x0200
Force the heap library to report all calls that it delegates to the Data Manager. This flag helps you to track down Memory Manager calls that operate on the storage heap—calls that should be changed to reference the corresponding Data Manager functions.
#define memDebugModeRecordMaxDynHeapUsed memDebugModeRecordMinDynHeapFree
Records the maximum amount of memory used by the dynamic heap during its lifetime.
#define memDebugModeRecordMinDynHeapFree 0x0040
Records the maximum amount of memory used by the dynamic heap during its lifetime.
#define memDebugModeScrambleOnAll 0x0008
Obsolete flag. Provided for compatibility purposes only.
#define memDebugModeScrambleOnChange 0x0004
Obsolete flag. Provided for compatibility purposes only.
#define memDebugModeValidateParams 0x0100
Force the heap library to thoroughly validate all parameters passed to the Memory Manager and Heap Manager functions. This validation includes pointers and memory chunk handles, so, for example, an attempt to resize a bad pointer can be detected.

Comments

Use MemDebugMode() to obtain the current debug mode for the instance of the Heap Manager local to the calling process. Use MemSetDebugMode() to change the current debug mode.

Dynamic Heap Options ^TOP^

Purpose

Pass these constants to MemDynHeapOption() to get or set various dynamic heap parameters at run time.

Declared In

MemoryMgr.h

Constants

#define memOptGetAbsMaxMemUsage 2
Retrieve the maximum amount of physical memory the dynamic heap is allowed to use.
#define memOptGetAbsMinMemUsage 4
This option is not supported in Palm OS Cobalt.
#define memOptGetForceMemReleaseThreshold 8
Retrieve the memory usage watermark above which all unused memory will be immediately released back to the operating system.
#define memOptGetMaxUnusedMem 6
This option is not supported in Palm OS Cobalt.
#define memOptSetAbsMaxMemUsage 1
Specify the maximum amount of physical memory the dynamic heap is allowed to use.
#define memOptSetAbsMinMemUsage 3
This option is not supported in Palm OS Cobalt.
#define memOptSetForceMemReleaseThreshold 7
Specify the memory usage watermark above which all unused memory will be immediately released back to the operating system. The default value is the size of the heap, so this feature is off by default.
#define memOptSetMaxUnusedMem 5
This option is not supported in Palm OS Cobalt.

Heap Flags ^TOP^

Purpose

The set of flags that can be obtained for a heap using MemHeapFlags().

Declared In

MemoryMgr.h

Constants

#define memHeapFlagReadOnly memHeapFlagROMBased
The heap is read-only; it cannot be written to.
#define memHeapFlagROMBased 0x0001
The heap is located in ROM.
#define memHeapFlagWritable 0x0002
The heap can be written to.

Memory Manager Error Codes ^TOP^

Purpose

Error codes returned by the various Memory Manager functions.

Declared In

MemoryMgr.h

Constants

#define memErrAlreadyInitialized (memErrorClass | 13)
#define memErrCardNotPresent (memErrorClass | 5)
#define memErrChunkLocked (memErrorClass | 1)
#define memErrChunkNotLocked (memErrorClass | 4)
#define memErrEndOfHeapReached (memErrorClass | 15)
#define memErrFirst memErrChunkLocked
#define memErrHeapInvalid (memErrorClass | 14)
#define memErrInvalidParam (memErrorClass | 3)
#define memErrInvalidStoreHeader (memErrorClass | 7)
#define memErrLast memErrEndOfHeapReached
#define memErrNoCardHeader (memErrorClass | 6)
#define memErrNoRAMOnDevice (memErrorClass | 10)
#define memErrNoStore (memErrorClass | 11)
#define memErrNotEnoughSpace (memErrorClass | 2)
#define memErrRAMOnlyDevice (memErrorClass | 8)
#define memErrROMOnlyDevice (memErrorClass | 12)
#define memErrWriteProtect (memErrorClass | 9)

LocalIDKind Enum ^TOP^

Purpose

Declared In

MemoryMgr.h

Constants

memIDPtr
memIDHandle

Memory Manager Functions and Macros ^TOP^

MemCmp Function ^TOP^

Purpose

Compare two blocks of memory.

Declared In

MemoryMgr.h

Prototype

int16_t MemCmp (
   const void *s1,
   const void *s2,
   int32_t numBytes
)

Parameters

s1
Pointer to the first block of memory to be compared.
s2
Pointer to the second block of memory to be compared.
numBytes
Number of bytes to compare.

Returns

Returns zero if the two blocks of memory match, a positive value if s1 > s2, and a negative value if s1 < s2.

Comments

The two memory blocks are compared as a set of unsigned bytes.

MemDebugMode Function ^TOP^

Purpose

Obtain the current debug mode for the instance of the Heap Manager local to the calling process.

Declared In

MemoryMgr.h

Prototype

uint16_t MemDebugMode (
   void
)

Parameters

None.

Returns

Returns a set of debug flags. See "Debug Mode Flags" for the set of flags that this function can return.

See Also

MemSetDebugMode()

MemDynHeapGetInfo Function ^TOP^

Purpose

Retrieve information about a dynamic heap.

Declared In

MemoryMgr.h

Prototype

status_t MemDynHeapGetInfo (
   MemHeapInfoType *oInfo
)

Parameters

oInfo
Pointer to a structure that gets filled with information about the dynamic heap. See "MemHeapInfoType."

Returns

Always returns errNone.

Comments

Your application must supply a MemHeapInfoType structure to this function. Upon return, the structure contains the following information:

  • The size of the largest chunk that could be potentially allocated.
  • The default alignment of memory chunks.
  • The base address of the dynamic heap.
  • The amount of virtual address space reserved for the heap
  • The amount of physical memory that could be used to extend the pool of memory chunks.
  • The amount of physical memory being used by the dynamic heap, and the amount that could be returned to the operating system.
  • The number of chunks allocated from the heap, and the number of chunks in the heap that are free.
  • The amount of memory used by chunks that are not free.
  • The amount of uncommitted virtual address space reserved for chunks.
  • The total number of bytes that could potentially be used to allocate chunks.
  • The size of the largest memory block that could be allocated from the dynamic heap, and the size of the largest memory block that could be allocated from the dynamic heap without using additional kernel memory.

See Also

MemDynHeapOption(), MemDynHeapReleaseUnused(), MemHeapDynamic()

MemDynHeapOption Function ^TOP^

Purpose

Allow the fine-tuning of various dynamic heap parameters at run time.

Declared In

MemoryMgr.h

Prototype

uint32_t MemDynHeapOption (
   uint32_t cmd,
   uint32_t value
)

Parameters

cmd
One of the commands listed under "Dynamic Heap Options."
value
The value associated with the command, when using one of the option-setting commands. Ignored otherwise.

Returns

Returns the current effective value of the specified dynamic heap option.

See Also

MemDynHeapGetInfo(), MemHeapDynamic()

MemDynHeapReleaseUnused Function ^TOP^

Purpose

Force the dynamic heap to release as much memory as it can back to the operating system.

Declared In

MemoryMgr.h

Prototype

void MemDynHeapReleaseUnused (
   void
)

Parameters

None.

Returns

Nothing.

Comments

The Heap Manager releases unused memory in page quantities. Any page in the address range controlled by the heap that does not contain allocated memory chunks or internal heap control structures could potentially be released back to the operating system. Applications should not assume that all pages occupied by the heap are always accessible; never attempt to access, for example, the area occupied by a chunk that was freed.

See Also

MemHeapDynamic()

MemHandleDataStorage Function ^TOP^

Purpose

Determine whether or not a chunk is located in a storage heap.

Declared In

MemoryMgr.h

Prototype

Boolean MemHandleDataStorage (
   MemHandle h
)

Parameters

h
Chunk handle.

Returns

Returns true if the specified chunk belongs to the storage area.

See Also

MemPtrDataStorage()

MemHandleFree Function ^TOP^

Purpose

Dispose of a memory chunk given its handle.

Declared In

MemoryMgr.h

Prototype

status_t MemHandleFree (
   MemHandle h
)

Parameters

h
Chunk handle.

Returns

Returns errNone if no error occurred. Returns memErrInvalidParam if the chunk could not, or should not, be freed.

Comments

If the memDebugModeFillFree flag is set, the unused memory will be filled with a default value (currently, 0x55).

If the supplied pointer indicates a chunk in a storage heap, the request is forwarded to the Data Manager.


NOTE: The Palm OS Cobalt Memory Manager uses virtual pages to hold handle tables, and they may not be returned to the kernel even if the chunks referenced by those handles are freed. In addition, the threshold of free memory that a heap can keep without returning the memory to the kernel impacts the amount of free memory reported after certain allocation and de-allocation operations. Because of this, if you allocate handles and pointers and then free them, the amount of memory reported as available after the series of operations may not be the same as that reported before.

See Also

MemDebugMode(), MemPtrFree(), MemHandleNew(), DmHandleFree()

MemHandleHeapID Function ^TOP^

Purpose

Get the ID of the heap that contains a given memory chunk referenced by its handle.

Declared In

MemoryMgr.h

Prototype

uint16_t MemHandleHeapID (
   MemHandle h
)

Parameters

h
Chunk handle.

Returns

Returns the ID of the heap containing the specified memory chunk, or 0xFFFF if the specified pointer does not match any heap.

See Also

MemHeapID(), MemPtrHeapID()

MemHandleLock Function ^TOP^

Purpose

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

Declared In

MemoryMgr.h

Prototype

MemPtr MemHandleLock (
   MemHandle h
)

Parameters

h
Chunk handle.

Returns

Returns a pointer to the chunk's data, or NULL if an error.

Comments

A NULL handle can safely be passed to this function; NULL will be returned.

If the supplied handle indicates a chunk in a storage heap, the request is forwarded to the Data Manager.

See Also

MemHandleUnlock(), DmHandleLock()

MemHandleNew Function ^TOP^

Purpose

Allocate a new movable chunk in the dynamic heap.

Declared In

MemoryMgr.h

Prototype

MemHandle MemHandleNew (
   uint32_t size
)

Parameters

size
Size, in bytes, of the memory chunk to allocate.

Returns

Returns the handle of the chunk, or NULL if the chunk couldn't be allocated.

Comments

The handle returned by this function should not be interpreted by the application in any way. Memory handles should be used only in conjunction with the appropriate APIs.

See Also

MemHandleFree(), MemPtrNew()

MemHandleResize Function ^TOP^

Purpose

Resize a chunk referenced by a handle.

Declared In

MemoryMgr.h

Prototype

status_t MemHandleResize (
   MemHandle h,
   uint32_t newSize
)

Parameters

h
Chunk handle.
newSize
New size of the memory chunk. This value should be non-zero.

Returns

Returns errNone if the chunk was successfully resized, or one of the following otherwise:

memErrNotEnoughSpace
There is not enough free memory to fulfill the request.
memErrChunkLocked
The given chunk cannot be resized.
memErrInvalidParam
One of the supplied arguments is invalid.

Comments

This function may cause the unlocked chunk to be moved.

If the supplied handle indicates a chunk in a storage heap, the request is forwarded to the Data Manager.

See Also

MemHandleSize(), MemPtrResize(), DmHandleResize()

MemHandleSetOwner Function ^TOP^

Purpose

Set the owner ID of a chunk, given the chunk's handle.

Declared In

MemoryMgr.h

Prototype

status_t MemHandleSetOwner (
   MemHandle h,
   uint16_t owner
)

Parameters

h
Chunk handle.
owner
New owner ID of the chunk. Specify 0 to set the owner to the operating system. Only the lowest four bits are used.

Returns

Returns errNone if the owner ID was set successfully, or memErrInvalidParam if an error occurred.

Comments

The Heap Manager reserves owner ID 15 for internal usage. You cannot set a chunk's owner ID to 15 with this function.

See Also

MemPtrSetOwner()

MemHandleSize Function ^TOP^

Purpose

Get the size of a memory chunk referenced by a handle.

Declared In

MemoryMgr.h

Prototype

uint32_t MemHandleSize (
   MemHandle h
)

Parameters

h
Chunk handle.

Returns

Returns the size, in bytes, of the memory chunk referenced by the handle. Returns 0 if the size of the chunk is 0 or if an error occurred.

Comments

If the supplied handle indicates a chunk in a storage heap, the request is forwarded to the Data Manager.

See Also

MemHandleResize(), MemPtrRealloc(), DmHandleSize()

MemHandleUnlock Function ^TOP^

Purpose

Unlock a movable memory chunk.

Declared In

MemoryMgr.h

Prototype

status_t MemHandleUnlock (
   MemHandle h
)

Parameters

h
Chunk handle.

Returns

Returns errNone if the chunk was unlocked, or memErrInvalidParam if an error occurred.

Comments

If the supplied handle indicates a chunk in a storage heap, the request is forwarded to the Data Manager.

See Also

MemHandleLock(), MemPtrUnlock(), DmHandleUnlock()

MemHeapCheck Function ^TOP^

Purpose

Validate the internal structure of a given heap.

Declared In

MemoryMgr.h

Prototype

status_t MemHeapCheck (
   uint16_t heapID
)

Parameters

heapID
ID of the heap to check.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

memErrInvalidParam
heapID is invalid.
memErrInvalidHeap
Heap corruption was detected.

Comments

This function can be used with any writable heap. If the calling process does not have write access to the heap, errNone is returned. This call is never forwarded to the Data Manager.

This function is called internally at appropriate times if the MemDebugModeCheckOnChange or memDebugModeCheckOnAll debug mode flags are set.

See Also

MemDebugMode(), MemHeapCompact()

MemHeapCompact Function ^TOP^

Purpose

Compact a heap.

Declared In

MemoryMgr.h

Prototype

status_t MemHeapCompact (
   uint16_t heapID
)

Parameters

heapID
ID of the heap to be compacted.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

memErrInvalidParam
heapID is invalid, or the heap specified by heapID is not writable.
memErrNotEnoughSpace
There was not enough memory to complete the compaction.

Comments

The calling process must have write permission to be able to compact the heap. If the calling process does not have write access to the heap, errNone is returned.

This call is never forwarded to the Data Manager.

See Also

MemHeapScramble()

MemHeapDynamic Function ^TOP^

Purpose

Determine whether or not the specified heap is the dynamic heap.

Declared In

MemoryMgr.h

Prototype

Boolean MemHeapDynamic (
   uint16_t heapID
)

Parameters

heapID
ID of the heap.

Returns

Returns true if the specified heap is the dynamic heap, false otherwise.

See Also

MemDynHeapGetInfo(), MemDynHeapOption(), MemDynHeapReleaseUnused(), MemHeapFlags()

MemHeapFlags Function ^TOP^

Purpose

Get the heap flags for a specified heap. These flags indicate whether or not the heap can be written to and whether or not the heap is located in ROM.

Declared In

MemoryMgr.h

Prototype

uint16_t MemHeapFlags (
   uint16_t heapID
)

Parameters

heapID
ID of the heap.

Returns

Returns the heap flags, or 0 if heapID is invalid. See "Heap Flags" for the set of flags that can make up the returned value.

See Also

MemHeapDynamic()

MemHeapFreeBytes Function ^TOP^

Purpose

Get the total number of free bytes in a specified heap and the size of the largest free chunk in that heap.

Declared In

MemoryMgr.h

Prototype

status_t MemHeapFreeBytes (
   uint16_t heapID,
   uint32_t *freeP,
   uint32_t *maxP
)

Parameters

heapID
ID of the heap.
freeP
The total number of bytes that are free in the heap.
maxP
The size, in bytes, of the largest free chunk in the heap.

Returns

Returns errNone if the operation completed successfully, or memErrInvalidParam if heapID is invalid.

Comments

The size of the largest chunk returned by this call, in most cases, will be the size of the heap "wilderness" area: the area that is not backed up with physical memory. There is no guarantee that the returned amount actually can be allocated due to limits on physical memory imposed by resource bank and overall availability of free memory in the system.

See Also

MemHeapSize()

MemHeapID Function ^TOP^

Purpose

Get the ID for a heap, given its index.

Declared In

MemoryMgr.h

Prototype

uint16_t MemHeapID (
   uint16_t heapIndex
)

Parameters

heapIndex
Heap index.

Returns

Returns the heap ID.

Comments

Index 0 refers to the dynamic heap. Index 1 refers to the storage area. Index 2 refers to ROM.

See Also

MemHandleHeapID(), MemPtrHeapID()

MemHeapScramble Function ^TOP^

Purpose

Scramble a heap, moving each of the heap's movable chunks. This function can be useful when debugging.

Declared In

MemoryMgr.h

Prototype

status_t MemHeapScramble (
   uint16_t heapID
)

Parameters

heapID
ID of the heap to be scrambled.

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

memErrInvalidParam
heapID is invalid, or the heap specified by heapID is not writable.
memErrNotEnoughSpace
There was not enough memory to scramble the heap.

Comments

The calling process must have write permission to be able to scramble the heap. If the calling process does not have write access to the heap, errNone is returned.

This call is never forwarded to the Data Manager.

See Also

MemHeapCompact()

MemHeapSize Function ^TOP^

Purpose

Get the maximum number of bytes that the heap can manage or request from the kernel.

Declared In

MemoryMgr.h

Prototype

uint32_t MemHeapSize (
   uint16_t heapID
)

Parameters

heapID
ID of the heap.

Returns

Returns the maximum size, in bytes, of the specified heap, or 0 if heapID is invalid.

Comments

The value returned by this call represents the maximum amount possible. Not all of this memory is necessarily available.

See Also

MemHeapFreeBytes()

MemMove Function ^TOP^

Purpose

Move memory.

Declared In

MemoryMgr.h

Prototype

status_t MemMove (
   void *dstP,
   const void *sP,
   int32_t numBytes
)

Parameters

dstP
Pointer to the destination.
sP
Pointer to the source.
numBytes
Number of bytes to move.

Returns

Always returns errNone.

Comments

This function properly handles overlapping ranges.

MemNumHeaps Function ^TOP^

Purpose

Get the number of available heaps in both ROM and RAM.

Declared In

MemoryMgr.h

Prototype

uint16_t MemNumHeaps (
   void
)

Parameters

None.

Returns

The number of heaps. This value is always 3, since the system has three heaps: the dynamic heap, the storage area, and ROM.

See Also

MemHandleHeapID(), MemPtrHeapID(), MemNumRAMHeaps()

MemNumRAMHeaps Function ^TOP^

Purpose

Get the number of available RAM heaps.

Declared In

MemoryMgr.h

Prototype

uint16_t MemNumRAMHeaps (
   void
)

Parameters

None.

Returns

The number of heaps. This value is always 2, since the system has two RAM heaps: the dynamic heap, and the non-secure RAM storage heap.

See Also

MemHandleHeapID(), MemPtrHeapID(), MemNumHeaps()

MemPtrDataStorage Function ^TOP^

Purpose

Determine whether or not a chunk is located in the storage heap.

Declared In

MemoryMgr.h

Prototype

Boolean MemPtrDataStorage (
   MemPtr p
)

Parameters

p
Pointer to the chunk.

Returns

Returns true if the specified chunk belongs to the storage area.

Comments

This function checks whether or not the given pointer falls within the address range occupied by the heap located in the storage area.

See Also

MemHandleDataStorage()

MemPtrFree Macro ^TOP^

Purpose

Dispose of a memory chunk referenced by the given pointer.

Declared In

MemoryMgr.h

Prototype

#define MemPtrFree (
   p
)

Parameters

p
Pointer to the memory chunk to be freed.

Returns

Returns errNone if no error occurred. Returns memErrInvalidParam if the chunk could not, or should not, be freed.

Comments

If the memDebugModeFillFree flag is set, the unused memory will be filled with a default value (currently, 0x55).

If the supplied pointer indicates a chunk in a storage heap, the request is forwarded to the Data Manager.


NOTE: The Palm OS Cobalt Memory Manager uses virtual pages to hold handle tables, and they may not be returned to the kernel even if the chunks referenced by those handles are freed. In addition, the threshold of free memory that a heap can keep without returning the memory to the kernel impacts the amount of free memory reported after certain allocation and de-allocation operations. Because of this, if you allocate handles and pointers and then free them, the amount of memory reported as available after the series of operations may not be the same as that reported before.

See Also

MemDebugMode(), MemHandleFree(), MemPtrNew(), DmHandleFree()

MemPtrHeapID Function ^TOP^

Purpose

Get the ID of the heap that contains a given memory chunk referenced by a pointer.

Declared In

MemoryMgr.h

Prototype

uint16_t MemPtrHeapID (
   MemPtr p
)

Parameters

p
Pointer to the chunk.

Returns

Returns the ID of the heap containing the specified memory chunk, or 0xFFFF if the specified pointer does not match any heap.

See Also

MemHandleHeapID(), MemHeapID()

MemPtrNew Function ^TOP^

Purpose

Allocate a new memory chunk from the dynamic heap.

Declared In

MemoryMgr.h

Prototype

MemPtr MemPtrNew (
   uint32_t size
)

Parameters

size
The desired size of the chunk.

Returns

Returns a pointer to a newly allocated chunk if successful, or NULL if the Memory Manager was unable to allocate a memory chunk of the requested size.

Comments

This function allocates a non-movable chunk in the dynamic heap and returns a pointer to that chunk. Applications can use this call to allocate dynamic memory. User processes should use this call as a primary dynamic memory allocator.

See Also

MemHandleNew(), MemPtrFree()

MemPtrRealloc Function ^TOP^

Purpose

Change the size of a non-movable chunk referenced by a pointer.

Declared In

MemoryMgr.h

Prototype

MemPtr MemPtrRealloc (
   MemPtr ptr,
   uint32_t newSize
)

Parameters

ptr
Pointer to the memory chunk to be reallocated.
newSize
New size, in bytes, of the chunk.

Returns

Returns a pointer to the reallocated chunk, or NULL if the chunk couldn't be resized as requested.

Comments

The semantic of this call resembles the standard C library function realloc. The contents of the chunk will be unchanged up to the lesser of the new and old size. If ptr is NULL, this function behaves like MemPtrNew(). If newSize is 0 and ptr is not NULL, the memory chunk is freed and NULL is returned. MemPtrRealloc significantly simplifies the management of variable-length memory chunks, so this call is recommended over MemPtrResize().

Only non-movable chunks can be reallocated using this call.

See Also

MemHandleResize(), DmPtrResize()

MemPtrRecoverHandle Function ^TOP^

Purpose

Recover the handle of a memory chunk referenced by the given pointer to its data.

Declared In

MemoryMgr.h

Prototype

MemHandle MemPtrRecoverHandle (
   MemPtr p
)

Parameters

p
Pointer to a memory chunk.

Returns

Returns the handle of the memory chunk, or NULL if an error occurred.

Comments

For memory chunks in the dynamic heap, the given pointer will be converted to a handle and returned as a result. For memory chunks in a storage heap, the call is forwarded to the Data Manager.

See Also

DmRecoverHandle()

MemPtrResize Function ^TOP^

Purpose

Resize a memory chunk referenced by a pointer.

Declared In

MemoryMgr.h

Prototype

status_t MemPtrResize (
   MemPtr p,
   uint32_t newSize
)

Parameters

p
Pointer to the memory chunk to be resized.
newSize
New desired size of the memory chunk, in bytes.

Returns

Returns errNone if the chunk was successfully resized, or one of the following otherwise:

memErrNotEnoughSpace
There is not enough memory to fulfill the request.
memErrChunkLocked
The given chunk cannot be resized in place.
memErrInvalidParam
One of the arguments is invalid, the chunk does not exist, or the chunk should not be resized.

Comments

Call this function to resize a locked chunk. This function is always successful when shrinking the size of a chunk. When growing a chunk, it attempts to use free space immediately following the chunk, and returns memErrChunkLocked if the resize fails.

For non-movable chunks in the dynamic heap, consider using MemPtrRealloc(). In most cases, that function is more convenient.

If the supplied pointer indicates a chunk in a storage heap, the request is forwarded to the Data Manager.

See Also

MemHandleResize(), MemPtrNew(), DmPtrResize()

MemPtrSetOwner Function ^TOP^

Purpose

Set the owner ID of a chunk referenced by a pointer.

Declared In

MemoryMgr.h

Prototype

status_t MemPtrSetOwner (
   MemPtr p,
   uint16_t owner
)

Parameters

p
Chunk pointer.
owner
New owner ID of the chunk. Specify 0 to set the owner to the operating system. Only the lowest four bits are used.

Returns

Returns errNone if the owner ID was set successfully, or memErrInvalidParam if an error occurred.

Comments

The Heap Manager reserves owner ID 15 for internal usage. You cannot set a chunk's owner ID to 15 with this function.

See Also

MemHandleSetOwner()

MemPtrSize Function ^TOP^

Purpose

Get the size of a memory chunk referenced by a pointer.

Declared In

MemoryMgr.h

Prototype

uint32_t MemPtrSize (
   MemPtr p
)

Parameters

p
Pointer to a memory chunk.

Returns

The size of the chunk, in bytes, or 0 if an error occurred.

Comments

The value returned represents the size of the "Data" portion of the memory chunk that is equal to the value that was specified when it was allocated or resized.

If the supplied pointer indicates a chunk in a storage heap, the request is forwarded to the Data Manager.

See Also

MemPtrNew(), MemPtrResize(), DmPtrSize()

MemPtrUnlock Function ^TOP^

Purpose

Unlock a chunk, given a pointer to the chunk.

Declared In

MemoryMgr.h

Prototype

status_t MemPtrUnlock (
   MemPtr p
)

Parameters

p
Pointer to the chunk to be unlocked.

Returns

Returns errNone if the chunk was unlocked, or memErrInvalidParam if an error occurred.

Comments

If the supplied pointer indicates a chunk in a storage heap, the request is forwarded to the Data Manager.

See Also

MemHandleUnlock(), DmPtrUnlock()

MemSet Function ^TOP^

Purpose

Set a memory range to a specified value.

Declared In

MemoryMgr.h

Prototype

status_t MemSet (
   void *dstP,
   int32_t numBytes,
   uint8_t value
)

Parameters

dstP
Pointer to the beginning of the memory range to be set.
numBytes
Number of bytes to be set.
value
Value to which each of the bytes in the specified range are set.

Returns

Always returns errNone.

MemSetDebugMode Function ^TOP^

Purpose

Set the debugging mode for the instance of the Heap Manager local to the calling process.

Declared In

MemoryMgr.h

Prototype

status_t MemSetDebugMode (
   uint16_t flags
)

Parameters

flags
Use the logical OR operator (|) to provide any combination of the flags listed in "Debug Mode Flags."

Returns

Returns errNone if the debug mode flags were set successfully, or memErrHeapInvalid if an invalid heap was detected.

Comments

When using the memDebugModeFillFree debug flag, note that only memory that is accessible will be filled. The first 32 bits of free chunk data are reserved for internal use and will never be filled.

When working with the storage heap you should try to always use functions provided by the Data Manager. The MemDebugModeNoDmCalls debug flag helps you to track down "leftover" Memory Manager calls that operate on the storage heap. These calls can then be converted into Data Manager calls.

See Also

MemDebugMode()