intern/guardedalloc/MEM_guardedalloc.h

   1 /*
   2  * ***** BEGIN GPL LICENSE BLOCK *****
   3  *
   4  * This program is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU General Public License
   6  * as published by the Free Software Foundation; either version 2
   7  * of the License, or (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with this program; if not, write to the Free Software Foundation,
  16  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  17  *
  18  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
  19  * All rights reserved.
  20  *
  21  * The Original Code is: all of this file.
  22  *
  23  * Contributor(s): Brecht Van Lommel
  24  *                 Campbell Barton
  25  *
  26  * ***** END GPL LICENSE BLOCK *****
  27  */
  28
  29 /**
  30  * \file MEM_guardedalloc.h
  31  * \ingroup MEM
  32  *
  33  * \author Copyright (C) 2001 NaN Technologies B.V.
  34  * \brief Read \ref MEMPage
  35  *
  36  * \page MEMPage Guarded memory(de)allocation
  37  *
  38  * \section aboutmem c-style guarded memory allocation
  39  *
  40  * \subsection memabout About the MEM module
  41  *
  42  * MEM provides guarded malloc/calloc calls. All memory is enclosed by
  43  * pads, to detect out-of-bound writes. All blocks are placed in a
  44  * linked list, so they remain reachable at all times. There is no
  45  * back-up in case the linked-list related data is lost.
  46  *
  47  * \subsection memissues Known issues with MEM
  48  *
  49  * There are currently no known issues with MEM. Note that there is a
  50  * second intern/ module with MEM_ prefix, for use in c++.
  51  *
  52  * \subsection memdependencies Dependencies
  53  * - stdlib
  54  * - stdio
  55  *
  56  * \subsection memdocs API Documentation
  57  * See \ref MEM_guardedalloc.h
  58  */
  59
  60 #ifndef __MEM_GUARDEDALLOC_H__
  61 #define __MEM_GUARDEDALLOC_H__
  62
  63 #include <stdio.h>          /* needed for FILE* */
  64 #include "MEM_sys_types.h"  /* needed for uintptr_t */
  65
  66 /* some GNU attributes are only available from GCC 4.3 */
  67 #define MEM_GNU_ATTRIBUTES (defined(__GNUC__) && ((__GNUC__ * 100 + __GNUC_MINOR__) >= 403))
  68
  69 #ifdef __cplusplus
  70 extern "C" {
  71 #endif
  72
  73         /** Returns the length of the allocated memory segment pointed at
  74          * by vmemh. If the pointer was not previously allocated by this
  75          * module, the result is undefined.*/
  76         size_t MEM_allocN_len(const void *vmemh)
  77 #if MEM_GNU_ATTRIBUTES
  78         __attribute__((warn_unused_result))
  79 #endif
  80         ;
  81
  82         /**
  83          * Release memory previously allocatred by this module.
  84          */
  85         short MEM_freeN(void *vmemh);
  86
  87         /**
  88          * Return zero if memory is not in allocated list
  89          */
  90         short MEM_testN(void *vmemh);
  91
  92         /**
  93          * Duplicates a block of memory, and returns a pointer to the
  94          * newly allocated block.  */
  95         void *MEM_dupallocN(const void *vmemh)
  96 #if MEM_GNU_ATTRIBUTES
  97         __attribute__((warn_unused_result))
  98 #endif
  99         ;
 100
 101         /**
 102          * Reallocates a block of memory, and returns pointer to the newly
 103          * allocated block, the old one is freed. this is not as optimized
 104          * as a system realloc but just makes a new allocation and copies
 105          * over from existing memory. */
 106         void *MEM_reallocN(void *vmemh, size_t len)
 107 #if MEM_GNU_ATTRIBUTES
 108         __attribute__((warn_unused_result))
 109         __attribute__((alloc_size(2)))
 110 #endif
 111         ;
 112
 113         /**
 114          * A variant of realloc which zeros new bytes
 115          */
 116         void *MEM_recallocN(void *vmemh, size_t len)
 117 #if MEM_GNU_ATTRIBUTES
 118         __attribute__((warn_unused_result))
 119         __attribute__((alloc_size(2)))
 120 #endif
 121         ;
 122
 123         /**
 124          * Allocate a block of memory of size len, with tag name str. The
 125          * memory is cleared. The name must be static, because only a
 126          * pointer to it is stored ! */
 127         void *MEM_callocN(size_t len, const char *str)
 128 #if MEM_GNU_ATTRIBUTES
 129         __attribute__((warn_unused_result))
 130         __attribute__((nonnull(2)))
 131         __attribute__((alloc_size(1)))
 132 #endif
 133         ;
 134
 135         /**
 136          * Allocate a block of memory of size len, with tag name str. The
 137          * name must be a static, because only a pointer to it is stored !
 138          * */
 139         void *MEM_mallocN(size_t len, const char *str)
 140 #if MEM_GNU_ATTRIBUTES
 141         __attribute__((warn_unused_result))
 142         __attribute__((nonnull(2)))
 143         __attribute__((alloc_size(1)))
 144 #endif
 145         ;
 146
 147         /**
 148          * Same as callocN, clears memory and uses mmap (disk cached) if supported.
 149          * Can be free'd with MEM_freeN as usual.
 150          * */
 151         void *MEM_mapallocN(size_t len, const char *str)
 152 #if MEM_GNU_ATTRIBUTES
 153         __attribute__((warn_unused_result))
 154         __attribute__((nonnull(2)))
 155         __attribute__((alloc_size(1)))
 156 #endif
 157         ;
 158
 159         /** Print a list of the names and sizes of all allocated memory
 160          * blocks. as a python dict for easy investigation */
 161         void MEM_printmemlist_pydict(void);
 162
 163         /** Print a list of the names and sizes of all allocated memory
 164          * blocks. */
 165         void MEM_printmemlist(void);
 166
 167         /** calls the function on all allocated memory blocks. */
 168         void MEM_callbackmemlist(void (*func)(void*));
 169
 170         /** Print statistics about memory usage */
 171         void MEM_printmemlist_stats(void);
 172
 173         /** Set the callback function for error output. */
 174         void MEM_set_error_callback(void (*func)(const char *));
 175
 176         /**
 177          * Are the start/end block markers still correct ?
 178          *
 179          * @retval 0 for correct memory, 1 for corrupted memory. */
 180         int MEM_check_memory_integrity(void);
 181
 182         /** Set thread locking functions for safe memory allocation from multiple
 183          * threads, pass NULL pointers to disable thread locking again. */
 184         void MEM_set_lock_callback(void (*lock)(void), void (*unlock)(void));
 185
 186         /** Attempt to enforce OSX (or other OS's) to have malloc and stack nonzero */
 187         void MEM_set_memory_debug(void);
 188
 189         /**
 190          * Memory usage stats
 191          * - MEM_get_memory_in_use is all memory
 192          * - MEM_get_mapped_memory_in_use is a subset of all memory */
 193         uintptr_t MEM_get_memory_in_use(void);
 194         /** Get mapped memory usage. */
 195         uintptr_t MEM_get_mapped_memory_in_use(void);
 196         /** Get amount of memory blocks in use. */
 197         int MEM_get_memory_blocks_in_use(void);
 198
 199         /** Reset the peak memory statistic to zero. */
 200         void MEM_reset_peak_memory(void);
 201
 202         /** Get the peak memory usage in bytes, including mmap allocations. */
 203         uintptr_t MEM_get_peak_memory(void)
 204 #if MEM_GNU_ATTRIBUTES
 205         __attribute__((warn_unused_result))
 206 #endif
 207         ;
 208
 209 #ifndef NDEBUG
 210 const char *MEM_name_ptr(void *vmemh);
 211 #endif
 212
 213 #ifdef __cplusplus
 214 /* alloc funcs for C++ only */
 215 #define MEM_CXX_CLASS_ALLOC_FUNCS(_id)                                        \
 216 public:                                                                       \
 217         void *operator new(size_t num_bytes) {                                    \
 218                 return MEM_mallocN(num_bytes, _id);                                   \
 219         }                                                                         \
 220         void operator delete(void *mem) {                                         \
 221                 if (mem)                                                              \
 222                         MEM_freeN(mem);                                                   \
 223         }                                                                         \
 224         void *operator new[](size_t num_bytes) {                                  \
 225                 return MEM_mallocN(num_bytes, _id "[]");                              \
 226         }                                                                         \
 227         void operator delete[](void *mem) {                                       \
 228                 if (mem)                                                              \
 229                         MEM_freeN(mem);                                                   \
 230         }                                                                         \
 231
 232 #endif  /* __cplusplus */
 233
 234 #ifdef __cplusplus
 235 }
 236 #endif  /* __cplusplus */
 237
 238 #endif  /* __MEM_GUARDEDALLOC_H__ */