This is a generic heap manager which incorporates a memory leak detection system which can monitor and report the dynamic memory which is in use for each heap.
More...
|
Data Structures |
struct | lub_heap_stats_s |
struct | struct_void_ptr |
struct | _lub_partition_spec |
Defines |
#define | LUB_HEAP_ZERO_ALLOC ((void*)-1) |
Typedefs |
typedef struct lub_heap_s | lub_heap_t |
typedef struct
lub_heap_free_block_s | lub_heap_free_block_t |
typedef struct lub_heap_stats_s | lub_heap_stats_t |
typedef void | lub_heap_foreach_fn (void *block, unsigned index, size_t size, void *arg) |
typedef struct _lub_partition | lub_partition_t |
typedef struct _lub_partition_spec | lub_partition_spec_t |
Enumerations |
enum | lub_heap_status_t {
LUB_HEAP_OK,
LUB_HEAP_FAILED,
LUB_HEAP_DOUBLE_FREE,
LUB_HEAP_CORRUPTED,
LUB_HEAP_INVALID_POINTER
} |
enum | lub_heap_align_t {
LUB_HEAP_ALIGN_NATIVE = sizeof(struct_void_ptr),
LUB_HEAP_ALIGN_2_POWER_2 = 0x00000004,
LUB_HEAP_ALIGN_2_POWER_3 = 0x00000008,
LUB_HEAP_ALIGN_2_POWER_4 = 0x00000010,
LUB_HEAP_ALIGN_2_POWER_5 = 0x00000020,
LUB_HEAP_ALIGN_2_POWER_6 = 0x00000040,
LUB_HEAP_ALIGN_2_POWER_7 = 0x00000080,
LUB_HEAP_ALIGN_2_POWER_8 = 0x00000100,
LUB_HEAP_ALIGN_2_POWER_9 = 0x00000200,
LUB_HEAP_ALIGN_2_POWER_10 = 0x00000400,
LUB_HEAP_ALIGN_2_POWER_11 = 0x00000800,
LUB_HEAP_ALIGN_2_POWER_12 = 0x00001000,
LUB_HEAP_ALIGN_2_POWER_13 = 0x00002000,
LUB_HEAP_ALIGN_2_POWER_14 = 0x00004000,
LUB_HEAP_ALIGN_2_POWER_15 = 0x00008000,
LUB_HEAP_ALIGN_2_POWER_16 = 0x00010000,
LUB_HEAP_ALIGN_2_POWER_17 = 0x00020000,
LUB_HEAP_ALIGN_2_POWER_18 = 0x00040000,
LUB_HEAP_ALIGN_2_POWER_19 = 0x00080000,
LUB_HEAP_ALIGN_2_POWER_20 = 0x00100000,
LUB_HEAP_ALIGN_2_POWER_21 = 0x00200000,
LUB_HEAP_ALIGN_2_POWER_22 = 0x00400000,
LUB_HEAP_ALIGN_2_POWER_23 = 0x00800000,
LUB_HEAP_ALIGN_2_POWER_24 = 0x01000000,
LUB_HEAP_ALIGN_2_POWER_25 = 0x02000000,
LUB_HEAP_ALIGN_2_POWER_26 = 0x04000000,
LUB_HEAP_ALIGN_2_POWER_27 = 0x08000000
} |
enum | lub_heap_show_e { LUB_HEAP_SHOW_LEAKS,
LUB_HEAP_SHOW_PARTIALS,
LUB_HEAP_SHOW_ALL
} |
Functions |
void | lub_heap_foreach_segment (lub_heap_t *instance, lub_heap_foreach_fn *fn, void *arg) |
void | lub_heap_foreach_free_block (lub_heap_t *instance, lub_heap_foreach_fn *fn, void *arg) |
lub_heap_t * | lub_heap_create (void *start, size_t size) |
void | lub_heap_destroy (lub_heap_t *instance) |
void | lub_heap_add_segment (lub_heap_t *instance, void *start, size_t size) |
void * | lub_heap_static_alloc (lub_heap_t *instance, size_t size) |
lub_heap_status_t | lub_heap_realloc (lub_heap_t *instance, char **ptr, size_t size, lub_heap_align_t alignment) |
bool_t | lub_heap_taint (bool_t enable) |
bool_t | lub_heap_is_tainting (void) |
bool_t | lub_heap_check (bool_t enable) |
bool_t | lub_heap_is_checking (void) |
bool_t | lub_heap_check_memory (lub_heap_t *instance) |
void | lub_heap_stop_here (lub_heap_status_t status, char *old_ptr, size_t new_size) |
void | lub_heap__get_stats (lub_heap_t *instance, lub_heap_stats_t *stats) |
void | lub_heap_show (lub_heap_t *instance, bool_t verbose) |
size_t | lub_heap__get_max_free (lub_heap_t *instance) |
size_t | lub_heap__get_block_overhead (lub_heap_t *instance, const void *ptr) |
size_t | lub_heap__get_block_size (lub_heap_t *instance, const void *ptr) |
void | lub_heap_leak_scan (void) |
bool_t | lub_heap_leak_report (lub_heap_show_e how, const char *substring) |
void | lub_heap__set_framecount (unsigned framecount) |
unsigned | lub_heap__get_framecount (void) |
bool_t | lub_heap_validate_pointer (lub_heap_t *instance, char *ptr) |
void | lub_heap_init (const char *program_name) |
lub_heap_status_t | lub_heap_cache_init (lub_heap_t *instance, lub_heap_align_t max_block_size, size_t num_max_blocks) |
void | lub_heap_leak_suppress_detection (lub_heap_t *instance) |
void | lub_heap_leak_restore_detection (lub_heap_t *instance) |
size_t | lub_heap_overhead_size (lub_heap_align_t max_block_size, size_t num_max_blocks) |
lub_partition_t * | lub_partition_create (const lub_partition_spec_t *spec) |
void | lub_partition_kill (lub_partition_t *instance) |
lub_heap_status_t | lub_partition_realloc (lub_partition_t *instance, char **ptr, size_t size, lub_heap_align_t alignment) |
bool_t | lub_partition_check_memory (lub_partition_t *instance) |
void | lub_partition_show (lub_partition_t *instance, bool_t verbose) |
void | lub_partition_stop_here (lub_heap_status_t status, char *old_ptr, size_t new_size) |
Detailed Description
This is a generic heap manager which incorporates a memory leak detection system which can monitor and report the dynamic memory which is in use for each heap.
A thread safe dynamic memory alloction system for use in a multitasking operating system.
A client creates an instance of heap; providing it with memory segments to manage. Subsequent operations can then be invoked to obtain memory from those registered segments.
Static memory allocations are those which are for the lifetime of the heap from which they are allocated. Because they do not need to be freed there is zero overhead required for such blocks; they can be exactly butted up against each other in memory. There is also zero fragmentation as they are never freed.
Dynamic memory allocations have a lifetime less than that of the heap from which they are allocated. In order to manage the reuse of this blocks once they are released, there will be a slight "housekeeping" overhead associated with each block. They are also suceptible to fragmentation, which can occur when the lifetimes of blocks differ from one another.
It monitors the dynamic allocation which are performed and maintains statistics to help identify and isolation memory leaks.
It detects two types of leak by scanning the BSS and DATA segments and identifying any nodes referenced from there. Then each of these referenced nodes is scanned to look for further references.
there is no reference to a block of memory or to any memory within that block in the system.
there is no reference to the start of a block of memory. NB. there may be circumstances where this is not a real leak, e.g. memory allocation systems typically hand out references just beyond a control header to their clients. However there may also be instances where this is a real leak and someone just happens to have a reference to some contained data.
Memory is deliberately dirtied in the following ways:
- Initial heap space - 0xBBBBBBBB
- Allocated memory - 0xAAAAAAAA
- Freed memory - 0xFFFFFFFF
- Dead Stack memory - 0xCCCCCCCC (done before leak scan)
Currently the following utility functions are available:
- leakScan [0|1|2] - provides a dump of the currently allocated blocks of memory in the system pool. argument values have the following meanings:
- 0 - display stats for just memory leaks.
- 1 - display stats for memory leaks and partial leaks.
- 2 - display stats for all currently allocation memory blocks.
- leakEnable [framecount] - enables leak detection and causes the current statistics to be cleared out. Even if there are memory blocks in use, this command will cause future "leakShow" invocations to behave as if monitoring started from this new point in time. The optional 'framecount' argument can be used to change the number of levels of backtrace recorded. By default this number is 16. The number of contexts stored will be affected by this number. If the value is small then a limited number of contexts will exist and the memory overhead of monitoring will be reduced. If the number is large (can support a maximum of 16 levels) then the granularity of the contexts will be finer i.e. more of them, but the memory overhead in monitoring will be increased. With no specified framecount the maximum will be assumed.
- leakDisable - Disabled the leak detection.
Static and dynamic blocks are allocated from opposite ends of a memory segment. As static blocks are allocated the end of the last "free block" migrates downwards in memory. Dynamic blocks are allocated from the start of the appropriately sized free block, hence leaving space for static allocations at the end of the heap memory.
The heap implements a "best fit" model, for allocation of dynamic memory. This means that free blocks are maintained in size order and hence the most appropriate one can be used to satisfy client requests. This minimises fragmentation of the dynamically allocated memory.
The free blocks are held in a binary tree (using bintree) which provide fast searching for the appropriate block.
- Author:
- Graeme McKerrell
- Date:
- Created On : Wed Dec 14 10:20:00 2005
- Version:
- UNTESTED
This is a high level client of the lub_heap component and provides the following additional features:
The client doesn't need to provide memory storage for this partition. It will automatically obtain this from the system pool (malloc/free etc)
If cache details are provided then a small high performance heap, just big enough to hold the cache, is created on a per thread basis. This is referenced using thread specific storage within the owning thread and if it is unable to satisfy the request then a slower mutex locked global heap is created and used instead.
- The (slower) global heap will automatically extend itself as needed.
- Author:
- Graeme McKerrell
- Date:
- Created On : Wed Jun 27 14:00:00 2007
- Version:
- UNTESTED
Define Documentation
#define LUB_HEAP_ZERO_ALLOC ((void*)-1) |
This 'magic' pointer is returned when a client requests zero bytes The client can see that the allocation has succeeded, but cannot use the "memory" returned. This pointer may be passed transparently back to lub_heap_realloc() without impact.
Typedef Documentation
This type defines a function prototype to be used to iterate around each of a number of things in the system.
This type is used to reference an instance of a free block
This type defines the statistics available for each heap.
This type is used to reference an instance of a heap.
This type is used to specify any local_ requirements
This type is used to reference an instance of a heap.
Enumeration Type Documentation
This type is used to indicate the alignment required for a memory allocation.
- Enumerator:
-
LUB_HEAP_ALIGN_NATIVE |
This is the "native" alignment required for the current CPU architecture. |
LUB_HEAP_ALIGN_2_POWER_2 |
4 byte alignment |
LUB_HEAP_ALIGN_2_POWER_3 |
8 byte alignment |
LUB_HEAP_ALIGN_2_POWER_4 |
16 byte alignment |
LUB_HEAP_ALIGN_2_POWER_5 |
32 byte alignment |
LUB_HEAP_ALIGN_2_POWER_6 |
64 byte alignment |
LUB_HEAP_ALIGN_2_POWER_7 |
128 byte alignment |
LUB_HEAP_ALIGN_2_POWER_8 |
256 byte alignment |
LUB_HEAP_ALIGN_2_POWER_9 |
512 byte alignment |
LUB_HEAP_ALIGN_2_POWER_10 |
1024 byte alignment (1KB) |
LUB_HEAP_ALIGN_2_POWER_11 |
2048 byte alignment (2KB) |
LUB_HEAP_ALIGN_2_POWER_12 |
4096 byte alignment (4KB) |
LUB_HEAP_ALIGN_2_POWER_13 |
8192 byte alignment (8KB) |
LUB_HEAP_ALIGN_2_POWER_14 |
16384 byte alignment (16KB) |
LUB_HEAP_ALIGN_2_POWER_15 |
32768 byte alignment (32KB) |
LUB_HEAP_ALIGN_2_POWER_16 |
65536 byte alignment (64KB) |
LUB_HEAP_ALIGN_2_POWER_17 |
131072 byte alignment (128KB) |
LUB_HEAP_ALIGN_2_POWER_18 |
262144 byte alignment (256KB) |
LUB_HEAP_ALIGN_2_POWER_19 |
524288 byte alignment (512KB) |
LUB_HEAP_ALIGN_2_POWER_20 |
1048576 byte alignment (1MB) |
LUB_HEAP_ALIGN_2_POWER_21 |
2097152 byte alignment (2MB) |
LUB_HEAP_ALIGN_2_POWER_22 |
4194304 byte alignment (4MB) |
LUB_HEAP_ALIGN_2_POWER_23 |
8388608 byte alignment (8MB) |
LUB_HEAP_ALIGN_2_POWER_24 |
16777216 byte alignment (16MB) |
LUB_HEAP_ALIGN_2_POWER_25 |
33554432 byte alignment (32MB) |
LUB_HEAP_ALIGN_2_POWER_26 |
67108864 byte alignment (64MB) |
LUB_HEAP_ALIGN_2_POWER_27 |
134217728 byte alignment (128MB) |
This type defines how leak details should be displayed
- Enumerator:
-
LUB_HEAP_SHOW_LEAKS |
Only show allocations which have no reference elsewhere in the system |
LUB_HEAP_SHOW_PARTIALS |
Only show allocations which have no direct reference elsewhere in the system, but do have their contents referenced. |
LUB_HEAP_SHOW_ALL |
Show all the current allocations in the system. |
This type is used to indicate the result of a dynamic memory allocation
- Enumerator:
-
LUB_HEAP_OK |
The allocation was successful |
LUB_HEAP_FAILED |
There was insufficient resource to satisfy the request |
LUB_HEAP_DOUBLE_FREE |
An attempt has been made to release an already freed block of memory. |
LUB_HEAP_CORRUPTED |
A memory corruption has been detected. e.g. someone writing beyond the bounds of an allocated block of memory. |
LUB_HEAP_INVALID_POINTER |
The client has passed in an invalid pointer i.e. one which lies outside the bounds of the current heap. |
Function Documentation
size_t lub_heap__get_max_free |
( |
lub_heap_t * |
instance |
) |
|
This method provides the size, in bytes, of the largest allocation which can be performed.
- Precondition:
- The heap needs to have been created with an initial memory segment.
- Returns:
- size of largest possible allocation.
- Postcondition:
-
- Parameters:
-
instance |
The instance on which to operate |
This operation fills out a statistics structure with the details for the specified heap.
- Precondition:
-
- Postcondition:
- the results filled out are a snapshot of the statistics as the time of the call.
- Parameters:
-
instance |
The instance on which to operate |
stats |
A client provided structure to fill out with the heap details |
void lub_heap__set_framecount |
( |
unsigned |
framecount |
) |
|
- Parameters:
-
framecount |
The new framecount to use |
void lub_heap_add_segment |
( |
lub_heap_t * |
instance, |
|
|
void * |
start, |
|
|
size_t |
size | |
|
) |
| | |
This operation augments an existing heap with some more memory to manage. NB. if the memory happens to be follow on from the initial memory segment then the two will merge into a single larger segment. This means that a heap which is expanded with a sbrk() like mechanism will contain a single expandible segment.
- Precondition:
- The heap needs to have been create with an initial memory segment.
- Returns:
-
- Postcondition:
- The new segment of memory becomes available for use by this heap.
- Parameters:
-
instance |
The heap instance on which to operate |
start |
The beginning of the memory segment to be managed |
size |
The number of bytes available for use in this segment |
This operation adds a cache to the current heap, which speeds up the allocation and releasing of smaller block sizes.
- Precondition:
- The heap must have been initialised
- This call must not have been made on this heap before
- Returns:
- LUB_HEAP_OK if the cache was successfully set up.
- LUB_HEAP_FAILED if the cache was not set up for whatever reason
- Postcondition:
- memory allocations for smaller block sizes may come from the cache.
- Parameters:
-
instance |
The instance on which to operate |
max_block_size |
The maximum block size for the cache |
num_max_blocks |
The number of maximum sized blocks to make available. |
This operation controls runtime heap corruption detection. This means that during every heap operation a full check is done of the specified heap, before any allocations/free are performed. This has a performance overhead but provides a valuable aid in finding a memory corrupting client. Corruption will be spotted the first time a memory operation is performed AFTER it has occured.
By default checking is switched off.
- Precondition:
-
- Returns:
-
- Postcondition:
- (enabled) the heap will have been scanned for any corruption and if found the return status of the invoking heap operation will be LUB_HEAP_CORRUPTED.
- (disabled) no entire heap memory checking will occur.
- Parameters:
-
enable |
BOOL_TRUE to enable checking or BOOL_FALSE to disable |
This operation checks the integrety of the memory in the specified heap. Corruption will be spotted the first time a check is performed AFTER it has occured.
- Precondition:
- the specified heap will have been created
- Returns:
- BOOL_TRUE if the heap is OK
- BOOL_FALSE if the heap is corrupted.
- Postcondition:
-
lub_heap_t* lub_heap_create |
( |
void * |
start, |
|
|
size_t |
size | |
|
) |
| | |
This operation creates a dynamic heap from the provided memory segment.
- Precondition:
-
- Returns:
- a reference to a heap object which can be used to allocate memory from the segments associated with this heap.
- Postcondition:
- memory allocations can be invoked on the returned intance.
- further memory segements can be augmented to the heap using the lub_heap_add_segment() operation.
- Parameters:
-
start |
The begining of the first memory segment to associate with this heap |
size |
The number of bytes available for use in the first segment. |
This operation creates a dynamic heap from the provided memory segment.
- Precondition:
- The heap needs to have been create with an initial memory segment.
- Returns:
-
- Postcondition:
- The heap is no longer valid for use.
- The memory segment(s) previously given to the heap may now be reused.
- Any extra resources used for leak detection will have been released.
- Parameters:
-
instance |
The heap instance on which to operate |
This operation is a diagnostic which can be used to iterate around all the free blocks in the specified heap. For example it may be desirable to output information about each of the free blocks present.
- Precondition:
- The heap needs to have been create with an initial memory segment.
- Returns:
-
- Postcondition:
- -The specified function will have been called once for every free block in the specified heap
- Parameters:
-
instance |
The heap instance on which to operate |
fn |
The client provided function to call for each free block |
arg |
Some client specific data to pass through to the callback function. |
This operation is a diagnostic which can be used to iterate around all the segments in the specified heap. For example it may be desirable to output information about each of the segments present.
- Precondition:
- The heap needs to have been create with an initial memory segment.
- Returns:
-
- Postcondition:
- -The specified function will have been called once for every segment in the specified heap
- Parameters:
-
instance |
The heap instance on which to operate |
fn |
The client provided function to call for each free block |
arg |
Some client specific data to pass through to the callback function. |
void lub_heap_init |
( |
const char * |
program_name |
) |
|
This operation is used to initialise the heap management subsystem
- Precondition:
-
- Postcondition:
- The POSIX specific subsystem will be initialised to load the debugging symbols for the current executable. This enables the backtraces used for leak detection to show the full detail in the stack traces.
- If the system is configured at build time without GPL support (disabled by default) then only the address of each stack frame will be shown.
- Parameters:
-
program_name |
The full pathname of the current executable This is typically obtained from argv[0] in main() |
bool_t lub_heap_is_checking |
( |
void |
|
) |
|
This operation indicates the current status of the full memory checking facility.
- Precondition:
- none
- Returns:
- BOOL_TRUE if full memory checking is enabled.
- BOOL_FALSE if full memory checking is disabled.
- Postcondition:
- none
bool_t lub_heap_is_tainting |
( |
void |
|
) |
|
This operation indicates the current status of the memory tainting facility
- Precondition:
- none
- Returns:
- BOOL_TRUE if memory tainting is enabled.
- BOOL_FALSE if memory tainting is disabled.
- Postcondition:
- none
This function dumps all the context details for the heap to stdout. 'how' is one of the following values: 0 - show only leaks 1 - show partial leaks (no references to the start of the block) 2 - show all allocations (VERY VERBOSE)
NB. if tainting is switched off then this function will not perform any memory scanning and will simply show all the allocated blocks.
- Returns:
- a boolean indicating whether any leaks were displayed or not.
- Parameters:
-
how |
how to display the details |
substring |
an optional substring to use to filter contexts. Only contexts which contain the substring will be displayed |
void lub_heap_leak_restore_detection |
( |
lub_heap_t * |
instance |
) |
|
This operation signals the end of a section of code which should not have any of it's heap usage monitored by the leak detection code.
NB. you may nest the usage of lub_heap_leak_suppress_detection() and lub_heap_leak_restore_detection() in which case only when the outermost section has been terminated will monitoring commence again.
- Precondition:
- The heap must have been initialised
- lub_heap_start_unmonitored_section() must have been called.
- Returns:
-
- Postcondition:
- If leak detection is enabled then no subsequent allocations will be monitored until the lub_heap_end_unmonitored_section() is called.
- Parameters:
-
instance |
The instance on which to operate |
void lub_heap_leak_scan |
( |
void |
|
) |
|
This function scans memory to identify memory leaks
NB. if tainting is switched off then this function may miss some leaks as references may remain in freed memory.
void lub_heap_leak_suppress_detection |
( |
lub_heap_t * |
instance |
) |
|
This operation signals the start of a section of code which should not have any of it's heap usage monitored by the leak detection code.
- Precondition:
- The heap must have been initialised
- Returns:
-
- Postcondition:
-
- Parameters:
-
instance |
The instance on which to operate |
size_t lub_heap_overhead_size |
( |
lub_heap_align_t |
max_block_size, |
|
|
size_t |
num_max_blocks | |
|
) |
| | |
This operation returns the overhead, in bytes, which is required to implement a heap instance. This provide clients the means of calculating how much memory they need to assign for a heap instance to manage.
- Precondition:
-
- Returns:
- size in bytes of the overhead required by a lub_heap instance.
- Postcondition:
-
- Parameters:
-
max_block_size |
The maximum block size for the cache |
num_max_blocks |
The number of maximum sized blocks to make available. |
This operation changes the size of the object referenced by a passed in pointer to "size". The contents will be unchanged up to the minimum of the old and new sizes. If the new size is larger, the new space is uninitialised.
- Precondition:
- The heap needs to have been created with an initial memory segment.
- If "*ptr" contains a non-NULL value then this MUST have been allocated using this operation, from the same heap instance.
- Returns:
- the status of the operation.
- Postcondition:
- The client takes responsiblity for releasing any allocated memory when they are finished with it.
- If *ptr contains a non-NULL value, then after a succesfull call, the initial memory referenced by it may have been released for reuse, and the pointer modified to reference some new memory.
- *ptr may contain NULL in which case no memory will be released back to the heap for reuse, and the pointer is filled out with the allocated memory.
- (size == 0) No new memory will be allocated, *ptr will be set to NULL, and any original memory referenced by it will have been released.
- Parameters:
-
instance |
The heap instance on which to operate |
ptr |
Reference to a pointer containing previously allocated memory or NULL. |
size |
The number of bytes required for the object |
alignment |
The alignement required for a new allocations. |
This operation dumps the salient details of the specified heap to stdout
- Parameters:
-
instance |
The instance on which to operate |
verbose |
Whether to be verbose or not |
void* lub_heap_static_alloc |
( |
lub_heap_t * |
instance, |
|
|
size_t |
size | |
|
) |
| | |
This operation allocates some "static" memory from a heap. This is memory which will remain allocted for the lifetime of the heap instance. "static" memory allocation has zero overhead and causes zero fragmentation.
NB. static allocation are only handed out from the first memory segment
- Precondition:
- The heap needs to have been created with an initial memory segment.
- Returns:
- a pointer to some "static" memory which will be fixed for the remaining lifetime of this heap.
- Postcondition:
- The client cannot ever free this memory although if the heap is managing memory which itself has been dynamically allocated, then the memory will be recovered when the heap is released.
- Parameters:
-
instance |
The heap instance on which to operate |
size |
The number of bytes to allocate |
void lub_heap_stop_here |
( |
lub_heap_status_t |
status, |
|
|
char * |
old_ptr, |
|
|
size_t |
new_size | |
|
) |
| | |
This function is invoked whenever a call to lub_heap_realloc() fails. It is provided as a debugging aid; simple set a breakpoint to stop execution of the program and any failures will be caught in context.
- Parameters:
-
status |
The failure status of the the call to realloc |
old_ptr |
The old value of the pointer passed in |
new_size |
The requested number of bytes |
This operation controls the tainted memory facility. This means that during certain heap operations memory can be filled with some well defined bit patterns. This causes a slight performance overhead but can be used to shake out bugs such and free-memory-reads and uninitialised-memory-reads
By default tainting is switched off.
- Precondition:
-
- Returns:
-
- Postcondition:
- (enabled) when a memory segment is given to a heap (either at creation or later) the contents will be set to 0xBB
- (enabled) when some dynamically allocated memory is released back to a heap the contents will be set to 0xFF
- (enabled) when some dynamic or static memory is allocated the contents will be set to 0xAA as the "uninitialised" value.
- (disabled) no memory tainting will occur.
- Parameters:
-
enable |
BOOL_TRUE to enable tainting or BOOL_FALSE to disable |
This operation checks the integrety of the memory in the specified partition. Corruption will be spotted the first time a check is performed AFTER it has occured.
- Precondition:
- the specified partition will have been created
- Returns:
- BOOL_TRUE if the partition is OK
- BOOL_FALSE if the partition is corrupted.
- Postcondition:
-
This operation creates a partition
- Precondition:
- The system pool needs to be accessible
- Returns:
- a reference to a partition object which can be used to allocate memory
- Postcondition:
- memory allocations can be invoked on the returned intance.
- Parameters:
-
spec |
This is used to specify the details to be used for the partition. |
This operation starts the process of killing a partition.
- Precondition:
- The partition needs to have been created.
- Returns:
-
- Postcondition:
- The partition will no longer hand out memory.
- When the final outstanding piece of memory is handed back the partition will destroy itself.
- Upon final destruction any resources obtained from the system pool will be returned.
- Parameters:
-
instance |
The heap instance on which to operate |
This operation changes the size of the object referenced by a passed in pointer to "size". The contents will be unchanged up to the minimum of the old and new sizes. If the new size is larger, the new space is uninitialised.
- Precondition:
- The partition needs to have been created.
- If "*ptr" contains a non-NULL value then this MUST have been allocated using this operation, from the same heap instance.
- Returns:
- the status of the operation.
- Postcondition:
- The client takes responsiblity for releasing any allocated memory when they are finished with it.
- If *ptr contains a non-NULL value, then after a succesfull call, the initial memory referenced by it may have been released for reuse, and the pointer modified to reference some new memory.
- *ptr may contain NULL in which case no memory will be released back to the heap for reuse, and the pointer is filled out with the allocated memory.
- (size == 0) No new memory will be allocated, *ptr will be set to NULL, and any original memory referenced by it will have been released.
- Parameters:
-
instance |
The partition instance on which to operate |
ptr |
Reference to a pointer containing previously allocated memory or NULL. |
size |
The number of bytes required for the object |
alignment |
The alignment required for a new allocations. |
This operation dumps the salient details of the specified partition to stdout
- Parameters:
-
instance |
The instance on which to operate |
verbose |
Whether to be verbose or not |
void lub_partition_stop_here |
( |
lub_heap_status_t |
status, |
|
|
char * |
old_ptr, |
|
|
size_t |
new_size | |
|
) |
| | |
This function is invoked whenever a call to lub_partition_realloc() fails. It is provided as a debugging aid; simple set a breakpoint to stop execution of the program and any failures will be caught in context.
- Parameters:
-
status |
The failure status of the the call to realloc |
old_ptr |
The old value of the pointer passed in |
new_size |
The requested number of bytes |