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