Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/thirdparty/extract/src/memento.h @ 2:b50eed0cc0ef upstream

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. The directory name has changed: no version number in the expanded directory now.
author Franz Glasner <fzglas.hg@dom66.de>
date Mon, 15 Sep 2025 11:43:07 +0200
parents
children
comparison
equal deleted inserted replaced
1:1d09e1dec1d9 2:b50eed0cc0ef
1 /* Copyright (C) 2009-2018 Artifex Software, Inc.
2 All Rights Reserved.
3
4 This software is provided AS-IS with no warranty, either express or
5 implied.
6
7 This software is distributed under license and may not be copied,
8 modified or distributed except as expressly authorized under the terms
9 of the license contained in the file COPYING in this distribution.
10
11 Refer to licensing information at http://www.artifex.com or contact
12 Artifex Software, Inc., 39 Mesa Street, Suite 108A, San Francisco,
13 CA 94129, USA, for further information.
14 */
15
16 /* Memento: A library to aid debugging of memory leaks/heap corruption.
17 *
18 * Usage (with C):
19 * First, build your project with MEMENTO defined, and include this
20 * header file wherever you use malloc, realloc or free.
21 * This header file will use macros to point malloc, realloc and free to
22 * point to Memento_malloc, Memento_realloc, Memento_free.
23 *
24 * Run your program, and all mallocs/frees/reallocs should be redirected
25 * through here. When the program exits, you will get a list of all the
26 * leaked blocks, together with some helpful statistics. You can get the
27 * same list of allocated blocks at any point during program execution by
28 * calling Memento_listBlocks();
29 *
30 * Every call to malloc/free/realloc counts as an 'allocation event'.
31 * On each event Memento increments a counter. Every block is tagged with
32 * the current counter on allocation. Every so often during program
33 * execution, the heap is checked for consistency. By default this happens
34 * after 1024 events, then after 2048 events, then after 4096 events, etc.
35 * This can be changed at runtime by using Memento_setParanoia(int level).
36 * 0 turns off such checking, 1 sets checking to happen on every event,
37 * any positive number n sets checking to happen once every n events,
38 * and any negative number n sets checking to happen after -n events, then
39 * after -2n events etc.
40 *
41 * The default paranoia level is therefore -1024.
42 *
43 * Memento keeps blocks around for a while after they have been freed, and
44 * checks them as part of these heap checks to see if they have been
45 * written to (or are freed twice etc).
46 *
47 * A given heap block can be checked for consistency (it's 'pre' and
48 * 'post' guard blocks are checked to see if they have been written to)
49 * by calling Memento_checkBlock(void *blockAddress);
50 *
51 * A check of all the memory can be triggered by calling Memento_check();
52 * (or Memento_checkAllMemory(); if you'd like it to be quieter).
53 *
54 * A good place to breakpoint is Memento_breakpoint, as this will then
55 * trigger your debugger if an error is detected. This is done
56 * automatically for debug windows builds.
57 *
58 * If a block is found to be corrupt, information will be printed to the
59 * console, including the address of the block, the size of the block,
60 * the type of corruption, the number of the block and the event on which
61 * it last passed a check for correctness.
62 *
63 * If you rerun, and call Memento_paranoidAt(int event); with this number
64 * the code will wait until it reaches that event and then start
65 * checking the heap after every allocation event. Assuming it is a
66 * deterministic failure, you should then find out where in your program
67 * the error is occurring (between event x-1 and event x).
68 *
69 * Then you can rerun the program again, and call
70 * Memento_breakAt(int event); and the program will call
71 * Memento_Breakpoint() when event x is reached, enabling you to step
72 * through.
73 *
74 * Memento_find(address) will tell you what block (if any) the given
75 * address is in.
76 *
77 * An example:
78 * Suppose we have a gs invocation that crashes with memory corruption.
79 * * Build with -DMEMENTO.
80 * * In your debugger put a breakpoint on Memento_breakpoint.
81 * * Run the program. It will stop in Memento_inited.
82 * * Execute Memento_setParanoia(1); (In VS use Ctrl-Alt-Q). (Note #1)
83 * * Continue execution.
84 * * It will detect the memory corruption on the next allocation event
85 * after it happens, and stop in Memento_breakpoint. The console should
86 * show something like:
87 *
88 * Freed blocks:
89 * 0x172e610(size=288,num=1415) index 256 (0x172e710) onwards corrupted
90 * Block last checked OK at allocation 1457. Now 1458.
91 *
92 * * This means that the block became corrupted between allocation 1457
93 * and 1458 - so if we rerun and stop the program at 1457, we can then
94 * step through, possibly with a data breakpoint at 0x172e710 and see
95 * when it occurs.
96 * * So restart the program from the beginning. When we stop after
97 * initialisation execute Memento_breakAt(1457); (and maybe
98 * Memento_setParanoia(1), or Memento_setParanoidAt(1457))
99 * * Continue execution until we hit Memento_breakpoint.
100 * * Now you can step through and watch the memory corruption happen.
101 *
102 * Note #1: Using Memento_setParanoia(1) can cause your program to run
103 * very slowly. You may instead choose to use Memento_setParanoia(100)
104 * (or some other figure). This will only exhaustively check memory on
105 * every 100th allocation event. This trades speed for the size of the
106 * average allocation event range in which detection of memory corruption
107 * occurs. You may (for example) choose to run once checking every 100
108 * allocations and discover that the corruption happens between events
109 * X and X+100. You can then rerun using Memento_paranoidAt(X), and
110 * it'll only start exhaustively checking when it reaches X.
111 *
112 * More than one memory allocator?
113 *
114 * If you have more than one memory allocator in the system (like for
115 * instance the ghostscript chunk allocator, that builds on top of the
116 * standard malloc and returns chunks itself), then there are some things
117 * to note:
118 *
119 * * If the secondary allocator gets its underlying blocks from calling
120 * malloc, then those will be checked by Memento, but 'subblocks' that
121 * are returned to the secondary allocator will not. There is currently
122 * no way to fix this other than trying to bypass the secondary
123 * allocator. One way I have found to do this with the chunk allocator
124 * is to tweak its idea of a 'large block' so that it puts every
125 * allocation in its own chunk. Clearly this negates the point of having
126 * a secondary allocator, and is therefore not recommended for general
127 * use.
128 *
129 * * Again, if the secondary allocator gets its underlying blocks from
130 * calling malloc (and hence Memento) leak detection should still work
131 * (but whole blocks will be detected rather than subblocks).
132 *
133 * * If on every allocation attempt the secondary allocator calls into
134 * Memento_failThisEvent(), and fails the allocation if it returns true
135 * then more useful features can be used; firstly memory squeezing will
136 * work, and secondly, Memento will have a "finer grained" paranoia
137 * available to it.
138 *
139 * Usage with C++:
140 *
141 * Memento has some experimental code in it to trap new/delete (and
142 * new[]/delete[] if required) calls.
143 *
144 * In order for this to work, either:
145 *
146 * 1) Build memento.c with the c++ compiler.
147 *
148 * or
149 *
150 * 2) Build memento.c as normal with the C compiler, then from any
151 * one of your .cpp files, do:
152 *
153 * #define MEMENTO_CPP_EXTRAS_ONLY
154 * #include "memento.c"
155 *
156 * In the case where MEMENTO is not defined, this will not do anything.
157 *
158 * Both Windows and GCC provide separate new[] and delete[] operators
159 * for arrays. Apparently some systems do not. If this is the case for
160 * your system, define MEMENTO_CPP_NO_ARRAY_CONSTRUCTORS.
161 *
162 * "libbacktrace.so failed to load"
163 *
164 * In order to give nice backtraces on unix, Memento will try to use
165 * a libbacktrace dynamic library. If it can't find it, you'll see
166 * that warning, and your backtraces won't include file/line information.
167 *
168 * To fix this you'll need to build your own libbacktrace. Don't worry
169 * it's really easy:
170 * git clone git://github.com/ianlancetaylor/libbacktrace
171 * cd libbacktrace
172 * ./configure
173 * make
174 *
175 * This leaves the build .so as .libs/libbacktrace.so
176 *
177 * Memento will look for this on LD_LIBRARY_PATH, or in /opt/lib/,
178 * or in /lib/, or in /usr/lib/, or in /usr/local/lib/. I recommend
179 * using /opt/lib/ as this won't conflict with anything that you
180 * get via a package manager like apt.
181 *
182 * sudo mkdir /opt
183 * sudo mkdir /opt/lib
184 * sudo cp .libs/libbacktrace.so /opt/lib/
185 */
186
187 #ifndef MEMENTO_H
188
189 #include <stdlib.h>
190 #include <stdarg.h>
191
192 #define MEMENTO_H
193
194 #ifndef MEMENTO_UNDERLYING_MALLOC
195 #define MEMENTO_UNDERLYING_MALLOC malloc
196 #endif
197 #ifndef MEMENTO_UNDERLYING_FREE
198 #define MEMENTO_UNDERLYING_FREE free
199 #endif
200 #ifndef MEMENTO_UNDERLYING_REALLOC
201 #define MEMENTO_UNDERLYING_REALLOC realloc
202 #endif
203 #ifndef MEMENTO_UNDERLYING_CALLOC
204 #define MEMENTO_UNDERLYING_CALLOC calloc
205 #endif
206
207 #ifndef MEMENTO_MAXALIGN
208 #define MEMENTO_MAXALIGN (sizeof(int))
209 #endif
210
211 #define MEMENTO_PREFILL 0xa6
212 #define MEMENTO_POSTFILL 0xa7
213 #define MEMENTO_ALLOCFILL 0xa8
214 #define MEMENTO_FREEFILL 0xa9
215
216 #define MEMENTO_FREELIST_MAX 0x2000000
217
218 int Memento_checkBlock(void *);
219 int Memento_checkAllMemory(void);
220 int Memento_check(void);
221
222 int Memento_setParanoia(int);
223 int Memento_paranoidAt(int);
224 int Memento_breakAt(int);
225 void Memento_breakOnFree(void *a);
226 void Memento_breakOnRealloc(void *a);
227 int Memento_getBlockNum(void *);
228 int Memento_find(void *a);
229 void Memento_breakpoint(void);
230 int Memento_failAt(int);
231 int Memento_failThisEvent(void);
232 void Memento_listBlocks(void);
233 void Memento_listNewBlocks(void);
234 size_t Memento_setMax(size_t);
235 void Memento_stats(void);
236 void *Memento_label(void *, const char *);
237 void Memento_tick(void);
238
239 void *Memento_malloc(size_t s);
240 void *Memento_realloc(void *, size_t s);
241 void Memento_free(void *);
242 void *Memento_calloc(size_t, size_t);
243 char *Memento_strdup(const char*);
244 int Memento_asprintf(char **ret, const char *format, ...);
245 int Memento_vasprintf(char **ret, const char *format, va_list ap);
246
247 void Memento_info(void *addr);
248 void Memento_listBlockInfo(void);
249 void *Memento_takeByteRef(void *blk);
250 void *Memento_dropByteRef(void *blk);
251 void *Memento_takeShortRef(void *blk);
252 void *Memento_dropShortRef(void *blk);
253 void *Memento_takeIntRef(void *blk);
254 void *Memento_dropIntRef(void *blk);
255 void *Memento_takeRef(void *blk);
256 void *Memento_dropRef(void *blk);
257 void *Memento_adjustRef(void *blk, int adjust);
258 void *Memento_reference(void *blk);
259
260 int Memento_checkPointerOrNull(void *blk);
261 int Memento_checkBytePointerOrNull(void *blk);
262 int Memento_checkShortPointerOrNull(void *blk);
263 int Memento_checkIntPointerOrNull(void *blk);
264
265 void Memento_startLeaking(void);
266 void Memento_stopLeaking(void);
267
268 /* Returns number of allocation events so far. */
269 int Memento_sequence(void);
270
271 /* Returns non-zero if our process was forked by Memento squeeze. */
272 int Memento_squeezing(void);
273
274 void Memento_fin(void);
275
276 void Memento_bt(void);
277
278 #ifdef MEMENTO
279
280 #ifndef COMPILING_MEMENTO_C
281 #define malloc Memento_malloc
282 #define free Memento_free
283 #define realloc Memento_realloc
284 #define calloc Memento_calloc
285 #define strdup Memento_strdup
286 #define asprintf Memento_asprintf
287 #define vasprintf Memento_vasprintf
288 #endif
289
290 #else
291
292 #define Memento_malloc MEMENTO_UNDERLYING_MALLOC
293 #define Memento_free MEMENTO_UNDERLYING_FREE
294 #define Memento_realloc MEMENTO_UNDERLYING_REALLOC
295 #define Memento_calloc MEMENTO_UNDERLYING_CALLOC
296 #define Memento_strdup strdup
297 #define Memento_asprintf asprintf
298 #define Memento_vasprintf vasprintf
299
300 #define Memento_checkBlock(A) 0
301 #define Memento_checkAllMemory() 0
302 #define Memento_check() 0
303 #define Memento_setParanoia(A) 0
304 #define Memento_paranoidAt(A) 0
305 #define Memento_breakAt(A) 0
306 #define Memento_breakOnFree(A) 0
307 #define Memento_breakOnRealloc(A) 0
308 #define Memento_getBlockNum(A) 0
309 #define Memento_find(A) 0
310 #define Memento_breakpoint() do {} while (0)
311 #define Memento_failAt(A) 0
312 #define Memento_failThisEvent() 0
313 #define Memento_listBlocks() do {} while (0)
314 #define Memento_listNewBlocks() do {} while (0)
315 #define Memento_setMax(A) 0
316 #define Memento_stats() do {} while (0)
317 #define Memento_label(A,B) (A)
318 #define Memento_info(A) do {} while (0)
319 #define Memento_listBlockInfo() do {} while (0)
320 #define Memento_takeByteRef(A) (A)
321 #define Memento_dropByteRef(A) (A)
322 #define Memento_takeShortRef(A) (A)
323 #define Memento_dropShortRef(A) (A)
324 #define Memento_takeIntRef(A) (A)
325 #define Memento_dropIntRef(A) (A)
326 #define Memento_takeRef(A) (A)
327 #define Memento_dropRef(A) (A)
328 #define Memento_adjustRef(A,V) (A)
329 #define Memento_reference(A) (A)
330 #define Memento_checkPointerOrNull(A) 0
331 #define Memento_checkBytePointerOrNull(A) 0
332 #define Memento_checkShortPointerOrNull(A) 0
333 #define Memento_checkIntPointerOrNull(A) 0
334
335 #define Memento_tick() do {} while (0)
336 #define Memento_startLeaking() do {} while (0)
337 #define Memento_stopLeaking() do {} while (0)
338 #define Memento_fin() do {} while (0)
339 #define Memento_bt() do {} while (0)
340 #define Memento_sequence() (0)
341 #define Memento_squeezing() (0)
342
343 #endif /* MEMENTO */
344
345 #endif /* MEMENTO_H */