memory.h File Reference

Portable substitutes of standard malloc() and free() functions. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdlib.h>

Go to the source code of this file.

Classes
struct	cmagic_memory_alloc_packet_t
	Set of allocation functions. Used in some CMagic structures to specify a desired memory pool. More...

Typedefs
typedef void *(*	cmagic_memory_malloc_fptr_t) (size_t size)
	A pointer to malloc like function. More...
typedef void *(*	cmagic_memory_realloc_fptr_t) (void *ptr, size_t size)
	A pointer to realloc like function. More...
typedef void(*	cmagic_memory_free_fptr_t) (void *ptr)
	A pointer to free like function. More...

Enumerations
enum	cmagic_memory_free_result {   CMAGIC_MEMORY_FREE_RESULT_OK, CMAGIC_MEMORY_FREE_RESULT_OK_NULLPTR, CMAGIC_MEMORY_FREE_RESULT_ERR_NOT_ALLOCATED_BEFORE, CMAGIC_MEMORY_FREE_RESULT_ERR_ADDRESS_OUTSIDE_MEMORY_POOL,   CMAGIC_MEMORY_FREE_RESULT_ERR_UNINITIALIZED }
	Type of result returned from cmagic_memory_free_ext. More...

Functions
void	cmagic_memory_init (void *static_memory_pool, size_t static_memory_pool_size)
	Sets a memory range where all dynamic allocated objects will reside. More...
void *	cmagic_memory_malloc (size_t size)
	Dynamically allocates a block of memory of requested size, returning a pointer to the beginning of the block. More...
void *	cmagic_memory_realloc (void *ptr, size_t size)
	Reallocates memory block changing its original size. More...
enum cmagic_memory_free_result	cmagic_memory_free_ext (void *ptr)
	Extended version of cmagic_memory_free. More...
void	cmagic_memory_free (void *ptr)
	Deallocates a block of memory previously allocated by a call to cmagic_memory_malloc or cmagic_memory_realloc is deallocated, making it available again for further allocations. More...
bool	cmagic_memory_is_allocated (void *ptr)
	Checks if the memory block was allocated before with cmagic_memory_malloc or cmagic_memory_realloc and not freed yet. More...
size_t	cmagic_memory_get_allocated_bytes (void)
	Returns the sum of currently allocated bytes. More...
size_t	cmagic_memory_get_free_bytes (void)
	Returns number of free bytes in the memory pool. More...
size_t	cmagic_memory_get_allocations (void)
	Returns number of allocations made by cmagic_memory_malloc. More...

Variables
static const cmagic_memory_alloc_packet_t	CMAGIC_MEMORY_ALLOC_PACKET_STD
	Allocation from the standard library. More...
static const cmagic_memory_alloc_packet_t	CMAGIC_MEMORY_ALLOC_PACKET_CUSTOM_CMAGIC
	Custom allocation from the CMagic library. More...

Detailed Description

Portable substitutes of standard malloc() and free() functions.

Does not use any platform dependent system calls. Everything is maintained in a static memory block.

Typedef Documentation

cmagic_memory_free_fptr_t

typedef void(* cmagic_memory_free_fptr_t) (void *ptr)

A pointer to free like function.

cmagic_memory_malloc_fptr_t

typedef void*(* cmagic_memory_malloc_fptr_t) (size_t size)

A pointer to malloc like function.

cmagic_memory_realloc_fptr_t

typedef void*(* cmagic_memory_realloc_fptr_t) (void *ptr, size_t size)

A pointer to realloc like function.

Enumeration Type Documentation

cmagic_memory_free_result

enum cmagic_memory_free_result

Type of result returned from cmagic_memory_free_ext.

Values with OK word are successful cmagic_memory_free_ext calls. Values with ERR word indicate invalid usage of the dynamic allocations. In such cases user should inspect

Enumerator
CMAGIC_MEMORY_FREE_RESULT_OK	The memory block was freed successfully.
CMAGIC_MEMORY_FREE_RESULT_OK_NULLPTR	Function was called on a NULL pointer. It's not an error.
CMAGIC_MEMORY_FREE_RESULT_ERR_NOT_ALLOCATED_BEFORE	Tried to free a memory block which was not allocated before or already freed.
CMAGIC_MEMORY_FREE_RESULT_ERR_ADDRESS_OUTSIDE_MEMORY_POOL	Function was called on a pointer outside the memory pool specified with cmagic_memory_init.
CMAGIC_MEMORY_FREE_RESULT_ERR_UNINITIALIZED	cmagic_memory_init was not called before performing any dynamic memory operations.

Function Documentation

cmagic_memory_free()

void cmagic_memory_free

(

void *

ptr

)

Deallocates a block of memory previously allocated by a call to cmagic_memory_malloc or cmagic_memory_realloc is deallocated, making it available again for further allocations.

Does nothing for NULL pointer or pointer not allocated with above functions. Errors can be retrieved by using extended version of this function cmagic_memory_free_ext. It never causes undefined behavior. But undefined behavior occurs if user dereferences pointer after calling this function (use after free). Notice that this function does not change the value of ptr itself, hence it still points to the same (now invalid) location. For Debug build configuration this function triggers an assertion if ptr is invalid or already freed.

Complexity

O(1)

Parameters

ptr	address of a memory block to be freed or NULL

cmagic_memory_free_ext()

enum cmagic_memory_free_result cmagic_memory_free_ext

(

void *

ptr

)

Extended version of cmagic_memory_free.

Mainly for debug purposes. Allows to detect invalid dynamic memory management.

Parameters

ptr	address of a memory block to be freed or NULL

Returns

status value indicating operation success or error

cmagic_memory_get_allocated_bytes()

size_t cmagic_memory_get_allocated_bytes

(

void

)

Returns the sum of currently allocated bytes.

cmagic_memory_get_allocations()

size_t cmagic_memory_get_allocations

(

void

)

Returns number of allocations made by cmagic_memory_malloc.

Every successful call to cmagic_memory_malloc increments this value. Every successful call to cmagic_memory_free decrements this value. A call to cmagic_memory_realloc doesn't change this value.

Implementation details

Internally this fuction counts a number of special nodes mentioned in the description of cmagic_memory_malloc.

cmagic_memory_get_free_bytes()

size_t cmagic_memory_get_free_bytes

(

void

)

Returns number of free bytes in the memory pool.

There is not a guarantee that a next cmagic_memory_malloc with a size less than the result returned from this function won't fail. It is so because the free bytes may not form continuous free space range.

cmagic_memory_init()

void cmagic_memory_init	(	void *	static_memory_pool,
		size_t	static_memory_pool_size
	)

Sets a memory range where all dynamic allocated objects will reside.

Must be called exactly once before any call to any other function from this header. Sets a memory range which will be used by every other function from this header and it must be valid during these calls. So generally it should be located in the static memory to be accessible during the whole program run time. Typical use is to declare a static array of chars of a sane size and pass it to this function.

Parameters

static_memory_pool	address of a static byte array declared by user
static_memory_pool_size	size of the static array

cmagic_memory_is_allocated()

bool cmagic_memory_is_allocated

(

void *

ptr

)

Checks if the memory block was allocated before with cmagic_memory_malloc or cmagic_memory_realloc and not freed yet.

Mainly for debug purposes. Allows to detect invalid dynamic memory management.

Parameters

ptr	address of a memory block to checked

Returns

true if the memory block is allocated and can be freed, false otherwise

cmagic_memory_malloc()

void* cmagic_memory_malloc

(

size_t

size

)

Dynamically allocates a block of memory of requested size, returning a pointer to the beginning of the block.

The content of the newly allocated block of memory is not initialized, remaining with indeterminate values. When the memory block is no longer needed it can be freed using cmagic_memory_free.

Implementation details

The memory pool set by cmagic_memory_init is divided into equal size blocks. Every block is either raw data or a special node. Special node holds an information about number of bytes allocated right after it. Special nodes form a linked list. When cmagic_memory_malloc is called the linked list is traversed in search of holes of unallocated memory. If a hole big enough is found a new special node is created and inserted into the linked list. Then the address after the special node is returned. If all holes are too small or there is just no holes at all, the special node is added at the end of the linked list.

Complexity

O(n)

Parameters

size	size of the memory block to allocate, in bytes

Returns

On success, a pointer to the memory block allocated by the function. The type of this pointer is always void*, which can be cast to the desired type of data pointer in order to be dereferenceable. If the function failed to allocate the requested block of memory, a NULL pointer is returned.

cmagic_memory_realloc()

void* cmagic_memory_realloc	(	void *	ptr,
		size_t	size
	)

Reallocates memory block changing its original size.

Changes the size of the memory block pointed to by ptr. May move the memory block to a new location (whose address is returned by the function). The content of the memory block is preserved up to the lesser of the new and old sizes, even if the block is moved to a new location. If the new size is larger, the value of the newly allocated portion is indeterminate. In case that ptr is a NULL pointer, the function behaves like cmagic_memory_malloc, assigning a new block of size bytes and returning a pointer to its beginning.

Complexity

O(1) if size is lower or equal to the original size, O(n) otherwise

Parameters

ptr	pointer to the memory block allocated before by cmagic_memory_malloc or cmagic_memory_realloc
size	updated size of the memory block

Returns

pointer to a possibly new memory block or NULL if reallocation failed. In such a case original ptr is as still valid pointer to an unmodified memory block.

Variable Documentation

CMAGIC_MEMORY_ALLOC_PACKET_CUSTOM_CMAGIC

const cmagic_memory_alloc_packet_t CMAGIC_MEMORY_ALLOC_PACKET_CUSTOM_CMAGIC

static

Initial value:

= {
    cmagic_memory_malloc, cmagic_memory_realloc, cmagic_memory_free
}

Custom allocation from the CMagic library.

CMAGIC_MEMORY_ALLOC_PACKET_STD

const cmagic_memory_alloc_packet_t CMAGIC_MEMORY_ALLOC_PACKET_STD

static

Initial value:

= {
    malloc, realloc, free
}

Allocation from the standard library.