src/xbt/mmalloc/mmalloc.info

   1 This is ./mmalloc.info, produced by makeinfo version 4.6 from
   2 mmalloc.texi.
   3
   4 START-INFO-DIR-ENTRY
   5 * Mmalloc: (mmalloc).           The GNU mapped-malloc package.
   6 END-INFO-DIR-ENTRY
   7
   8    This file documents the GNU mmalloc (mapped-malloc) package, written
   9 by fnf@cygnus.com, based on GNU malloc written by mike@ai.mit.edu.
  10
  11    Copyright (C) 1992 Free Software Foundation, Inc.
  12
  13    Permission is granted to make and distribute verbatim copies of this
  14 manual provided the copyright notice and this permission notice are
  15 preserved on all copies.
  16
  17    Permission is granted to copy and distribute modified versions of
  18 this manual under the conditions for verbatim copying, provided also
  19 that the entire resulting derived work is distributed under the terms
  20 of a permission notice identical to this one.
  21
  22    Permission is granted to copy and distribute translations of this
  23 manual into another language, under the above conditions for modified
  24 versions.
  25
  26 \1f
  27 File: mmalloc.info,  Node: Top,  Next: Overview,  Prev: (dir),  Up: (dir)
  28
  29 mmalloc
  30 *******
  31
  32 This file documents the GNU memory-mapped malloc package mmalloc.
  33
  34 * Menu:
  35
  36 * Overview::                    Overall Description
  37 * Implementation::              Implementation
  38
  39  --- The Detailed Node Listing ---
  40
  41 Implementation
  42
  43 * Compatibility::               Backwards Compatibility
  44 * Functions::                   Function Descriptions
  45
  46 \1f
  47 File: mmalloc.info,  Node: Overview,  Next: Implementation,  Prev: Top,  Up: Top
  48
  49 Overall Description
  50 *******************
  51
  52 This is a heavily modified version of GNU `malloc'.  It uses `mmap' as
  53 the basic mechanism for obtaining memory from the system, rather than
  54 `sbrk'.  This gives it several advantages over the more traditional
  55 malloc:
  56
  57    * Several different heaps can be used, each of them growing or
  58      shinking under control of `mmap', with the `mmalloc' functions
  59      using a specific heap on a call by call basis.
  60
  61    * By using `mmap', it is easy to create heaps which are intended to
  62      be persistent and exist as a filesystem object after the creating
  63      process has gone away.
  64
  65    * Because multiple heaps can be managed, data used for a specific
  66      purpose can be allocated into its own heap, making it easier to
  67      allow applications to "dump" and "restore" initialized
  68      malloc-managed memory regions.  For example, the "unexec" hack
  69      popularized by GNU Emacs could potentially go away.
  70
  71 \1f
  72 File: mmalloc.info,  Node: Implementation,  Prev: Overview,  Up: Top
  73
  74 Implementation
  75 **************
  76
  77 The `mmalloc' functions contain no internal static state.  All
  78 `mmalloc' internal data is allocated in the mapped in region, along
  79 with the user data that it manages.  This allows it to manage multiple
  80 such regions and to "pick up where it left off" when such regions are
  81 later dynamically mapped back in.
  82
  83    In some sense, malloc has been "purified" to contain no internal
  84 state information and generalized to use multiple memory regions rather
  85 than a single region managed by `sbrk'.  However the new routines now
  86 need an extra parameter which informs `mmalloc' which memory region it
  87 is dealing with (along with other information).  This parameter is
  88 called the "malloc descriptor".
  89
  90    The functions initially provided by `mmalloc' are:
  91
  92      void *mmalloc_attach (int fd, void *baseaddr);
  93      void *mmalloc_detach (void *md);
  94      int mmalloc_errno (void *md);
  95      int mmalloc_setkey (void *md, int keynum, void *key);
  96      void *mmalloc_getkey (void *md, int keynum);
  97
  98      void *mmalloc (void *md, size_t size);
  99      void *mrealloc (void *md, void *ptr, size_t size);
 100      void *mvalloc (void *md, size_t size);
 101      void mfree (void *md, void *ptr);
 102
 103 * Menu:
 104
 105 * Compatibility::               Backwards Compatibility
 106 * Functions::                   Function Descriptions
 107
 108 \1f
 109 File: mmalloc.info,  Node: Compatibility,  Next: Functions,  Prev: Implementation,  Up: Implementation
 110
 111 Backwards Compatibility
 112 =======================
 113
 114 To allow a single malloc package to be used in a given application,
 115 provision is made for the traditional `malloc', `realloc', and `free'
 116 functions to be implemented as special cases of the `mmalloc'
 117 functions.  In particular, if any of the functions that expect malloc
 118 descriptors are called with a `NULL' pointer rather than a valid malloc
 119 descriptor, then they default to using an `sbrk' managed region.  The
 120 `mmalloc' package provides compatible `malloc', `realloc', and `free'
 121 functions using this mechanism internally.  Applications can avoid this
 122 extra interface layer by simply including the following defines:
 123
 124      #define malloc(size)               mmalloc ((void *)0, (size))
 125      #define realloc(ptr,size)  mrealloc ((void *)0, (ptr), (size));
 126      #define free(ptr)          mfree ((void *)0, (ptr))
 127
 128 or replace the existing `malloc', `realloc', and `free' calls with the
 129 above patterns if using `#define' causes problems.
 130
 131 \1f
 132 File: mmalloc.info,  Node: Functions,  Prev: Compatibility,  Up: Implementation
 133
 134 Function Descriptions
 135 =====================
 136
 137 These are the details on the functions that make up the `mmalloc'
 138 package.
 139
 140 `void *mmalloc_attach (int FD, void *BASEADDR);'
 141      Initialize access to a `mmalloc' managed region.
 142
 143      If FD is a valid file descriptor for an open file, then data for
 144      the `mmalloc' managed region is mapped to that file.   Otherwise
 145      `/dev/zero' is used and the data will not exist in any filesystem
 146      object.
 147
 148      If the open file corresponding to FD is from a previous use of
 149      `mmalloc' and passes some basic sanity checks to ensure that it is
 150      compatible with the current `mmalloc' package, then its data is
 151      mapped in and is immediately accessible at the same addresses in
 152      the current process as the process that created the file.
 153
 154      If BASEADDR is not `NULL', the mapping is established starting at
 155      the specified address in the process address space.  If BASEADDR
 156      is `NULL', the `mmalloc' package chooses a suitable address at
 157      which to start the mapped region, which will be the value of the
 158      previous mapping if opening an existing file which was previously
 159      built by `mmalloc', or for new files will be a value chosen by
 160      `mmap'.
 161
 162      Specifying BASEADDR provides more control over where the regions
 163      start and how big they can be before bumping into existing mapped
 164      regions or future mapped regions.
 165
 166      On success, returns a malloc descriptor which is used in subsequent
 167      calls to other `mmalloc' package functions.  It is explicitly
 168      `void *' (`char *' for systems that don't fully support `void') so
 169      that users of the package don't have to worry about the actual
 170      implementation details.
 171
 172      On failure returns `NULL'.
 173
 174 `void *mmalloc_detach (void *MD);'
 175      Terminate access to a `mmalloc' managed region identified by the
 176      descriptor MD, by closing the base file and unmapping all memory
 177      pages associated with the region.
 178
 179      Returns `NULL' on success.
 180
 181      Returns the malloc descriptor on failure, which can subsequently
 182      be used for further action (such as obtaining more information
 183      about the nature of the failure).
 184
 185 `void *mmalloc (void *MD, size_t SIZE);'
 186      Given an `mmalloc' descriptor MD, allocate additional memory of
 187      SIZE bytes in the associated mapped region.
 188
 189 `*mrealloc (void *MD, void *PTR, size_t SIZE);'
 190      Given an `mmalloc' descriptor MD and a pointer to memory
 191      previously allocated by `mmalloc' in PTR, reallocate the memory to
 192      be SIZE bytes long, possibly moving the existing contents of
 193      memory if necessary.
 194
 195 `void *mvalloc (void *MD, size_t SIZE);'
 196      Like `mmalloc' but the resulting memory is aligned on a page
 197      boundary.
 198
 199 `void mfree (void *MD, void *PTR);'
 200      Given an `mmalloc' descriptor MD and a pointer to memory previously
 201      allocated by `mmalloc' in PTR, free the previously allocated
 202      memory.
 203
 204 `int mmalloc_errno (void *MD);'
 205      Given a `mmalloc' descriptor, if the last `mmalloc' operation
 206      failed for some reason due to a system call failure, then returns
 207      the associated `errno'.  Returns 0 otherwise.  (This function is
 208      not yet implemented).
 209
 210
 211 \1f
 212 Tag Table:
 213 Node: Top\7f937
 214 Node: Overview\7f1370
 215 Node: Implementation\7f2395
 216 Node: Compatibility\7f3785
 217 Node: Functions\7f4856
 218 \1f
 219 End Tag Table