Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/docs/reference/c/fitz/memory.md @ 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 # Memory
2
3 All memory in Fitz is allocated through an allocator, which allows you to use
4 a custom allocator instead of the system malloc if you need to.
5
6 ## Malloc & Free
7
8 You should not need to do raw memory allocation using the Fitz context, but if
9 you do, here are the functions you need. These work just like the regular C
10 functions, but take a Fitz context and throw an exception if the allocation
11 fails. They will **not** return `NULL`; either they will succeed or they will
12 throw an exception.
13
14 void *fz_malloc(fz_context *ctx, size_t size);
15 void *fz_realloc(fz_context *ctx, void *old, size_t size);
16 void *fz_calloc(fz_context *ctx, size_t count, size_t size);
17 void fz_free(fz_context *ctx, void *ptr);
18
19 There are also some macros that allocate structures and arrays, together with a type cast to catch typing errors.
20
21 T *fz_malloc_struct(fz_context *ctx, T); // Allocate and zero the memory.
22 T *fz_malloc_array(fz_context *ctx, size_t count, T); // Allocate uninitialized memory!
23 T *fz_realloc_array(fz_context *ctx, T *old, size_t count, T);
24
25 In the rare case that you need an allocation that returns `NULL` on failure,
26 there are variants for that too: `fz_malloc_no_throw`, etc.
27
28 ## Pool Allocator
29
30 The pool allocator is used for allocating many small objects that live and die
31 together. All objects allocated from the pool will be freed when the pool is
32 freed.
33
34 fz_pool *fz_new_pool(fz_context *ctx);
35 void *fz_pool_alloc(fz_context *ctx, fz_pool *pool, size_t size);
36 char *fz_pool_strdup(fz_context *ctx, fz_pool *pool, const char *s);
37 void fz_drop_pool(fz_context *ctx, fz_pool *pool);
38
39 ## Reference Counting
40
41 Most objects in MuPDF use reference counting to keep track of when they are no
42 longer used and can be freed. We use the verbs "keep" and "drop" to increment
43 and decrement the reference count. For simplicity, we also use the word "drop"
44 for non-reference counted objects (so that in case we change our minds and
45 decide to add reference counting to an object, the code that uses it need not
46 change).