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
  65 /* needed for uintptr_t and attributes, exception, dont use BLI anywhere else in MEM_* */
  66 #include "../../source/blender/blenlib/BLI_sys_types.h"
  67 #include "../../source/blender/blenlib/BLI_compiler_attrs.h"
  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         extern size_t (*MEM_allocN_len)(const void *vmemh) ATTR_WARN_UNUSED_RESULT;
  77
  78         /**
  79          * Release memory previously allocatred by this module.
  80          */
  81         extern void (*MEM_freeN)(void *vmemh);
  82
  83 #if 0  /* UNUSED */
  84         /**
  85          * Return zero if memory is not in allocated list
  86          */
  87         extern short (*MEM_testN)(void *vmemh);
  88 #endif
  89
  90         /**
  91          * Duplicates a block of memory, and returns a pointer to the
  92          * newly allocated block.  */
  93         extern void *(*MEM_dupallocN)(const void *vmemh) /* ATTR_MALLOC */ ATTR_WARN_UNUSED_RESULT;
  94
  95         /**
  96          * Reallocates a block of memory, and returns pointer to the newly
  97          * allocated block, the old one is freed. this is not as optimized
  98          * as a system realloc but just makes a new allocation and copies
  99          * over from existing memory. */
 100         extern void *(*MEM_reallocN_id)(void *vmemh, size_t len, const char *str) /* ATTR_MALLOC */ ATTR_WARN_UNUSED_RESULT ATTR_ALLOC_SIZE(2);
 101
 102         /**
 103          * A variant of realloc which zeros new bytes
 104          */
 105         extern void *(*MEM_recallocN_id)(void *vmemh, size_t len, const char *str) /* ATTR_MALLOC */ ATTR_WARN_UNUSED_RESULT ATTR_ALLOC_SIZE(2);
 106
 107 #define MEM_reallocN(vmemh, len) MEM_reallocN_id(vmemh, len, __func__)
 108 #define MEM_recallocN(vmemh, len) MEM_recallocN_id(vmemh, len, __func__)
 109
 110         /**
 111          * Allocate a block of memory of size len, with tag name str. The
 112          * memory is cleared. The name must be static, because only a
 113          * pointer to it is stored ! */
 114         extern void *(*MEM_callocN)(size_t len, const char *str) /* ATTR_MALLOC */ ATTR_WARN_UNUSED_RESULT ATTR_ALLOC_SIZE(1) ATTR_NONNULL(2);
 115
 116         /**
 117          * Allocate a block of memory of size len, with tag name str. The
 118          * name must be a static, because only a pointer to it is stored !
 119          * */
 120         extern void *(*MEM_mallocN)(size_t len, const char *str) /* ATTR_MALLOC */ ATTR_WARN_UNUSED_RESULT ATTR_ALLOC_SIZE(1) ATTR_NONNULL(2);
 121
 122         /**
 123          * Same as callocN, clears memory and uses mmap (disk cached) if supported.
 124          * Can be free'd with MEM_freeN as usual.
 125          * */
 126         extern void *(*MEM_mapallocN)(size_t len, const char *str) /* ATTR_MALLOC */ ATTR_WARN_UNUSED_RESULT ATTR_ALLOC_SIZE(1) ATTR_NONNULL(2);
 127
 128         /** Print a list of the names and sizes of all allocated memory
 129          * blocks. as a python dict for easy investigation */
 130         extern void (*MEM_printmemlist_pydict)(void);
 131
 132         /** Print a list of the names and sizes of all allocated memory
 133          * blocks. */
 134         extern void (*MEM_printmemlist)(void);
 135
 136         /** calls the function on all allocated memory blocks. */
 137         extern void (*MEM_callbackmemlist)(void (*func)(void *));
 138
 139         /** Print statistics about memory usage */
 140         extern void (*MEM_printmemlist_stats)(void);
 141
 142         /** Set the callback function for error output. */
 143         extern void (*MEM_set_error_callback)(void (*func)(const char *));
 144
 145         /**
 146          * Are the start/end block markers still correct ?
 147          *
 148          * @retval 0 for correct memory, 1 for corrupted memory. */
 149         extern bool (*MEM_check_memory_integrity)(void);
 150
 151         /** Set thread locking functions for safe memory allocation from multiple
 152          * threads, pass NULL pointers to disable thread locking again. */
 153         extern void (*MEM_set_lock_callback)(void (*lock)(void), void (*unlock)(void));
 154
 155         /** Attempt to enforce OSX (or other OS's) to have malloc and stack nonzero */
 156         extern void (*MEM_set_memory_debug)(void);
 157
 158         /**
 159          * Memory usage stats
 160          * - MEM_get_memory_in_use is all memory
 161          * - MEM_get_mapped_memory_in_use is a subset of all memory */
 162         extern uintptr_t (*MEM_get_memory_in_use)(void);
 163         /** Get mapped memory usage. */
 164         extern uintptr_t (*MEM_get_mapped_memory_in_use)(void);
 165         /** Get amount of memory blocks in use. */
 166         extern unsigned int (*MEM_get_memory_blocks_in_use)(void);
 167
 168         /** Reset the peak memory statistic to zero. */
 169         extern void (*MEM_reset_peak_memory)(void);
 170
 171         /** Get the peak memory usage in bytes, including mmap allocations. */
 172         extern size_t (*MEM_get_peak_memory)(void) ATTR_WARN_UNUSED_RESULT;
 173
 174 #define MEM_SAFE_FREE(v) if (v) { MEM_freeN(v); v = NULL; } (void)0
 175
 176 #ifndef NDEBUG
 177 extern const char *(*MEM_name_ptr)(void *vmemh);
 178 #endif
 179
 180 /* Switch allocator to slower but fully guarded mode. */
 181 void MEM_use_guarded_allocator(void);
 182
 183 #ifdef __cplusplus
 184 /* alloc funcs for C++ only */
 185 #define MEM_CXX_CLASS_ALLOC_FUNCS(_id)                                        \
 186 public:                                                                       \
 187         void *operator new(size_t num_bytes) {                                    \
 188                 return MEM_mallocN(num_bytes, _id);                                   \
 189         }                                                                         \
 190         void operator delete(void *mem) {                                         \
 191                 if (mem)                                                              \
 192                         MEM_freeN(mem);                                                   \
 193         }                                                                         \
 194         void *operator new[](size_t num_bytes) {                                  \
 195                 return MEM_mallocN(num_bytes, _id "[]");                              \
 196         }                                                                         \
 197         void operator delete[](void *mem) {                                       \
 198                 if (mem)                                                              \
 199                         MEM_freeN(mem);                                                   \
 200         }                                                                         \
 201
 202 #if defined __GNUC__ || defined __sun
 203 #  define OBJECT_GUARDED_NEW(type, args ...) \
 204         new(MEM_mallocN(sizeof(type), __func__)) type(args)
 205 #else
 206 #  define OBJECT_GUARDED_NEW(type, ...) \
 207         new(MEM_mallocN(sizeof(type), __FUNCTION__)) type(__VA_ARGS__)
 208 #endif
 209 #define OBJECT_GUARDED_DELETE(what, type) \
 210         { if(what) { \
 211                         ((type*)(what))->~type(); \
 212                         MEM_freeN(what); \
 213         } } (void)0
 214 #endif  /* __cplusplus */
 215
 216 #ifdef __cplusplus
 217 }
 218 #endif  /* __cplusplus */
 219
 220 #endif  /* __MEM_GUARDEDALLOC_H__ */