intern/guardedalloc/MEM_guardedalloc.h

   1 /*
   2  * This program is free software; you can redistribute it and/or
   3  * modify it under the terms of the GNU General Public License
   4  * as published by the Free Software Foundation; either version 2
   5  * of the License, or (at your option) any later version.
   6  *
   7  * This program is distributed in the hope that it will be useful,
   8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
   9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  10  * GNU General Public License for more details.
  11  *
  12  * You should have received a copy of the GNU General Public License
  13  * along with this program; if not, write to the Free Software Foundation,
  14  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  15  *
  16  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
  17  * All rights reserved.
  18  */
  19
  20 /** \file
  21  * \ingroup MEM
  22  *
  23  * \brief Read \ref MEMPage
  24  *
  25  * \page MEMPage Guarded memory(de)allocation
  26  *
  27  * \section aboutmem c-style guarded memory allocation
  28  *
  29  * \subsection memabout About the MEM module
  30  *
  31  * MEM provides guarded malloc/calloc calls. All memory is enclosed by
  32  * pads, to detect out-of-bound writes. All blocks are placed in a
  33  * linked list, so they remain reachable at all times. There is no
  34  * back-up in case the linked-list related data is lost.
  35  *
  36  * \subsection memissues Known issues with MEM
  37  *
  38  * There are currently no known issues with MEM. Note that there is a
  39  * second intern/ module with MEM_ prefix, for use in c++.
  40  *
  41  * \subsection memdependencies Dependencies
  42  * - stdlib
  43  * - stdio
  44  *
  45  * \subsection memdocs API Documentation
  46  * See \ref MEM_guardedalloc.h
  47  */
  48
  49 #ifndef __MEM_GUARDEDALLOC_H__
  50 #define __MEM_GUARDEDALLOC_H__
  51
  52 #include <stdio.h> /* needed for FILE* */
  53
  54 /* needed for uintptr_t and attributes, exception, dont use BLI anywhere else in MEM_* */
  55 #include "../../source/blender/blenlib/BLI_compiler_attrs.h"
  56 #include "../../source/blender/blenlib/BLI_sys_types.h"
  57
  58 #ifdef __cplusplus
  59 extern "C" {
  60 #endif
  61
  62 /** Returns the length of the allocated memory segment pointed at
  63  * by vmemh. If the pointer was not previously allocated by this
  64  * module, the result is undefined.*/
  65 extern size_t (*MEM_allocN_len)(const void *vmemh) ATTR_WARN_UNUSED_RESULT;
  66
  67 /**
  68  * Release memory previously allocated by this module.
  69  */
  70 extern void (*MEM_freeN)(void *vmemh);
  71
  72 #if 0 /* UNUSED */
  73 /**
  74    * Return zero if memory is not in allocated list
  75    */
  76 extern short (*MEM_testN)(void *vmemh);
  77 #endif
  78
  79 /**
  80  * Duplicates a block of memory, and returns a pointer to the
  81  * newly allocated block.  */
  82 extern void *(*MEM_dupallocN)(const void *vmemh) /* ATTR_MALLOC */ ATTR_WARN_UNUSED_RESULT;
  83
  84 /**
  85  * Reallocates a block of memory, and returns pointer to the newly
  86  * allocated block, the old one is freed. this is not as optimized
  87  * as a system realloc but just makes a new allocation and copies
  88  * over from existing memory. */
  89 extern void *(*MEM_reallocN_id)(void *vmemh,
  90                                 size_t len,
  91                                 const char *str) /* ATTR_MALLOC */ ATTR_WARN_UNUSED_RESULT
  92     ATTR_ALLOC_SIZE(2);
  93
  94 /**
  95  * A variant of realloc which zeros new bytes
  96  */
  97 extern void *(*MEM_recallocN_id)(void *vmemh,
  98                                  size_t len,
  99                                  const char *str) /* ATTR_MALLOC */ ATTR_WARN_UNUSED_RESULT
 100     ATTR_ALLOC_SIZE(2);
 101
 102 #define MEM_reallocN(vmemh, len) MEM_reallocN_id(vmemh, len, __func__)
 103 #define MEM_recallocN(vmemh, len) MEM_recallocN_id(vmemh, len, __func__)
 104
 105 /**
 106  * Allocate a block of memory of size len, with tag name str. The
 107  * memory is cleared. The name must be static, because only a
 108  * pointer to it is stored ! */
 109 extern void *(*MEM_callocN)(size_t len, const char *str) /* ATTR_MALLOC */ ATTR_WARN_UNUSED_RESULT
 110     ATTR_ALLOC_SIZE(1) ATTR_NONNULL(2);
 111
 112 /**
 113  * Allocate a block of memory of size (len * size), with tag name
 114  * str, aborting in case of integer overflows to prevent vulnerabilities.
 115  * The memory is cleared. The name must be static, because only a
 116  * pointer to it is stored ! */
 117 extern void *(*MEM_calloc_arrayN)(size_t len,
 118                                   size_t size,
 119                                   const char *str) /* ATTR_MALLOC */ ATTR_WARN_UNUSED_RESULT
 120     ATTR_ALLOC_SIZE(1, 2) ATTR_NONNULL(3);
 121
 122 /**
 123  * Allocate a block of memory of size len, with tag name str. The
 124  * name must be a static, because only a pointer to it is stored !
 125  * */
 126 extern void *(*MEM_mallocN)(size_t len, const char *str) /* ATTR_MALLOC */ ATTR_WARN_UNUSED_RESULT
 127     ATTR_ALLOC_SIZE(1) ATTR_NONNULL(2);
 128
 129 /**
 130  * Allocate a block of memory of size (len * size), with tag name str,
 131  * aborting in case of integer overflow to prevent vulnerabilities. The
 132  * name must be a static, because only a pointer to it is stored !
 133  * */
 134 extern void *(*MEM_malloc_arrayN)(size_t len,
 135                                   size_t size,
 136                                   const char *str) /* ATTR_MALLOC */ ATTR_WARN_UNUSED_RESULT
 137     ATTR_ALLOC_SIZE(1, 2) ATTR_NONNULL(3);
 138
 139 /**
 140  * Allocate an aligned block of memory of size len, with tag name str. The
 141  * name must be a static, because only a pointer to it is stored !
 142  * */
 143 extern void *(*MEM_mallocN_aligned)(size_t len,
 144                                     size_t alignment,
 145                                     const char *str) /* ATTR_MALLOC */ ATTR_WARN_UNUSED_RESULT
 146     ATTR_ALLOC_SIZE(1) ATTR_NONNULL(3);
 147
 148 /**
 149  * Same as callocN, clears memory and uses mmap (disk cached) if supported.
 150  * Can be free'd with MEM_freeN as usual.
 151  * */
 152 extern void *(*MEM_mapallocN)(size_t len,
 153                               const char *str) /* ATTR_MALLOC */ ATTR_WARN_UNUSED_RESULT
 154     ATTR_ALLOC_SIZE(1) ATTR_NONNULL(2);
 155
 156 /** Print a list of the names and sizes of all allocated memory
 157  * blocks. as a python dict for easy investigation */
 158 extern void (*MEM_printmemlist_pydict)(void);
 159
 160 /** Print a list of the names and sizes of all allocated memory
 161  * blocks. */
 162 extern void (*MEM_printmemlist)(void);
 163
 164 /** calls the function on all allocated memory blocks. */
 165 extern void (*MEM_callbackmemlist)(void (*func)(void *));
 166
 167 /** Print statistics about memory usage */
 168 extern void (*MEM_printmemlist_stats)(void);
 169
 170 /** Set the callback function for error output. */
 171 extern void (*MEM_set_error_callback)(void (*func)(const char *));
 172
 173 /**
 174  * Are the start/end block markers still correct ?
 175  *
 176  * @retval true for correct memory, false for corrupted memory. */
 177 extern bool (*MEM_consistency_check)(void);
 178
 179 /** Set thread locking functions for safe memory allocation from multiple
 180  * threads, pass NULL pointers to disable thread locking again. */
 181 extern void (*MEM_set_lock_callback)(void (*lock)(void), void (*unlock)(void));
 182
 183 /** Attempt to enforce OSX (or other OS's) to have malloc and stack nonzero */
 184 extern void (*MEM_set_memory_debug)(void);
 185
 186 /**
 187  * Memory usage stats
 188  * - MEM_get_memory_in_use is all memory
 189  * - MEM_get_mapped_memory_in_use is a subset of all memory */
 190 extern size_t (*MEM_get_memory_in_use)(void);
 191 /** Get mapped memory usage. */
 192 extern size_t (*MEM_get_mapped_memory_in_use)(void);
 193 /** Get amount of memory blocks in use. */
 194 extern unsigned int (*MEM_get_memory_blocks_in_use)(void);
 195
 196 /** Reset the peak memory statistic to zero. */
 197 extern void (*MEM_reset_peak_memory)(void);
 198
 199 /** Get the peak memory usage in bytes, including mmap allocations. */
 200 extern size_t (*MEM_get_peak_memory)(void) ATTR_WARN_UNUSED_RESULT;
 201
 202 #ifdef __GNUC__
 203 #  define MEM_SAFE_FREE(v) \
 204     do { \
 205       typeof(&(v)) _v = &(v); \
 206       if (*_v) { \
 207         MEM_freeN(*_v); \
 208         *_v = NULL; \
 209       } \
 210     } while (0)
 211 #else
 212 #  define MEM_SAFE_FREE(v) \
 213     do { \
 214       void **_v = (void **)&(v); \
 215       if (*_v) { \
 216         MEM_freeN(*_v); \
 217         *_v = NULL; \
 218       } \
 219     } while (0)
 220 #endif
 221
 222 /* overhead for lockfree allocator (use to avoid slop-space) */
 223 #define MEM_SIZE_OVERHEAD sizeof(size_t)
 224 #define MEM_SIZE_OPTIMAL(size) ((size)-MEM_SIZE_OVERHEAD)
 225
 226 #ifndef NDEBUG
 227 extern const char *(*MEM_name_ptr)(void *vmemh);
 228 #endif
 229
 230 /* Switch allocator to slower but fully guarded mode. */
 231 void MEM_use_guarded_allocator(void);
 232
 233 #ifdef __cplusplus
 234 }
 235 #endif /* __cplusplus */
 236
 237 #ifdef __cplusplus
 238 /* alloc funcs for C++ only */
 239 #  define MEM_CXX_CLASS_ALLOC_FUNCS(_id) \
 240    public: \
 241     void *operator new(size_t num_bytes) \
 242     { \
 243       return MEM_mallocN(num_bytes, _id); \
 244     } \
 245     void operator delete(void *mem) \
 246     { \
 247       if (mem) \
 248         MEM_freeN(mem); \
 249     } \
 250     void *operator new[](size_t num_bytes) \
 251     { \
 252       return MEM_mallocN(num_bytes, _id "[]"); \
 253     } \
 254     void operator delete[](void *mem) \
 255     { \
 256       if (mem) \
 257         MEM_freeN(mem); \
 258     }
 259
 260 /* Needed when type includes a namespace, then the namespace should not be
 261  * specified after ~, so using a macro fails. */
 262 template<class T> inline void OBJECT_GUARDED_DESTRUCTOR(T *what)
 263 {
 264   what->~T();
 265 }
 266
 267 #  if defined __GNUC__
 268 #    define OBJECT_GUARDED_NEW(type, args...) new (MEM_mallocN(sizeof(type), __func__)) type(args)
 269 #  else
 270 #    define OBJECT_GUARDED_NEW(type, ...) \
 271       new (MEM_mallocN(sizeof(type), __FUNCTION__)) type(__VA_ARGS__)
 272 #  endif
 273 #  define OBJECT_GUARDED_DELETE(what, type) \
 274     { \
 275       if (what) { \
 276         OBJECT_GUARDED_DESTRUCTOR((type *)what); \
 277         MEM_freeN(what); \
 278       } \
 279     } \
 280     (void)0
 281 #  define OBJECT_GUARDED_SAFE_DELETE(what, type) \
 282     { \
 283       if (what) { \
 284         OBJECT_GUARDED_DESTRUCTOR((type *)what); \
 285         MEM_freeN(what); \
 286         what = NULL; \
 287       } \
 288     } \
 289     (void)0
 290 #endif /* __cplusplus */
 291
 292 #endif /* __MEM_GUARDEDALLOC_H__ */