| 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 |