giomba/nes-proj
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Added some Doxygen documentation for the heapmem module.

Browse Source
This commit is contained in:
Nicolas Tsiftes 2017-06-22 14:49:00 +02:00
parent 88144ced73
commit 620edd1ab6
2 changed files with 151 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
core/lib/heapmem.c
View File

@ -306,8 +306,20 @@ get_free_chunk(const size_t size)
return best;
}
/* heapmem_alloc: Allocate an object of the specified size, returning a pointer
to it in case of success, and NULL in case of failure. */
/*
* heapmem_alloc: Allocate an object of the specified size, returning
* a pointer to it in case of success, and NULL in case of failure.
*
* When allocating memory, heapmem_alloc() will first try to find a
* free chunk of the same size and the requested one. If none can be
* find, we pick a larger chunk that is as close in size as possible,
* and possibly split it so that the remaining part becomes a chunk
* available for allocation. At most CHUNK_SEARCH_MAX chunks on the
* free list will be examined.
*
* As a last resort, heapmem_alloc() will try to extend the heap
* space, and thereby create a new chunk available for use.
*/
void *
#if HEAPMEM_DEBUG
heapmem_alloc_debug(size_t size, const char *file, const unsigned line)
@ -341,9 +353,16 @@ heapmem_alloc(size_t size)
}
/*
* heapmem_free: Deallocate a previously allocated object. The pointer must
* exactly match one returned from an earlier call from heapmem_alloc or
* heapmem_realloc, without any call to heapmem_free in between.
* heapmem_free: Deallocate a previously allocated object.
*
* The pointer must exactly match one returned from an earlier call
* from heapmem_alloc or heapmem_realloc, without any call to
* heapmem_free in between.
*
* When performing a deallocation of a chunk, the chunk will be put on
* a list of free chunks internally. All free chunks that are adjacent
* in memory will be merged into a single chunk in order to mitigate
* fragmentation.
*/
void
#if HEAPMEM_DEBUG
@ -365,12 +384,26 @@ heapmem_free(void *ptr)
}
#if HEAPMEM_REALLOC
/* heapmem_realloc: Reallocate an object with a different size, possibly moving
it in memory. In case of success, the function returns a pointer to the
objects new location. In case of failure, it returns NULL. */
/*
* heapmem_realloc: Reallocate an object with a different size,
* possibly moving it in memory. In case of success, the function
* returns a pointer to the objects new location. In case of failure,
* it returns NULL.
*
* If the size of the new chunk is larger than that of the allocated
* chunk, heapmem_realloc() will first attempt to extend the currently
* allocated chunk. If that memory is not free, heapmem_ralloc() will
* attempt to allocate a completely new chunk, copy the old data to
* the new chunk, and deallocate the old chunk.
*
* If the size of the new chunk is smaller than the allocated one, we
* split the allocated chunk if the remaining chunk would be large
* enough to justify the overhead of creating a new chunk.
*/
void *
#if HEAPMEM_DEBUG
heapmem_realloc_debug(void *ptr, size_t size, const char *file, const unsigned line)
heapmem_realloc_debug(void *ptr, size_t size,
const char *file, const unsigned line)
#else
heapmem_realloc(void *ptr, size_t size)
#endif

120
core/lib/heapmem.h
View File

@ -28,12 +28,48 @@
*/
/**
* \file
* Declarations for the dynamic memory allocation module.
* \author
* Nicolas Tsiftes <nvt@sics.se>
* \addtogroup mem
* @{
*/
/**
* \defgroup heapmem Dynamic heap memory allocator
*
* The heapmem module is a dynamic heap memory allocator similar to
* malloc() in standard C. The heap memory is managed in a block of
* static memory, whose size is determined at compile-time by setting
* HEAPMEM_CONF_ARENA_SIZE parameter. By default, the heap memory is
* only 1 bytes, which entails that this parameter must be set
* explicitly in order to be possible to use this module.
*
* Each allocated memory object is referred to as a "chunk". The
* allocator manages free chunks in a double-linked list. While this
* adds some memory overhead compared to a single-linked list, it
* improves the performance of list management.
*
* Internally, allocated chunks can be retrieved using the pointer to
* the allocated memory returned by heapmem_alloc() and
* heapmem_realloc(), because the chunk structure immediately precedes
* the memory of the chunk.
*
* \note This module does not contain a corresponding function to the
* standard C function calloc().
*
* \note Dynamic memory should be used carefully on
* memory-constrained, embedded systems, because fragmentation
* may be induced through various allocation/deallocation
* patterns, and no guarantees are given regarding the
* availability of memory.
*
* @{
*/
/**
* \file
* Header file for the dynamic heap memory allocator.
* \author
* Nicolas Tsiftes <nvt@acm.org>
*/
#ifndef HEAPMEM_H
#define HEAPMEM_H
@ -49,21 +85,83 @@ typedef struct heapmem_stats {
} heapmem_stats_t;
#if HEAPMEM_DEBUG
#define heapmem_alloc(size) heapmem_alloc_debug((size), __FILE__, __LINE__)
#define heapmem_realloc(ptr, size) heapmem_realloc_debug((ptr), (size), __FILE__, __LINE__)
#define heapmem_free(ptr) heapmem_free_debug((ptr), __FILE__, __LINE__)
void *heapmem_alloc_debug(size_t, const char *file, const unsigned line);
void *heapmem_realloc_debug(void *, size_t, const char *file, const unsigned line);
void heapmem_free_debug(void *, const char *file, const unsigned line);
void *heapmem_alloc_debug(size_t size,
const char *file, const unsigned line);
void *heapmem_realloc_debug(void *ptr, size_t size,
const char *file, const unsigned line);
void heapmem_free_debug(void *ptr,
const char *file, const unsigned line);
#else
void *heapmem_alloc(size_t);
void *heapmem_realloc(void *, size_t);
void heapmem_free(void *);
/**
* \brief Allocate a chunk of memory in the heap.
* \param size The number of bytes to allocate.
* \return A pointer to the allocated memory chunk,
* or NULL if the allocation failed.
*
* \sa heapmem_realloc
* \sa heapmem_free
*/
void *heapmem_alloc(size_t size);
/**
* \brief Reallocate a chunk of memory in the heap.
* \param ptr A pointer to a chunk that has been allocated using
* heapmem_alloc() or heapmem_realloc().
* \param size The number of bytes to allocate.
* \return A pointer to the allocated memory chunk,
* or NULL if the allocation failed.
*
* \note If ptr is NULL, this function behaves the same as heapmem_alloc.
* \note If ptr is not NULL and size is zero, the function deallocates
* the chunk and returns NULL.
*
* \sa heapmem_alloc
* \sa heapmem_free
*/
void *heapmem_realloc(void *ptr, size_t size);
/**
* \brief Deallocate a chunk of memory.
* \param ptr A pointer to a chunk that has been allocated using
* heapmem_alloc() or heapmem_realloc().
*
* \note If ptr is NULL, this function will return immediately without
* without performing any action.
*
* \sa heapmem_alloc
* \sa heapmem_realloc
*/
void heapmem_free(void *ptr);
#endif /* HEAMMEM_DEBUG */
void heapmem_stats(heapmem_stats_t *);
/**
* \brief Obtain internal heapmem statistics regarding the
* allocated chunks.
* \param stats A pointer to an object of type heapmem_stats_t, which
* will be filled when calling this function.
*
* This function makes it possible to gain visibility into the internal
* structure of the heap. One can thus obtain information regarding
* the amount of memory allocated, overhead used for memory management,
* and the number of chunks allocated. By using this information, developers
* can tune their software to use the heapmem allocator more efficiently.
*
*/
void heapmem_stats(heapmem_stats_t *stats);
#endif /* !HEAPMEM_H */
/** @} */
/** @} */