src/xbt/mmalloc/mmalloc.texi

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