The Memory Management Library  0.2.1
Data Structures | Defines | Typedefs | Variables
memory.h File Reference

Documentation for Memory Management Library (CBL) More...

#include <stddef.h>
#include <stdio.h>
#include "cbl/except.h"
Include dependency graph for memory.h:
This graph shows which files directly or indirectly include this file:

Data Structures

struct  mem_loginfo_t
 contains the information about invalid memory operations. More...

Defines

#define MEM_ALLOC(n)   (mem_alloc((n), __FILE__, __LINE__))
 allocates storage of the size n in bytes.
#define MEM_CALLOC(c, n)   (mem_calloc((c), (n), __FILE__, __LINE__))
 allocation zero-filled storage of the size c * n in bytes.
#define MEM_NEW(p)   ((p) = MEM_ALLOC(sizeof *(p)))
 allocates to p storage whose size is determined by the size of the pointed-to type by p.
#define MEM_NEW0(p)   ((p) = MEM_CALLOC(1, sizeof *(p)))
 allocates to p zero-filled storage whose size is determined by the size of the pointed-to type by p.
#define MEM_FREE(p)   ((void)(mem_free((p), __FILE__, __LINE__), (p)=0))
 deallocates storage pointed to by p and set it to a null pointer.
#define MEM_RESIZE(p, n)   ((p) = mem_resize((p), (n), __FILE__, __LINE__))
 adjusts the size of storage pointed to by p to n bytes.

Typedefs

typedef struct mem_loginfo_t mem_loginfo_t
 contains the information about invalid memory operations.

Functions

memory allocating functions:
void * mem_alloc (size_t, const char *, int)
 allocates storage of the size n in bytes.
void * mem_calloc (size_t, size_t, const char *, int)
 allocates zero-filled storage of the size c * n in bytes.
memory deallocating functions:
void mem_free (void *, const char *, int)
 deallocates storage pointed to by p.
memory resizing functions:
void * mem_resize (void *, size_t, const char *, int)
 adjust the size of storage pointed to by p to n.
memory debugging functions:
void mem_log (FILE *, void(FILE *, const mem_loginfo_t *), void(FILE *, const mem_loginfo_t *))
void mem_leak (void(const mem_loginfo_t *, void *), void *)

Variables

const except_t mem_exceptfail
 exception for memory allocation failure.

Detailed Description

Documentation for Memory Management Library (CBL)

Header for Memory Management Library (CBL)


Define Documentation

#define MEM_FREE (   p)    ((void)(mem_free((p), __FILE__, __LINE__), (p)=0))

deallocates storage pointed to by p and set it to a null pointer.

See mem_free() for details.

Warning:
p must be a modifiable lvalue; a rvalue expression or non-modifiable lvalue like one qualified by const is not allowed. Also, MEM_FREE() evaluates its argument twice, so an argument containing side effects results in an unpredictable result.

Possible exceptions: none

Unchecked errors: foreign value given for p

#define MEM_NEW (   p)    ((p) = MEM_ALLOC(sizeof *(p)))

allocates to p storage whose size is determined by the size of the pointed-to type by p.

A common way to allocate storage to a pointer p is as follows:

      type *p;
      p = malloc(sizeof(type));

However, this is error-prone; it might cause the memory corrupted if one forget to change every instance of type when the type of p changes to, say, another_type. To preclude problems like this a proposed way to allocate storage for a pointer p is:

      p = malloc(sizeof(*p));

In this code, changing the type of p is automatically reflected to the allocation code above. Note that the expression given in the sizeof expression is not evaluated, so the validity of p's value does not matter here.

The macro MEM_NEW() is provided to facilitate such usage. It takes a pointer as an argument and allocates to it storage whose size is the size of the referrenced type. Therefore it makes an invalid call to invoke MEM_NEW() with a pointer to an imconplete type like a pointer to void and a pointer to a structure whose type definition is not visible.

Note that the sizeof operator does not evaluate its operand, which makes MEM_NEW() evaluate its argument exactly once as an actual function does. Embedding a side effect in the argument, however, is discouraged.

Possible exceptions: mem_exceptfail

Unchecked errors: none

#define MEM_NEW0 (   p)    ((p) = MEM_CALLOC(1, sizeof *(p)))

allocates to p zero-filled storage whose size is determined by the size of the pointed-to type by p.

The same explanation for MEM_NEW() applies. See MEM_NEW() for details.

Possible exceptions: mem_exceptfail

Unchecked errors: none

#define MEM_RESIZE (   p,
 
)    ((p) = mem_resize((p), (n), __FILE__, __LINE__))

adjusts the size of storage pointed to by p to n bytes.

See mem_resize() for details.

Possible exceptions: mem_exceptfail, assert_exceptfail

Unchecked errors: foreign value given for p

Warning:
MEM_RESIZE() evaluates its argument twice. An argument containing side effects results in an unpredictable result.

Typedef Documentation

typedef struct mem_loginfo_t mem_loginfo_t

contains the information about invalid memory operations.

An object of the type mem_loginfo_t is used when the information about an invalid memory operation is delivered to a user-provided log function. As explained in mem_log(), such a function must be declared to accept a mem_loginfo_t arguments.

Its members contains three kinds of information:

  • the information about an invalid memory operation. For example, if mem_free() is invoked for the storage that is already deallocated, the pointer given to mem_free() is passed through p. In the case of mem_resize(), the requested size is also available in size.
  • the information to locate an invalid memory operation. The file name, function name and line number where a problem occurred are provided through ifile, ifunc and iline, respectively.
  • the information about the memory block for which an invalid memory operation is invoked. For example, the "free-free" case (a.k.a., "double free") means that the pointer value delivered to mem_free() has been deallocated before. afile, afunc, aline and asize provide where it was allocated and what its size was. This information is useful in tracking how such an invalid operation was made.

If any of them is not available, they are set to a null pointer (for ifile, ifunc, afile and afunc) or 0 (for size, iline, aline and asize).

Warning:
Logging invalid memory operations is activated by mem_log() which is available only when the debugging version (not the production version) is used.

Function Documentation

void* mem_alloc ( size_t  n,
const char *  file,
int  line 
)

allocates storage of the size n in bytes.

mem_alloc() does the same job as malloc() except:

  • mem_alloc() raises an exception when fails the requested allocation;
  • mem_alloc() does not take 0 as the byte length to preclude the possibility of returning a null pointer;
  • mem_alloc() never returns a null pointer.

Possible exceptions: mem_exceptfail, assert_exceptfail

Unchecked errors: none

Parameters:
[in]nsize in bytes for storage to be allocated
[in]filefile name in which storage requested
[in]funcfunction name in which strage requested (if C99 supported)
[in]lineline number on which storage requested
Returns:
pointer to allocated storage
Warning:
mam_alloc() returns no null pointer in any case. Allocation failure triggers an exception, so no need to handle an exceptional case with the return value.

allocates storage of the size n in bytes.

Some general explanation on mem_alloc() can be found on the production version of the library.

Possible exceptions: mem_exceptfail, assert_exceptfail

Unchecked errors: none

Parameters:
[in]nsize of memory block requested in bytes
[in]filefile name in which allocation requested
[in]funcfunction name in which allocation requested (if C99 supported)
[in]linelinu number on which allocation requested
Returns:
memory block requested

Here is the caller graph for this function:

void* mem_calloc ( size_t  c,
size_t  n,
const char *  file,
int  line 
)

allocates zero-filled storage of the size c * n in bytes.

mem_calloc() does the same job as mem_alloc() except that the storage it allocates are zero- filled. The similar explanation as for mem_alloc() applies to mem_calloc() too; see mem_alloc() for details.

Possible exceptions: mem_exceptfail, assert_exceptfail

Unchecked errors: none

Parameters:
[in]cnumber of items to be allocated
[in]nsize in bytes for one item
[in]filefile name in which storage requested
[in]funcfunction name in which strage requested (if C99 supported)
[in]lineline number on which storage requested
Returns:
pointer to allocated (zero-filled) storage

allocates zero-filled storage of the size c * n in bytes.

mem_calloc() returns a zero-filled memory block whose size is at least n. mem_calloc() allocates a memory block by invoking mem_malloc() and set its every byte to zero by memset(). The similar explanation as for mem_alloc() applies to mem_calloc() too; see mem_alloc().

Possible exceptions: assert_exceptfail, mem_exceptfail

Unchecked errors: none

Parameters:
[in]cnumber of items to be allocated
[in]nsize in bytes for one item
[in]filefile name in which allocation requested
[in]funcfunction name in which allocation requested (if C99 supported)
[in]lineline number on which allocation requested
Returns:
pointer to allocated (zero-filled) memory block
Todo:
Improvements are possible and planned:
  • the C standard requires calloc() return a null pointer if it can allocates no storage of the size c * n in bytes, which allows no overflow in computing the multiplication. Overflow checking is necessary to mimic the behavior of calloc().

Here is the call graph for this function:

void mem_free ( void *  p,
const char *  file,
int  line 
)

deallocates storage pointed to by p.

mem_free() is a simple wrapper function for free().

The additional parameters, file, func (if C99 supported), line are for the consistent form in the calling sites; the debugging version of this library takes advantage of them to raise an exception when something goes wrong in mem_free(). When using the debugging version, some of the following unchecked errors are to be detected.

Possible exceptions: none

Unchecked errors: foreign value given for p

Warning:
A "foreign" value also includes a pointer value which points to storage already moved to a different address by, say, mem_resize().
Parameters:
[in]ppointer to storage to release
[in]filefile name in which deallocation requested
[in]funcfunction name in which deallocation requested (if C99 supported)
[in]lineline number on which deallocation requested
Returns:
nothing

deallocates storage pointed to by p.

mem_free() releases a given memory block.

Possible exceptions: assert_exceptfail

Unchecked errors: none

Parameters:
[in]ppointer to memory block to release (to mark as "freed")
[in]filefile name in which deallocation requested
[in]funcfunction name in which deallocation requested (if C99 supported)
[in]lineline number on which deallocation is requested
Returns:
nothing

Here is the call graph for this function:

Here is the caller graph for this function:

void* mem_resize ( void *  p,
size_t  n,
const char *  file,
int  line 
)

adjust the size of storage pointed to by p to n.

mem_resize() does the main job of realloc(); adjusting the size of storage already allocated by mem_alloc() or mem_calloc(). While realloc() deallocates like free() when the given size is 0 and allocates like malloc() when the given pointer is a null pointer, mem_resize() accepts neither a null pointer nor zero as its arguments. The similar explanation as for mem_alloc() also applies to mem_resize(). See mem_alloc() for details.

Possible exceptions: mem_exceptfail, assert_exceptfail

Unchecked errors: foreign value given for p

Parameters:
[in]ppointer to storage whose size to be adjusted
[in]nnew size for storage in bytes
[in]filefile name in which adjustment requested
[in]funcfunction name in which adjustment requested (if C99 supported)
[in]lineline number on which adjustment requested
Returns:
pointer to size-adjusted storage

adjust the size of storage pointed to by p to n.

mem_resize() does the main job of realloc(); adjusting the size of the memory block already allocated by mem_alloc() or mem_calloc(). While realloc() deallocates like free() when the given size is 0 and allocates like malloc() when the given pointer is a null pointer, mem_resize() accepts neither a null pointer nor zero as its arguments. The similar explanation as for mem_alloc() also applies to mem_resize(). See mem_alloc() for details.

Possible exceptions: mem_exceptfail, assert_exceptfail

Unchecked errors: none

Parameters:
[in]ppointer to memory block whose size to be adjusted
[in]nnew size for memory block in bytes
[in]filefile name in which adjustment requested
[in]funcfunction name in which adjustment requested (if C99 supported)
[in]lineline number on which adjustment requested
Returns:
pointer to size-adjusted memory block

Here is the call graph for this function:

Here is the caller graph for this function:

 All Data Structures Files Functions Variables Typedefs Defines