Contiki-NG
heapmem.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2005, Nicolas Tsiftes
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  * notice, this list of conditions and the following disclaimer in the
12  * documentation and/or other materials provided with the distribution.
13  * 3. Neither the name of the author nor the names of the contributors
14  * may be used to endorse or promote products derived from this software
15  * without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
18  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20  * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
21  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27  * SUCH DAMAGE.
28  */
29 
30 /**
31  * \addtogroup mem
32  * @{
33  */
34 
35 /**
36  * \defgroup heapmem heapmem: Dynamic heap memory allocator
37  *
38  * The heapmem module is a dynamic heap memory allocator similar to
39  * malloc() in standard C. The heap memory is managed in a block of
40  * static memory, whose size is determined at compile-time by setting
41  * HEAPMEM_CONF_ARENA_SIZE parameter. By default, the heap memory is
42  * only 1 bytes, which entails that this parameter must be set
43  * explicitly in order to be possible to use this module.
44  *
45  * Each allocated memory object is referred to as a "chunk". The
46  * allocator manages free chunks in a double-linked list. While this
47  * adds some memory overhead compared to a single-linked list, it
48  * improves the performance of list management.
49  *
50  * Internally, allocated chunks can be retrieved using the pointer to
51  * the allocated memory returned by heapmem_alloc() and
52  * heapmem_realloc(), because the chunk structure immediately precedes
53  * the memory of the chunk.
54  *
55  * \note This module does not contain a corresponding function to the
56  * standard C function calloc().
57  *
58  * \note Dynamic memory should be used carefully on
59  * memory-constrained, embedded systems, because fragmentation
60  * may be induced through various allocation/deallocation
61  * patterns, and no guarantees are given regarding the
62  * availability of memory.
63  *
64  * @{
65  */
66 
67 /**
68  * \file
69  * Header file for the dynamic heap memory allocator.
70  * \author
71  * Nicolas Tsiftes <nvt@acm.org>
72  */
73 
74 #ifndef HEAPMEM_H
75 #define HEAPMEM_H
76 
77 #include <stdlib.h>
78 
79 typedef struct heapmem_stats {
80  size_t allocated;
81  size_t overhead;
82  size_t available;
83  size_t footprint;
84  size_t chunks;
85 } heapmem_stats_t;
86 
87 #if HEAPMEM_DEBUG
88 
89 #define heapmem_alloc(size) heapmem_alloc_debug((size), __FILE__, __LINE__)
90 #define heapmem_realloc(ptr, size) heapmem_realloc_debug((ptr), (size), __FILE__, __LINE__)
91 #define heapmem_free(ptr) heapmem_free_debug((ptr), __FILE__, __LINE__)
92 
93 void *heapmem_alloc_debug(size_t size,
94  const char *file, const unsigned line);
95 void *heapmem_realloc_debug(void *ptr, size_t size,
96  const char *file, const unsigned line);
97 void heapmem_free_debug(void *ptr,
98  const char *file, const unsigned line);
99 
100 #else
101 
102 /**
103  * \brief Allocate a chunk of memory in the heap.
104  * \param size The number of bytes to allocate.
105  * \return A pointer to the allocated memory chunk,
106  * or NULL if the allocation failed.
107  *
108  * \sa heapmem_realloc
109  * \sa heapmem_free
110  */
111 
112 void *heapmem_alloc(size_t size);
113 
114 /**
115  * \brief Reallocate a chunk of memory in the heap.
116  * \param ptr A pointer to a chunk that has been allocated using
117  * heapmem_alloc() or heapmem_realloc().
118  * \param size The number of bytes to allocate.
119  * \return A pointer to the allocated memory chunk,
120  * or NULL if the allocation failed.
121  *
122  * \note If ptr is NULL, this function behaves the same as heapmem_alloc.
123  * \note If ptr is not NULL and size is zero, the function deallocates
124  * the chunk and returns NULL.
125  *
126  * \sa heapmem_alloc
127  * \sa heapmem_free
128  */
129 
130 void *heapmem_realloc(void *ptr, size_t size);
131 
132 /**
133  * \brief Deallocate a chunk of memory.
134  * \param ptr A pointer to a chunk that has been allocated using
135  * heapmem_alloc() or heapmem_realloc().
136  *
137  * \note If ptr is NULL, this function will return immediately without
138  * without performing any action.
139  *
140  * \sa heapmem_alloc
141  * \sa heapmem_realloc
142  */
143 
144 void heapmem_free(void *ptr);
145 
146 #endif /* HEAMMEM_DEBUG */
147 
148 /**
149  * \brief Obtain internal heapmem statistics regarding the
150  * allocated chunks.
151  * \param stats A pointer to an object of type heapmem_stats_t, which
152  * will be filled when calling this function.
153  *
154  * This function makes it possible to gain visibility into the internal
155  * structure of the heap. One can thus obtain information regarding
156  * the amount of memory allocated, overhead used for memory management,
157  * and the number of chunks allocated. By using this information, developers
158  * can tune their software to use the heapmem allocator more efficiently.
159  *
160  */
161 
162 void heapmem_stats(heapmem_stats_t *stats);
163 
164 #endif /* !HEAPMEM_H */
165 
166 /** @} */
167 /** @} */
void heapmem_free(void *ptr)
Deallocate a chunk of memory.
Definition: heapmem.c:373
void * heapmem_alloc(size_t size)
Allocate a chunk of memory in the heap.
Definition: heapmem.c:329
void heapmem_stats(heapmem_stats_t *stats)
Obtain internal heapmem statistics regarding the allocated chunks.
Definition: heapmem.c:490
void * heapmem_realloc(void *ptr, size_t size)
Reallocate a chunk of memory in the heap.
Definition: heapmem.c:410