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
LocalID Typedef
Purpose
Declared In
MemoryMgr.h
Prototype
typedef uint32_t LocalID
MemHeapInfoType Struct
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
Debug Mode Flags
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()
orMemHandleFree()
), 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
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
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
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
Purpose
Declared In
MemoryMgr.h
Constants
Memory Manager Functions and Macros
MemCmp Function
Purpose
Declared In
MemoryMgr.h
Prototype
int16_t MemCmp ( const void*s1
, const void*s2
, int32_tnumBytes
)
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
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
Returns
Returns a set of debug flags. See "Debug Mode Flags" for the set of flags that this function can return.
See Also
MemDynHeapGetInfo Function
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
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
Purpose
Allow the fine-tuning of various dynamic heap parameters at run time.
Declared In
MemoryMgr.h
Prototype
uint32_t MemDynHeapOption ( uint32_tcmd
, uint32_tvalue
)
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
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
Returns
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
MemHandleDataStorage Function
Purpose
Determine whether or not a chunk is located in a storage heap.
Declared In
MemoryMgr.h
Prototype
Boolean MemHandleDataStorage (
MemHandle h
)
Parameters
Returns
Returns true
if the specified chunk belongs to the storage area.
See Also
MemHandleFree Function
Purpose
Dispose of a memory chunk given its handle.
Declared In
MemoryMgr.h
Prototype
status_t MemHandleFree (
MemHandle h
)
Parameters
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
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
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
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'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
Purpose
Allocate a new movable chunk in the dynamic heap.
Declared In
MemoryMgr.h
Prototype
MemHandle MemHandleNew (
uint32_t size
)
Parameters
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
MemHandleResize Function
Purpose
Resize a chunk referenced by a handle.
Declared In
MemoryMgr.h
Prototype
status_t MemHandleResize ( MemHandleh
, uint32_tnewSize
)
Parameters
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
Purpose
Set the owner ID of a chunk, given the chunk's handle.
Declared In
MemoryMgr.h
Prototype
status_t MemHandleSetOwner ( MemHandleh
, uint16_towner
)
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
MemHandleSize Function
Purpose
Get the size of a memory chunk referenced by a handle.
Declared In
MemoryMgr.h
Prototype
uint32_t MemHandleSize (
MemHandle h
)
Parameters
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
Purpose
Unlock a movable memory chunk.
Declared In
MemoryMgr.h
Prototype
status_t MemHandleUnlock (
MemHandle h
)
Parameters
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
Purpose
Validate the internal structure of a given heap.
Declared In
MemoryMgr.h
Prototype
status_t MemHeapCheck (
uint16_t heapID
)
Parameters
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
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
Purpose
Declared In
MemoryMgr.h
Prototype
status_t MemHeapCompact (
uint16_t heapID
)
Parameters
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
memErrInvalidParam
-
heapID
is invalid, or the heap specified byheapID
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
MemHeapDynamic Function
Purpose
Determine whether or not the specified heap is the dynamic heap.
Declared In
MemoryMgr.h
Prototype
Boolean MemHeapDynamic (
uint16_t heapID
)
Parameters
Returns
Returns true
if the specified heap is the dynamic heap, false
otherwise.
See Also
MemDynHeapGetInfo()
, MemDynHeapOption()
, MemDynHeapReleaseUnused()
, MemHeapFlags()
MemHeapFlags Function
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
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
MemHeapFreeBytes Function
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_theapID
, 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
MemHeapID Function
Purpose
Get the ID for a heap, given its index.
Declared In
MemoryMgr.h
Prototype
uint16_t MemHeapID (
uint16_t heapIndex
)
Parameters
Returns
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
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
Returns
Returns errNone
if the operation completed successfully, or one of the following otherwise:
-
memErrInvalidParam
-
heapID
is invalid, or the heap specified byheapID
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
MemHeapSize Function
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
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
MemMove Function
Purpose
Declared In
MemoryMgr.h
Prototype
status_t MemMove ( void*dstP
, const void*sP
, int32_tnumBytes
)
Parameters
Returns
Comments
This function properly handles overlapping ranges.
MemNumHeaps Function
Purpose
Get the number of available heaps in both ROM and RAM.
Declared In
MemoryMgr.h
Prototype
uint16_t MemNumHeaps ( void )
Parameters
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
Purpose
Get the number of available RAM heaps.
Declared In
MemoryMgr.h
Prototype
uint16_t MemNumRAMHeaps ( void )
Parameters
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
Purpose
Determine whether or not a chunk is located in the storage heap.
Declared In
MemoryMgr.h
Prototype
Boolean MemPtrDataStorage (
MemPtr p
)
Parameters
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
MemPtrFree Macro
Purpose
Dispose of a memory chunk referenced by the given pointer.
Declared In
MemoryMgr.h
Prototype
#define MemPtrFree (
p
)
Parameters
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
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
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
Purpose
Allocate a new memory chunk from the dynamic heap.
Declared In
MemoryMgr.h
Prototype
MemPtr MemPtrNew (
uint32_t size
)
Parameters
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
MemPtrRealloc Function
Purpose
Change the size of a non-movable chunk referenced by a pointer.
Declared In
MemoryMgr.h
Prototype
MemPtr MemPtrRealloc ( MemPtrptr
, uint32_tnewSize
)
Parameters
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
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
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
MemPtrResize Function
Purpose
Resize a memory chunk referenced by a pointer.
Declared In
MemoryMgr.h
Prototype
status_t MemPtrResize ( MemPtrp
, uint32_tnewSize
)
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
Purpose
Set the owner ID of a chunk referenced by a pointer.
Declared In
MemoryMgr.h
Prototype
status_t MemPtrSetOwner ( MemPtrp
, uint16_towner
)
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
MemPtrSize Function
Purpose
Get the size of a memory chunk referenced by a pointer.
Declared In
MemoryMgr.h
Prototype
uint32_t MemPtrSize (
MemPtr p
)
Parameters
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
Purpose
Unlock a chunk, given a pointer to the chunk.
Declared In
MemoryMgr.h
Prototype
status_t MemPtrUnlock (
MemPtr p
)
Parameters
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
Purpose
Set a memory range to a specified value.
Declared In
MemoryMgr.h
Prototype
status_t MemSet ( void*dstP
, int32_tnumBytes
, uint8_tvalue
)
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
MemSetDebugMode Function
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.