"pma", a persistent memory allocator
version "2022.10Oct.30.1667172241 (Avon 8)"
Copyright (C) 2022 Terence Kelly
Contact: tpkelly @ { acm.org, cs.princeton.edu, eecs.umich.edu }
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License
along with this program. If not, see .
The authoritative "One True Version" of pma is available at
http://web.eecs.umich.edu/~tpkelly/pma/ [optionally "https"]
Partial or complete copies may appear elsewhere, e.g., GitHub or in
the GNU AWK (gawk) distribution, but the above Web site is the main
home and original source. Check it for updates and write to me if
you'd like to be notified about updates via e-mail. I welcome
feedback of any kind.
See the "NEWS" file for a summary of changes since previous release.
The design of pma is described in an article in ACM _Queue_ magazine,
March/April 2022. An early application of pma is in "persistent
memory gawk" (pm-gawk), released with gawk 5.2 in September 2022.
The prototype upon which pm-gawk is based is described in a paper in
NVMW 2022; see References below.
Usage: Applications #include "pma.h" and compile & link with pma.c
using a recent version of a modern compiler. See pma.h for interface
notes and pma.c for compilation notes. On older systems you might
need to link with "-lm". Requirements/assumptions include 64-bit
machine words (longs and pointers) and reasonable page sizes.
Testing & debugging: Applications that use pma should be tested with
assertions enabled and with verbose pma diagnostics enabled.
Enabling assertions may also enable heap integrity checks at entrance
and exit of functions such as pma_malloc and pma_free, which can
identify heap corruption and determine whether it is caused by pma or
by the client (i.e., the caller). One way to pinpoint heap
corruption in client code is to add code to print a backtrace early
in pma's integrity check function.
The most novel aspect for newcomers to persistent memory programming
is the role of the "root pointer." See my articles in ACM _Queue_
magazine v17n4 and v20n2 for an explanation.
Most of the test programs bundled with pma are primarily intended to
exercise pma functionality for my benefit; they're not optimized for
tutorial value. However they illustrate basic usage and you might
learn a trick or two by studying them. For example, test5 shows how
to use the root pointer; test6 shows how to make pma fall back on the
conventional ephemeral memory allocator (standard malloc); and test7
shows an easy way to create a persistent C++ STL container by sliding
a pma persistent heap beneath an STL