CLISH  0.7.3
Data Structures | Macros | Typedefs | Enumerations | Functions

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
 

Macros

#define LUB_HEAP_ZERO_ALLOC   ((void*)-1)
 

Typedefs

typedef typedef_BEGIN_C_DECL
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 typedef_BEGIN_C_DECL
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_tlub_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_tlub_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 allocation

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 allocation

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.

Leak Detection

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.

Full Leak

there is no reference to a block of memory or to any memory within that block in the system.

Partial Leak

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 Tainting

Memory is deliberately dirtied in the following ways:

Utility functions

Currently the following utility functions are available:

Implementation

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:

Automatically obtains its resources

The client doesn't need to provide memory storage for this partition. It will automatically obtain this from the system pool (malloc/free etc)

Multi-threading performance

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.

Automatically extends itself

Author
Graeme McKerrell
Date
Created On : Wed Jun 27 14:00:00 2007
Version
UNTESTED

Macro Definition 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

typedef void lub_heap_foreach_fn(void *block,unsigned index,size_t size,void *arg)

This type defines a function prototype to be used to iterate around each of a number of things in the system.

typedef struct lub_heap_free_block_s lub_heap_free_block_t

This type is used to reference an instance of a free block

This type defines the statistics available for each heap.

typedef typedef_BEGIN_C_DECL struct lub_heap_s lub_heap_t

This type is used to reference an instance of a heap.

This type is used to specify any local_ requirements

typedef typedef_BEGIN_C_DECL struct _lub_partition lub_partition_t

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
  • none
Parameters
instanceThe instance on which to operate
void lub_heap__get_stats ( lub_heap_t instance,
lub_heap_stats_t stats 
)

This operation fills out a statistics structure with the details for the specified heap.

Precondition
  • none
Postcondition
  • the results filled out are a snapshot of the statistics as the time of the call.
Parameters
instanceThe instance on which to operate
statsA client provided structure to fill out with the heap details
void lub_heap__set_framecount ( unsigned  framecount)
Parameters
framecountThe 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
  • none
Postcondition
  • The new segment of memory becomes available for use by this heap.
Parameters
instanceThe heap instance on which to operate
startThe beginning of the memory segment to be managed
sizeThe number of bytes available for use in this segment
lub_heap_status_t lub_heap_cache_init ( lub_heap_t instance,
lub_heap_align_t  max_block_size,
size_t  num_max_blocks 
)

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
instanceThe instance on which to operate
max_block_sizeThe maximum block size for the cache
num_max_blocksThe number of maximum sized blocks to make available.
bool_t lub_heap_check ( bool_t  enable)

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
  • none
Returns
  • last checking status
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
enableBOOL_TRUE to enable checking or BOOL_FALSE to disable
bool_t lub_heap_check_memory ( lub_heap_t instance)

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
  • none
lub_heap_t* lub_heap_create ( void *  start,
size_t  size 
)

This operation creates a dynamic heap from the provided memory segment.

Precondition
  • none
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
startThe begining of the first memory segment to associate with this heap
sizeThe number of bytes available for use in the first segment.
void lub_heap_destroy ( lub_heap_t instance)

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
  • none
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
instanceThe heap instance on which to operate
void lub_heap_foreach_free_block ( lub_heap_t instance,
lub_heap_foreach_fn fn,
void *  arg 
)

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
  • none
Postcondition
-The specified function will have been called once for every free block in the specified heap
Parameters
instanceThe heap instance on which to operate
fnThe client provided function to call for each free block
argSome client specific data to pass through to the callback function.
void lub_heap_foreach_segment ( lub_heap_t instance,
lub_heap_foreach_fn fn,
void *  arg 
)

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
  • none
Postcondition
-The specified function will have been called once for every segment in the specified heap
Parameters
instanceThe heap instance on which to operate
fnThe client provided function to call for each free block
argSome 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
  • none
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_nameThe 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
bool_t lub_heap_leak_report ( lub_heap_show_e  how,
const char *  substring 
)

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
howhow to display the details
substringan 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
  • none
Postcondition
  • If leak detection is enabled then no subsequent allocations will be monitored until the lub_heap_end_unmonitored_section() is called.
Parameters
instanceThe 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
  • none
Postcondition
Parameters
instanceThe 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
  • none
Returns
  • size in bytes of the overhead required by a lub_heap instance.
Postcondition
  • none
Parameters
max_block_sizeThe maximum block size for the cache
num_max_blocksThe number of maximum sized blocks to make available.
lub_heap_status_t lub_heap_realloc ( lub_heap_t instance,
char **  ptr,
size_t  size,
lub_heap_align_t  alignment 
)

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
instanceThe heap instance on which to operate
ptrReference to a pointer containing previously allocated memory or NULL.
sizeThe number of bytes required for the object
alignmentThe alignement required for a new allocations.
void lub_heap_show ( lub_heap_t instance,
bool_t  verbose 
)

This operation dumps the salient details of the specified heap to stdout

Parameters
instanceThe instance on which to operate
verboseWhether 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
instanceThe heap instance on which to operate
sizeThe 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
statusThe failure status of the the call to realloc
old_ptrThe old value of the pointer passed in
new_sizeThe requested number of bytes
bool_t lub_heap_taint ( bool_t  enable)

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
  • none
Returns
  • last tainted status
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
enableBOOL_TRUE to enable tainting or BOOL_FALSE to disable
bool_t lub_partition_check_memory ( lub_partition_t instance)

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
  • none
lub_partition_t* lub_partition_create ( const lub_partition_spec_t spec)

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
specThis is used to specify the details to be used for the partition.
void lub_partition_kill ( lub_partition_t instance)

This operation starts the process of killing a partition.

Precondition
  • The partition needs to have been created.
Returns
  • none
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
instanceThe heap instance on which to operate
lub_heap_status_t lub_partition_realloc ( lub_partition_t instance,
char **  ptr,
size_t  size,
lub_heap_align_t  alignment 
)

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
instanceThe partition instance on which to operate
ptrReference to a pointer containing previously allocated memory or NULL.
sizeThe number of bytes required for the object
alignmentThe alignment required for a new allocations.
void lub_partition_show ( lub_partition_t instance,
bool_t  verbose 
)

This operation dumps the salient details of the specified partition to stdout

Parameters
instanceThe instance on which to operate
verboseWhether 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
statusThe failure status of the the call to realloc
old_ptrThe old value of the pointer passed in
new_sizeThe requested number of bytes