1
/* "pma", a persistent memory allocator (interface)
2
Copyright (C) 2022 Terence Kelly
3
Contact: tpkelly @ { acm.org, cs.princeton.edu, eecs.umich.edu }
4
Home: http://web.eecs.umich.edu/~tpkelly/pma/ [or "https"]
5
Design: HTML: https://queue.acm.org/detail.cfm?id=3534855
6
PDF: https://dl.acm.org/doi/pdf/10.1145/3534855
8
This program is free software: you can redistribute it and/or modify
9
it under the terms of the GNU Affero General Public License as published by
10
the Free Software Foundation, either version 3 of the License, or
11
(at your option) any later version.
13
This program is distributed in the hope that it will be useful,
14
but WITHOUT ANY WARRANTY; without even the implied warranty of
15
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16
GNU Affero General Public License for more details.
18
You should have received a copy of the GNU Affero General Public License
19
along with this program. If not, see <https://www.gnu.org/licenses/>.
22
#ifndef PMA_H_INCLUDED
23
#define PMA_H_INCLUDED
25
// version strings of interface and implementation should match
26
#define PMA_H_VERSION "2022.10Oct.30.1667172241 (Avon 8-g1)"
27
extern const char pma_version[];
29
/* May contain line number in pma.c where something went wrong if one
30
of the other interfaces fails. "Use the Source, Luke." */
33
/* Must be called exactly once before any other pma_* function is
34
called, otherwise behavior is undefined. Available verbosity
35
levels are: 0 => no diagnostic printouts, 1 => errors only printed
36
to stderr, 2 => also warnings, 3 => also very verbose "FYI"
37
messages. Verbosity level 2 is recommended. Verbosity may be
38
over-ridden via environment variable PMA_VERBOSITY. File argument
39
specifies backing file containing persistent heap, which must
40
initially be an empty (logically all zeros) file, and ideally also
41
a sparse file. Backing file size must be a multiple of the system
42
page size on first use; ideally the backing file should also be a
43
multiple of the address alignment enforced in the implementation.
44
The backing file does not grow so it must be large enough to hold
45
the largest persistent heap that the application might need (if
46
the file is sparse, its storage resource footprint is "pay as you
47
go," so there's no downside to making it generously large). If
48
file argument is NULL, pma will fall back on standard memory
49
allocator: pma_malloc passes the buck to ordinary malloc, pma_free
50
calls ordinary free, etc. In fallback-to-standard-malloc mode,
51
only pma_malloc/calloc/realloc/free may be used; other functions
52
such as pma_get/set_root must not be used. The implementation may
53
store a copy of the file argument, i.e., the pointer, so both this
54
pointer and the memory to which it points (*file) must not change.
55
Initialization may perform an integrity check on the heap; this
56
check may be slow depending on the complexity of the heap. Any
57
non-zero return value indicates trouble; inspect both the value
58
returned and also pma_errno. */
59
extern int pma_init(int verbose, const char *file);
61
/* The following four functions may be used like their standard
62
counterparts. See notes on pma_init for fallback to standard
63
allocator. See notes on fork in README. */
64
extern void * pma_malloc(size_t size);
65
extern void * pma_calloc(size_t nmemb, size_t size);
66
extern void * pma_realloc(void *ptr, size_t size);
67
extern void pma_free(void *ptr);
69
/* The following two functions access the persistent heap's root
70
pointer, which must either be NULL or must point within a block of
71
persistent memory. If the pointer passed to pma_set_root is not a
72
pointer returned by pma_malloc/calloc/realloc, that is likely a
73
bug, though the implementation is not obliged to check for such
75
extern void pma_set_root(void *ptr);
76
extern void * pma_get_root(void);
78
/* Prints to stderr details of internal data structures, e.g., free
79
lists, and performs integrity checks, which may be very slow. */
80
extern void pma_check_and_dump(void);
82
/* Set non-metadata words of free blocks to given value. Useful for
83
debugging (v == 0xdeadDEADbeefBEEF) and for preparing backing file
84
to be re-sparsified with fallocate (v == 0x0). */
85
extern void pma_set_avail_mem(const unsigned long v);
87
#endif // PMA_H_INCLUDED
added
removed
support/pma.h
