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
       7  
       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.
      12  
      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.
      17  
      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/>.
      20  */
      21  
      22  #ifndef PMA_H_INCLUDED
      23  #define PMA_H_INCLUDED
      24  
      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[];
      28  
      29  /* May contain line number in pma.c where something went wrong if one
      30     of the other interfaces fails.  "Use the Source, Luke." */
      31  extern int pma_errno;
      32  
      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);
      60  
      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);
      68  
      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
      74     bugs. */
      75  extern void   pma_set_root(void *ptr);
      76  extern void * pma_get_root(void);
      77  
      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);
      81  
      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);
      86  
      87  #endif // PMA_H_INCLUDED