Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/include/mupdf/fitz/context.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) 2004-2025 Artifex Software, Inc.
2 //
3 // This file is part of MuPDF.
4 //
5 // MuPDF is free software: you can redistribute it and/or modify it under the
6 // terms of the GNU Affero General Public License as published by the Free
7 // Software Foundation, either version 3 of the License, or (at your option)
8 // any later version.
9 //
10 // MuPDF is distributed in the hope that it will be useful, but WITHOUT ANY
11 // WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
12 // FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
13 // details.
14 //
15 // You should have received a copy of the GNU Affero General Public License
16 // along with MuPDF. If not, see <https://www.gnu.org/licenses/agpl-3.0.en.html>
17 //
18 // Alternative licensing terms are available from the licensor.
19 // For commercial licensing, see <https://www.artifex.com/> or contact
20 // Artifex Software, Inc., 39 Mesa Street, Suite 108A, San Francisco,
21 // CA 94129, USA, for further information.
22
23 #ifndef MUPDF_FITZ_CONTEXT_H
24 #define MUPDF_FITZ_CONTEXT_H
25
26 #include "mupdf/fitz/version.h"
27 #include "mupdf/fitz/system.h"
28 #include "mupdf/fitz/geometry.h"
29
30
31 #ifndef FZ_VERBOSE_EXCEPTIONS
32 #define FZ_VERBOSE_EXCEPTIONS 0
33 #endif
34
35 typedef struct fz_font_context fz_font_context;
36 typedef struct fz_colorspace_context fz_colorspace_context;
37 typedef struct fz_style_context fz_style_context;
38 typedef struct fz_tuning_context fz_tuning_context;
39 typedef struct fz_store fz_store;
40 typedef struct fz_glyph_cache fz_glyph_cache;
41 typedef struct fz_document_handler_context fz_document_handler_context;
42 typedef struct fz_archive_handler_context fz_archive_handler_context;
43 typedef struct fz_output fz_output;
44 typedef struct fz_context fz_context;
45
46 /**
47 Allocator structure; holds callbacks and private data pointer.
48 */
49 typedef struct
50 {
51 void *user;
52 void *(*malloc)(void *, size_t);
53 void *(*realloc)(void *, void *, size_t);
54 void (*free)(void *, void *);
55 } fz_alloc_context;
56
57 /**
58 Exception macro definitions. Just treat these as a black box -
59 pay no attention to the man behind the curtain.
60 */
61 #define fz_var(var) fz_var_imp((void *)&(var))
62 #define fz_try(ctx) if (!fz_setjmp(*fz_push_try(ctx))) if (fz_do_try(ctx)) do
63 #define fz_always(ctx) while (0); if (fz_do_always(ctx)) do
64 #define fz_catch(ctx) while (0); if (fz_do_catch(ctx))
65
66 /**
67 These macros provide a simple exception handling system. Use them as
68 follows:
69
70 fz_try(ctx)
71 ...
72 fz_catch(ctx)
73 ...
74
75 or as:
76
77 fz_try(ctx)
78 ...
79 fz_always(ctx)
80 ...
81 fz_catch(ctx)
82 ...
83
84 Code within the fz_try() section can then throw exceptions using fz_throw()
85 (or fz_vthrow()).
86
87 They are implemented with setjmp/longjmp, which can have unfortunate
88 consequences for 'losing' local variable values on a throw. To avoid this
89 we recommend calling 'fz_var(variable)' before the fz_try() for any
90 local variable whose value may change within the fz_try() block and whose
91 value will be required afterwards.
92
93 Do not call anything in the fz_always() section that can throw.
94
95 Any exception can be rethrown from the fz_catch() section using fz_rethrow()
96 as long as there has been no intervening use of fz_try/fz_catch.
97 */
98
99 /**
100 Throw an exception.
101
102 This assumes an enclosing fz_try() block within the callstack.
103 */
104 FZ_NORETURN void fz_vthrow(fz_context *ctx, int errcode, const char *, va_list ap);
105 FZ_NORETURN void fz_throw(fz_context *ctx, int errcode, const char *, ...) FZ_PRINTFLIKE(3,4);
106 FZ_NORETURN void fz_rethrow(fz_context *ctx);
107
108 /**
109 Called within a catch block this modifies the current
110 exception's code. If it's of type 'fromcode' it is
111 modified to 'tocode'. Typically used for 'downgrading'
112 exception severity.
113 */
114 void fz_morph_error(fz_context *ctx, int fromcode, int tocode);
115
116 /**
117 Log a warning.
118
119 This goes to the registered warning stream (stderr by
120 default).
121 */
122 void fz_vwarn(fz_context *ctx, const char *fmt, va_list ap);
123 void fz_warn(fz_context *ctx, const char *fmt, ...) FZ_PRINTFLIKE(2,3);
124
125 /**
126 Within an fz_catch() block, retrieve the formatted message
127 string for the current exception.
128
129 This assumes no intervening use of fz_try/fz_catch.
130 */
131 const char *fz_caught_message(fz_context *ctx);
132
133 /**
134 Within an fz_catch() block, retrieve the error code for
135 the current exception.
136
137 This assumes no intervening use of fz_try/fz_catch.
138 */
139 int fz_caught(fz_context *ctx);
140
141 /*
142 Within an fz_catch() block, retrieve the errno code for
143 the current SYSTEM exception.
144
145 Is undefined for non-SYSTEM errors.
146 */
147 int fz_caught_errno(fz_context *ctx);
148
149 /**
150 Within an fz_catch() block, rethrow the current exception
151 if the errcode of the current exception matches.
152
153 This assumes no intervening use of fz_try/fz_catch.
154 */
155 void fz_rethrow_if(fz_context *ctx, int errcode);
156 void fz_rethrow_unless(fz_context *ctx, int errcode);
157
158 /**
159 Format an error message, and log it to the registered
160 error stream (stderr by default).
161 */
162 void fz_log_error_printf(fz_context *ctx, const char *fmt, ...) FZ_PRINTFLIKE(2,3);
163 void fz_vlog_error_printf(fz_context *ctx, const char *fmt, va_list ap);
164
165 /**
166 Log a (preformatted) string to the registered
167 error stream (stderr by default).
168 */
169 void fz_log_error(fz_context *ctx, const char *str);
170
171 void fz_start_throw_on_repair(fz_context *ctx);
172 void fz_end_throw_on_repair(fz_context *ctx);
173
174 /**
175 Now, a debugging feature. If FZ_VERBOSE_EXCEPTIONS is 1 then
176 some of the above functions are replaced by versions that print
177 FILE and LINE information.
178 */
179 #if FZ_VERBOSE_EXCEPTIONS
180 #define fz_vthrow(CTX, ERRCODE, FMT, VA) fz_vthrowFL(CTX, __FILE__, __LINE__, ERRCODE, FMT, VA)
181 #define fz_throw(CTX, ERRCODE, ...) fz_throwFL(CTX, __FILE__, __LINE__, ERRCODE, __VA_ARGS__)
182 #define fz_rethrow(CTX) fz_rethrowFL(CTX, __FILE__, __LINE__)
183 #define fz_morph_error(CTX, FROM, TO) fz_morph_errorFL(CTX, __FILE__, __LINE__, FROM, TO)
184 #define fz_vwarn(CTX, FMT, VA) fz_vwarnFL(CTX, __FILE__, __LINE__, FMT, VA)
185 #define fz_warn(CTX, ...) fz_warnFL(CTX, __FILE__, __LINE__, __VA_ARGS__)
186 #define fz_rethrow_if(CTX, ERRCODE) fz_rethrow_ifFL(CTX, __FILE__, __LINE__, ERRCODE)
187 #define fz_rethrow_unless(CTX, ERRCODE) fz_rethrow_unlessFL(CTX, __FILE__, __LINE__, ERRCODE)
188 #define fz_log_error_printf(CTX, ...) fz_log_error_printfFL(CTX, __FILE__, __LINE__, __VA_ARGS__)
189 #define fz_vlog_error_printf(CTX, FMT, VA) fz_log_error_printfFL(CTX, __FILE__, __LINE__, FMT, VA)
190 #define fz_log_error(CTX, STR) fz_log_error_printfFL(CTX, __FILE__, __LINE__, STR)
191 #define fz_do_catch(CTX) fz_do_catchFL(CTX, __FILE__, __LINE__)
192 FZ_NORETURN void fz_vthrowFL(fz_context *ctx, const char *file, int line, int errcode, const char *fmt, va_list ap);
193 FZ_NORETURN void fz_throwFL(fz_context *ctx, const char *file, int line, int errcode, const char *fmt, ...) FZ_PRINTFLIKE(5,6);
194 FZ_NORETURN void fz_rethrowFL(fz_context *ctx, const char *file, int line);
195 void fz_morph_errorFL(fz_context *ctx, const char *file, int line, int fromcode, int tocode);
196 void fz_vwarnFL(fz_context *ctx, const char *file, int line, const char *fmt, va_list ap);
197 void fz_warnFL(fz_context *ctx, const char *file, int line, const char *fmt, ...) FZ_PRINTFLIKE(4,5);
198 void fz_rethrow_ifFL(fz_context *ctx, const char *file, int line, int errcode);
199 void fz_rethrow_unlessFL(fz_context *ctx, const char *file, int line, int errcode);
200 void fz_log_error_printfFL(fz_context *ctx, const char *file, int line, const char *fmt, ...) FZ_PRINTFLIKE(4,5);
201 void fz_vlog_error_printfFL(fz_context *ctx, const char *file, int line, const char *fmt, va_list ap);
202 void fz_log_errorFL(fz_context *ctx, const char *file, int line, const char *str);
203 int fz_do_catchFL(fz_context *ctx, const char *file, int line);
204 #endif
205
206 /* Report an error to the registered error callback. */
207 void fz_report_error(fz_context *ctx);
208
209 /*
210 * Swallow an error and ignore it completely.
211 * This should only be called to signal that you've handled a TRYLATER or ABORT error,
212 */
213 void fz_ignore_error(fz_context *ctx);
214
215 /* Convert an error into another runtime exception.
216 * For use when converting an exception from Fitz to a language binding exception.
217 */
218 const char *fz_convert_error(fz_context *ctx, int *code);
219
220 enum fz_error_type
221 {
222 FZ_ERROR_NONE,
223 FZ_ERROR_GENERIC,
224
225 FZ_ERROR_SYSTEM, // fatal out of memory or syscall error
226 FZ_ERROR_LIBRARY, // unclassified error from third-party library
227 FZ_ERROR_ARGUMENT, // invalid or out-of-range arguments to functions
228 FZ_ERROR_LIMIT, // failed because of resource or other hard limits
229 FZ_ERROR_UNSUPPORTED, // tried to use an unsupported feature
230 FZ_ERROR_FORMAT, // syntax or format errors that are unrecoverable
231 FZ_ERROR_SYNTAX, // syntax errors that should be diagnosed and ignored
232
233 // for internal use only
234 FZ_ERROR_TRYLATER, // try-later progressive loading signal
235 FZ_ERROR_ABORT, // user requested abort signal
236 FZ_ERROR_REPAIRED, // internal flag used when repairing a PDF to avoid cycles
237 };
238
239 /**
240 Flush any repeated warnings.
241
242 Repeated warnings are buffered, counted and eventually printed
243 along with the number of repetitions. Call fz_flush_warnings
244 to force printing of the latest buffered warning and the
245 number of repetitions, for example to make sure that all
246 warnings are printed before exiting an application.
247 */
248 void fz_flush_warnings(fz_context *ctx);
249
250 /**
251 Locking functions
252
253 MuPDF is kept deliberately free of any knowledge of particular
254 threading systems. As such, in order for safe multi-threaded
255 operation, we rely on callbacks to client provided functions.
256
257 A client is expected to provide FZ_LOCK_MAX number of mutexes,
258 and a function to lock/unlock each of them. These may be
259 recursive mutexes, but do not have to be.
260
261 If a client does not intend to use multiple threads, then it
262 may pass NULL instead of a lock structure.
263
264 In order to avoid deadlocks, we have one simple rule
265 internally as to how we use locks: We can never take lock n
266 when we already hold any lock i, where 0 <= i <= n. In order
267 to verify this, we have some debugging code, that can be
268 enabled by defining FITZ_DEBUG_LOCKING.
269 */
270
271 typedef struct
272 {
273 void *user;
274 void (*lock)(void *user, int lock);
275 void (*unlock)(void *user, int lock);
276 } fz_locks_context;
277
278 enum {
279 FZ_LOCK_ALLOC = 0,
280 FZ_LOCK_FREETYPE,
281 FZ_LOCK_GLYPHCACHE,
282 FZ_LOCK_MAX
283 };
284
285 #if defined(MEMENTO) || !defined(NDEBUG)
286 #define FITZ_DEBUG_LOCKING
287 #endif
288
289 #ifdef FITZ_DEBUG_LOCKING
290
291 void fz_assert_lock_held(fz_context *ctx, int lock);
292 void fz_assert_lock_not_held(fz_context *ctx, int lock);
293 void fz_lock_debug_lock(fz_context *ctx, int lock);
294 void fz_lock_debug_unlock(fz_context *ctx, int lock);
295
296 #else
297
298 #define fz_assert_lock_held(A,B) do { } while (0)
299 #define fz_assert_lock_not_held(A,B) do { } while (0)
300 #define fz_lock_debug_lock(A,B) do { } while (0)
301 #define fz_lock_debug_unlock(A,B) do { } while (0)
302
303 #endif /* !FITZ_DEBUG_LOCKING */
304
305 /**
306 Specifies the maximum size in bytes of the resource store in
307 fz_context. Given as argument to fz_new_context.
308
309 FZ_STORE_UNLIMITED: Let resource store grow unbounded.
310
311 FZ_STORE_DEFAULT: A reasonable upper bound on the size, for
312 devices that are not memory constrained.
313 */
314 enum {
315 FZ_STORE_UNLIMITED = 0,
316 FZ_STORE_DEFAULT = 256 << 20,
317 };
318
319 /**
320 Allocate context containing global state.
321
322 The global state contains an exception stack, resource store,
323 etc. Most functions in MuPDF take a context argument to be
324 able to reference the global state. See fz_drop_context for
325 freeing an allocated context.
326
327 alloc: Supply a custom memory allocator through a set of
328 function pointers. Set to NULL for the standard library
329 allocator. The context will keep the allocator pointer, so the
330 data it points to must not be modified or freed during the
331 lifetime of the context.
332
333 locks: Supply a set of locks and functions to lock/unlock
334 them, intended for multi-threaded applications. Set to NULL
335 when using MuPDF in a single-threaded applications. The
336 context will keep the locks pointer, so the data it points to
337 must not be modified or freed during the lifetime of the
338 context.
339
340 max_store: Maximum size in bytes of the resource store, before
341 it will start evicting cached resources such as fonts and
342 images. FZ_STORE_UNLIMITED can be used if a hard limit is not
343 desired. Use FZ_STORE_DEFAULT to get a reasonable size.
344
345 May return NULL.
346 */
347 #define fz_new_context(alloc, locks, max_store) fz_new_context_imp(alloc, locks, max_store, FZ_VERSION)
348
349 /**
350 Make a clone of an existing context.
351
352 This function is meant to be used in multi-threaded
353 applications where each thread requires its own context, yet
354 parts of the global state, for example caching, are shared.
355
356 ctx: Context obtained from fz_new_context to make a copy of.
357 ctx must have had locks and lock/functions setup when created.
358 The two contexts will share the memory allocator, resource
359 store, locks and lock/unlock functions. They will each have
360 their own exception stacks though.
361
362 May return NULL.
363 */
364 fz_context *fz_clone_context(fz_context *ctx);
365
366 /**
367 Free a context and its global state.
368
369 The context and all of its global state is freed, and any
370 buffered warnings are flushed (see fz_flush_warnings). If NULL
371 is passed in nothing will happen.
372
373 Must not be called for a context that is being used in an active
374 fz_try(), fz_always() or fz_catch() block.
375 */
376 void fz_drop_context(fz_context *ctx);
377
378 /**
379 Set the user field in the context.
380
381 NULL initially, this field can be set to any opaque value
382 required by the user. It is copied on clones.
383 */
384 void fz_set_user_context(fz_context *ctx, void *user);
385
386 /**
387 Read the user field from the context.
388 */
389 void *fz_user_context(fz_context *ctx);
390
391 /**
392 FIXME: Better not to expose fz_default_error_callback, and
393 fz_default_warning callback and to allow 'NULL' to be used
394 int fz_set_xxxx_callback to mean "defaults".
395
396 FIXME: Do we need/want functions like
397 fz_error_callback(ctx, message) to allow callers to inject
398 stuff into the error/warning streams?
399 */
400 /**
401 The default error callback. Declared publicly just so that the
402 error callback can be set back to this after it has been
403 overridden.
404 */
405 void fz_default_error_callback(void *user, const char *message);
406
407 /**
408 The default warning callback. Declared publicly just so that
409 the warning callback can be set back to this after it has been
410 overridden.
411 */
412 void fz_default_warning_callback(void *user, const char *message);
413
414 /**
415 A callback called whenever an error message is generated.
416 The user pointer passed to fz_set_error_callback() is passed
417 along with the error message.
418 */
419 typedef void (fz_error_cb)(void *user, const char *message);
420
421 /**
422 A callback called whenever a warning message is generated.
423 The user pointer passed to fz_set_warning_callback() is
424 passed along with the warning message.
425 */
426 typedef void (fz_warning_cb)(void *user, const char *message);
427
428 /**
429 Set the error callback. This will be called as part of the
430 exception handling.
431
432 The callback must not throw exceptions!
433 */
434 void fz_set_error_callback(fz_context *ctx, fz_error_cb *error_cb, void *user);
435
436 /**
437 Retrieve the currently set error callback, or NULL if none
438 has been set. Optionally, if user is non-NULL, the user pointer
439 given when the warning callback was set is also passed back to
440 the caller.
441 */
442 fz_error_cb *fz_error_callback(fz_context *ctx, void **user);
443
444 /**
445 Set the warning callback. This will be called as part of the
446 exception handling.
447
448 The callback must not throw exceptions!
449 */
450 void fz_set_warning_callback(fz_context *ctx, fz_warning_cb *warning_cb, void *user);
451
452 /**
453 Retrieve the currently set warning callback, or NULL if none
454 has been set. Optionally, if user is non-NULL, the user pointer
455 given when the warning callback was set is also passed back to
456 the caller.
457 */
458 fz_warning_cb *fz_warning_callback(fz_context *ctx, void **user);
459
460 /**
461 In order to tune MuPDF's behaviour, certain functions can
462 (optionally) be provided by callers.
463 */
464
465 /**
466 Given the width and height of an image,
467 the subsample factor, and the subarea of the image actually
468 required, the caller can decide whether to decode the whole
469 image or just a subarea.
470
471 arg: The caller supplied opaque argument.
472
473 w, h: The width/height of the complete image.
474
475 l2factor: The log2 factor for subsampling (i.e. image will be
476 decoded to (w>>l2factor, h>>l2factor)).
477
478 subarea: The actual subarea required for the current operation.
479 The tuning function is allowed to increase this in size if
480 required.
481 */
482 typedef void (fz_tune_image_decode_fn)(void *arg, int w, int h, int l2factor, fz_irect *subarea);
483
484 /**
485 Given the source width and height of
486 image, together with the actual required width and height,
487 decide whether we should use mitchell scaling.
488
489 arg: The caller supplied opaque argument.
490
491 dst_w, dst_h: The actual width/height required on the target
492 device.
493
494 src_w, src_h: The source width/height of the image.
495
496 Return 0 not to use the Mitchell scaler, 1 to use the Mitchell
497 scaler. All other values reserved.
498 */
499 typedef int (fz_tune_image_scale_fn)(void *arg, int dst_w, int dst_h, int src_w, int src_h);
500
501 /**
502 Set the tuning function to use for
503 image decode.
504
505 image_decode: Function to use.
506
507 arg: Opaque argument to be passed to tuning function.
508 */
509 void fz_tune_image_decode(fz_context *ctx, fz_tune_image_decode_fn *image_decode, void *arg);
510
511 /**
512 Set the tuning function to use for
513 image scaling.
514
515 image_scale: Function to use.
516
517 arg: Opaque argument to be passed to tuning function.
518 */
519 void fz_tune_image_scale(fz_context *ctx, fz_tune_image_scale_fn *image_scale, void *arg);
520
521 /**
522 Get the number of bits of antialiasing we are
523 using (for graphics). Between 0 and 8.
524 */
525 int fz_aa_level(fz_context *ctx);
526
527 /**
528 Set the number of bits of antialiasing we should
529 use (for both text and graphics).
530
531 bits: The number of bits of antialiasing to use (values are
532 clamped to within the 0 to 8 range).
533 */
534 void fz_set_aa_level(fz_context *ctx, int bits);
535
536 /**
537 Get the number of bits of antialiasing we are
538 using for text. Between 0 and 8.
539 */
540 int fz_text_aa_level(fz_context *ctx);
541
542 /**
543 Set the number of bits of antialiasing we
544 should use for text.
545
546 bits: The number of bits of antialiasing to use (values are
547 clamped to within the 0 to 8 range).
548 */
549 void fz_set_text_aa_level(fz_context *ctx, int bits);
550
551 /**
552 Get the number of bits of antialiasing we are
553 using for graphics. Between 0 and 8.
554 */
555 int fz_graphics_aa_level(fz_context *ctx);
556
557 /**
558 Set the number of bits of antialiasing we
559 should use for graphics.
560
561 bits: The number of bits of antialiasing to use (values are
562 clamped to within the 0 to 8 range).
563 */
564 void fz_set_graphics_aa_level(fz_context *ctx, int bits);
565
566 /**
567 Get the minimum line width to be
568 used for stroked lines.
569
570 min_line_width: The minimum line width to use (in pixels).
571 */
572 float fz_graphics_min_line_width(fz_context *ctx);
573
574 /**
575 Set the minimum line width to be
576 used for stroked lines.
577
578 min_line_width: The minimum line width to use (in pixels).
579 */
580 void fz_set_graphics_min_line_width(fz_context *ctx, float min_line_width);
581
582 /**
583 Get the user stylesheet source text.
584 */
585 const char *fz_user_css(fz_context *ctx);
586
587 /**
588 Set the user stylesheet source text for use with HTML and EPUB.
589 */
590 void fz_set_user_css(fz_context *ctx, const char *text);
591
592 /**
593 Set the user stylesheet by loading the source from a file.
594 If the file is missing, do nothing.
595 */
596 void fz_load_user_css(fz_context *ctx, const char *filename);
597
598 /**
599 Return whether to respect document styles in HTML and EPUB.
600 */
601 int fz_use_document_css(fz_context *ctx);
602
603 /**
604 Toggle whether to respect document styles in HTML and EPUB.
605 */
606 void fz_set_use_document_css(fz_context *ctx, int use);
607
608 /**
609 Enable icc profile based operation.
610 */
611 void fz_enable_icc(fz_context *ctx);
612
613 /**
614 Disable icc profile based operation.
615 */
616 void fz_disable_icc(fz_context *ctx);
617
618 /**
619 Memory Allocation and Scavenging:
620
621 All calls to MuPDF's allocator functions pass through to the
622 underlying allocators passed in when the initial context is
623 created, after locks are taken (using the supplied locking
624 function) to ensure that only one thread at a time calls
625 through.
626
627 If the underlying allocator fails, MuPDF attempts to make room
628 for the allocation by evicting elements from the store, then
629 retrying.
630
631 Any call to allocate may then result in several calls to the
632 underlying allocator, and result in elements that are only
633 referred to by the store being freed.
634 */
635
636 /**
637 Allocate memory for a structure, clear it, and tag the pointer
638 for Memento.
639
640 Throws exception in the event of failure to allocate.
641 */
642 #define fz_malloc_struct(CTX, TYPE) \
643 ((TYPE*)Memento_label(fz_calloc(CTX, 1, sizeof(TYPE)), #TYPE))
644
645 /**
646 Allocate memory for an array of structures, clear it, and tag
647 the pointer for Memento.
648
649 Throws exception in the event of failure to allocate.
650 */
651 #define fz_malloc_struct_array(CTX, N, TYPE) \
652 ((TYPE*)Memento_label(fz_calloc(CTX, N, sizeof(TYPE)), #TYPE "[]"))
653
654 /**
655 Allocate uninitialized memory for an array of structures, and
656 tag the pointer for Memento. Does NOT clear the memory!
657
658 Throws exception in the event of failure to allocate.
659 */
660 #define fz_malloc_array(CTX, COUNT, TYPE) \
661 ((TYPE*)Memento_label(fz_malloc(CTX, (COUNT) * sizeof(TYPE)), #TYPE "[]"))
662 #define fz_realloc_array(CTX, OLD, COUNT, TYPE) \
663 ((TYPE*)Memento_label(fz_realloc(CTX, OLD, (COUNT) * sizeof(TYPE)), #TYPE "[]"))
664
665 /**
666 Allocate uninitialized memory of a given size.
667 Does NOT clear the memory!
668
669 May return NULL for size = 0.
670
671 Throws exception in the event of failure to allocate.
672 */
673 void *fz_malloc(fz_context *ctx, size_t size);
674
675 /**
676 Allocate array of memory of count entries of size bytes.
677 Clears the memory to zero.
678
679 Throws exception in the event of failure to allocate.
680 */
681 void *fz_calloc(fz_context *ctx, size_t count, size_t size);
682
683 /**
684 Reallocates a block of memory to given size. Existing contents
685 up to min(old_size,new_size) are maintained. The rest of the
686 block is uninitialised.
687
688 fz_realloc(ctx, NULL, size) behaves like fz_malloc(ctx, size).
689
690 fz_realloc(ctx, p, 0); behaves like fz_free(ctx, p).
691
692 Throws exception in the event of failure to allocate.
693 */
694 void *fz_realloc(fz_context *ctx, void *p, size_t size);
695
696 /**
697 Free a previously allocated block of memory.
698
699 fz_free(ctx, NULL) does nothing.
700
701 Never throws exceptions.
702 */
703 void fz_free(fz_context *ctx, void *p);
704
705 /**
706 Flexible array member allocation helpers.
707 */
708 #define fz_malloc_flexible(ctx, T, M, count) \
709 Memento_label(fz_calloc(ctx, 1, offsetof(T, M) + sizeof(*((T*)0)->M) * (count)), #T)
710 #define fz_realloc_flexible(ctx, p, T, M, count) \
711 Memento_label(fz_realloc(ctx, p, offsetof(T, M) + sizeof(*((T*)0)->M) * (count)), #T)
712 #define fz_pool_alloc_flexible(ctx, pool, T, M, count) \
713 fz_pool_alloc(ctx, pool, offsetof(T, M) + sizeof(*((T*)0)->M) * (count))
714
715 /**
716 fz_malloc equivalent that returns NULL rather than throwing
717 exceptions.
718 */
719 void *fz_malloc_no_throw(fz_context *ctx, size_t size);
720
721 /**
722 fz_calloc equivalent that returns NULL rather than throwing
723 exceptions.
724 */
725 void *fz_calloc_no_throw(fz_context *ctx, size_t count, size_t size);
726
727 /**
728 fz_realloc equivalent that returns NULL rather than throwing
729 exceptions.
730 */
731 void *fz_realloc_no_throw(fz_context *ctx, void *p, size_t size);
732
733 /**
734 fz_malloc equivalent, except that the block is guaranteed aligned.
735 Block must be freed later using fz_free_aligned.
736 */
737 void *fz_malloc_aligned(fz_context *ctx, size_t size, int align);
738
739 /**
740 fz_free equivalent, for blocks allocated via fz_malloc_aligned.
741 */
742 void fz_free_aligned(fz_context *ctx, void *p);
743
744 /**
745 Portable strdup implementation, using fz allocators.
746 */
747 char *fz_strdup(fz_context *ctx, const char *s);
748
749 /**
750 Fill block with len bytes of pseudo-randomness.
751 */
752 void fz_memrnd(fz_context *ctx, uint8_t *block, int len);
753
754 /*
755 Reference counted malloced C strings.
756 */
757 typedef struct
758 {
759 int refs;
760 char str[FZ_FLEXIBLE_ARRAY];
761 } fz_string;
762
763 /*
764 Allocate a new string to hold a copy of str.
765
766 Returns with a refcount of 1.
767 */
768 fz_string *fz_new_string(fz_context *ctx, const char *str);
769
770 /*
771 Take another reference to a string.
772 */
773 fz_string *fz_keep_string(fz_context *ctx, fz_string *str);
774
775 /*
776 Drop a reference to a string, freeing if the refcount
777 reaches 0.
778 */
779 void fz_drop_string(fz_context *ctx, fz_string *str);
780
781 #define fz_cstring_from_string(A) ((A) == NULL ? NULL : (A)->str)
782
783 /* Implementation details: subject to change. */
784
785 /* Implementations exposed for speed, but considered private. */
786
787 void fz_var_imp(void *);
788 fz_jmp_buf *fz_push_try(fz_context *ctx);
789 int fz_do_try(fz_context *ctx);
790 int fz_do_always(fz_context *ctx);
791 int (fz_do_catch)(fz_context *ctx);
792
793 #ifndef FZ_JMPBUF_ALIGN
794 #define FZ_JMPBUF_ALIGN 32
795 #endif
796
797 typedef struct
798 {
799 fz_jmp_buf buffer;
800 int state, code;
801 char padding[FZ_JMPBUF_ALIGN-sizeof(int)*2];
802 } fz_error_stack_slot;
803
804 typedef struct
805 {
806 fz_error_stack_slot *top;
807 fz_error_stack_slot stack[256];
808 fz_error_stack_slot padding;
809 fz_error_stack_slot *stack_base;
810 int errcode;
811 int errnum; /* errno for SYSTEM class errors */
812 void *print_user;
813 void (*print)(void *user, const char *message);
814 char message[256];
815 } fz_error_context;
816
817 typedef struct
818 {
819 void *print_user;
820 void (*print)(void *user, const char *message);
821 int count;
822 char message[256];
823 } fz_warn_context;
824
825 typedef struct
826 {
827 int hscale;
828 int vscale;
829 int scale;
830 int bits;
831 int text_bits;
832 float min_line_width;
833 } fz_aa_context;
834
835 typedef enum
836 {
837 FZ_ACTIVITY_NEW_DOC = 0,
838 FZ_ACTIVITY_SHUTDOWN = 1
839 } fz_activity_reason;
840
841 typedef void (fz_activity_fn)(fz_context *ctx, void *opaque, fz_activity_reason reason, void *reason_arg);
842
843 typedef struct
844 {
845 void *opaque;
846 fz_activity_fn *activity;
847 } fz_activity_context;
848
849 void fz_register_activity_logger(fz_context *ctx, fz_activity_fn *activity, void *opaque);
850
851 struct fz_context
852 {
853 void *user;
854
855 /* If master points to itself, then we are the master context.
856 * If master is NULL, then we are the master context, but we have
857 * been destroyed. We exist just so the count of clones can live
858 * on. Otherwise master points to the master context from which
859 * we were cloned. */
860 fz_context *master;
861 /* The number of contexts in this family. 1 for this one, plus
862 * 1 for every context cloned (directly or indirectly) from it. */
863 int context_count;
864
865 /* Only the master version of this is used! */
866 int next_document_id;
867
868 fz_alloc_context alloc;
869 fz_locks_context locks;
870 fz_error_context error;
871 fz_warn_context warn;
872 fz_activity_context activity;
873
874 /* unshared contexts */
875 fz_aa_context aa;
876 uint16_t seed48[7];
877 #if FZ_ENABLE_ICC
878 int icc_enabled;
879 #endif
880 int throw_on_repair;
881
882 /* TODO: should these be unshared? */
883 fz_document_handler_context *handler;
884 fz_archive_handler_context *archive;
885 fz_style_context *style;
886 fz_tuning_context *tuning;
887
888 /* shared contexts */
889 fz_output *stddbg;
890 fz_font_context *font;
891 fz_colorspace_context *colorspace;
892 fz_store *store;
893 fz_glyph_cache *glyph_cache;
894 };
895
896 fz_context *fz_new_context_imp(const fz_alloc_context *alloc, const fz_locks_context *locks, size_t max_store, const char *version);
897
898 /**
899 Lock one of the user supplied mutexes.
900 */
901 static inline void
902 fz_lock(fz_context *ctx, int lock)
903 {
904 fz_lock_debug_lock(ctx, lock);
905 ctx->locks.lock(ctx->locks.user, lock);
906 }
907
908 /**
909 Unlock one of the user supplied mutexes.
910 */
911 static inline void
912 fz_unlock(fz_context *ctx, int lock)
913 {
914 fz_lock_debug_unlock(ctx, lock);
915 ctx->locks.unlock(ctx->locks.user, lock);
916 }
917
918 /* Lock-safe reference counting functions */
919
920 static inline void *
921 fz_keep_imp(fz_context *ctx, void *p, int *refs)
922 {
923 if (p)
924 {
925 (void)Memento_checkIntPointerOrNull(refs);
926 fz_lock(ctx, FZ_LOCK_ALLOC);
927 if (*refs > 0)
928 {
929 (void)Memento_takeRef(p);
930 ++*refs;
931 }
932 fz_unlock(ctx, FZ_LOCK_ALLOC);
933 }
934 return p;
935 }
936
937 static inline void *
938 fz_keep_imp_locked(fz_context *ctx FZ_UNUSED, void *p, int *refs)
939 {
940 if (p)
941 {
942 (void)Memento_checkIntPointerOrNull(refs);
943 if (*refs > 0)
944 {
945 (void)Memento_takeRef(p);
946 ++*refs;
947 }
948 }
949 return p;
950 }
951
952 static inline void *
953 fz_keep_imp8_locked(fz_context *ctx FZ_UNUSED, void *p, int8_t *refs)
954 {
955 if (p)
956 {
957 (void)Memento_checkIntPointerOrNull(refs);
958 if (*refs > 0)
959 {
960 (void)Memento_takeRef(p);
961 ++*refs;
962 }
963 }
964 return p;
965 }
966
967 static inline void *
968 fz_keep_imp8(fz_context *ctx, void *p, int8_t *refs)
969 {
970 if (p)
971 {
972 (void)Memento_checkBytePointerOrNull(refs);
973 fz_lock(ctx, FZ_LOCK_ALLOC);
974 if (*refs > 0)
975 {
976 (void)Memento_takeRef(p);
977 ++*refs;
978 }
979 fz_unlock(ctx, FZ_LOCK_ALLOC);
980 }
981 return p;
982 }
983
984 static inline void *
985 fz_keep_imp16(fz_context *ctx, void *p, int16_t *refs)
986 {
987 if (p)
988 {
989 (void)Memento_checkShortPointerOrNull(refs);
990 fz_lock(ctx, FZ_LOCK_ALLOC);
991 if (*refs > 0)
992 {
993 (void)Memento_takeRef(p);
994 ++*refs;
995 }
996 fz_unlock(ctx, FZ_LOCK_ALLOC);
997 }
998 return p;
999 }
1000
1001 static inline int
1002 fz_drop_imp(fz_context *ctx, void *p, int *refs)
1003 {
1004 if (p)
1005 {
1006 int drop;
1007 (void)Memento_checkIntPointerOrNull(refs);
1008 fz_lock(ctx, FZ_LOCK_ALLOC);
1009 if (*refs > 0)
1010 {
1011 (void)Memento_dropIntRef(p);
1012 drop = --*refs == 0;
1013 }
1014 else
1015 drop = 0;
1016 fz_unlock(ctx, FZ_LOCK_ALLOC);
1017 return drop;
1018 }
1019 return 0;
1020 }
1021
1022 static inline int
1023 fz_drop_imp8(fz_context *ctx, void *p, int8_t *refs)
1024 {
1025 if (p)
1026 {
1027 int drop;
1028 (void)Memento_checkBytePointerOrNull(refs);
1029 fz_lock(ctx, FZ_LOCK_ALLOC);
1030 if (*refs > 0)
1031 {
1032 (void)Memento_dropByteRef(p);
1033 drop = --*refs == 0;
1034 }
1035 else
1036 drop = 0;
1037 fz_unlock(ctx, FZ_LOCK_ALLOC);
1038 return drop;
1039 }
1040 return 0;
1041 }
1042
1043 static inline int
1044 fz_drop_imp16(fz_context *ctx, void *p, int16_t *refs)
1045 {
1046 if (p)
1047 {
1048 int drop;
1049 (void)Memento_checkShortPointerOrNull(refs);
1050 fz_lock(ctx, FZ_LOCK_ALLOC);
1051 if (*refs > 0)
1052 {
1053 (void)Memento_dropShortRef(p);
1054 drop = --*refs == 0;
1055 }
1056 else
1057 drop = 0;
1058 fz_unlock(ctx, FZ_LOCK_ALLOC);
1059 return drop;
1060 }
1061 return 0;
1062 }
1063
1064 #endif