diff options
| -rw-r--r-- | mmalloc/mmalloc.texi | 272 |
1 files changed, 272 insertions, 0 deletions
diff --git a/mmalloc/mmalloc.texi b/mmalloc/mmalloc.texi new file mode 100644 index 0000000..6de4944 --- /dev/null +++ b/mmalloc/mmalloc.texi @@ -0,0 +1,272 @@ +\input texinfo @c -*- Texinfo -*- +@setfilename mmalloc.info + +@ifinfo +@format +START-INFO-DIR-ENTRY +* Mmalloc: (mmalloc). The GNU mapped-malloc package. +END-INFO-DIR-ENTRY +@end format + +This file documents the GNU mmalloc (mapped-malloc) package, written by +fnf@@cygnus.com. + +Copyright (C) 1992 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ifinfo +@iftex +@c @finalout +@setchapternewpage odd +@settitle MMALLOC, the GNU memory-mapped malloc package +@titlepage +@title mmalloc +@subtitle The GNU memory-mapped malloc package +@author Fred Fish +@author Cygnus Support +@page + +@tex +\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ +\xdef\manvers{\$Revision$} % For use in headers, footers too +{\parskip=0pt +\hfill Cygnus Support\par +\hfill fnf\@cygnus.com\par +\hfill {\it MMALLOC, the GNU memory-mapped malloc package}, \manvers\par +\hfill \TeX{}info \texinfoversion\par +} +@end tex + +@vskip 0pt plus 1filll +Copyright @copyright{} 1992 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end titlepage +@end iftex + +@ifinfo +@node Top, Overview, (dir), (dir) +@top mmalloc +This file documents the GNU memory-mapped malloc package mmalloc. + +@menu +* Overview:: Overall Description +* Implementation:: Implementation + + --- The Detailed Node Listing --- + +Implementation + +* Compatibility:: Backwards Compatibility +* Functions:: Function Descriptions +@end menu + +@end ifinfo + +@node Overview, Implementation, Top, Top +@chapter Overall Description + +This is a heavily modified version of GNU @code{malloc}. It uses +@code{mmap} as the basic mechanism for for obtaining memory from the +system, rather than @code{sbrk}. This gives it several advantages over the +more traditional malloc: + +@itemize @bullet +@item +Providing suitable precautions are taken to avoid memory region +collisions, @code{sbrk} is now available for use by applications that +use this package and still need to use some memory management +package that includes functions like @code{malloc}, @code{realloc}, and +@code{free}. + +@item +Several different memory pools can be used, each of them growing +or shinking under control of @code{mmap}, with the @code{mmalloc} functions +using a specific pool on a call by call basis. + +@item +By using @code{mmap}, it is easy to create data pools which are intended to +be persistent and exist as a filesystem object after the creating +process has gone away. + +@item +Because multiple memory pools can be managed, data used for a +specific purpose can be allocated into its own memory pool, making +it easier to allow applications to ``dump'' and ``restore'' initialized +malloc-managed memory regions. For example, the ``unexec'' hack popularized +by GNU Emacs could potentially go away. +@end itemize + +@node Implementation, , Overview, Top +@chapter Implementation + +The @code{mmalloc} functions contain no internal static state. All +@code{mmalloc} internal data is allocated in the mapped in region, along +with the user data that it manages. This allows it to manage multiple +such regions and to ``pick up where it left off'' when such regions are +later dynamically mapped back in. + +In some sense, malloc has been ``purified'' to contain no internal state +information and generalized to use multiple memory regions rather than a +single region managed by @code{sbrk}. However the new routines now need an +extra parameter which informs @code{mmalloc} which memory region it is dealing +with (along with other information). This parameter is called the +@dfn{malloc descriptor}. + +For ease of initial implementation, and to avoid exporting or importing +any more global variables or routines than necessary, this package is +implemented with all functions contained within a single source file. +At some future point, once everything has stabilized, it may be desirable +to split it up into separate files. + +The functions initially provided by @code{mmalloc} are: + +@example +void *mmalloc_attach (int fd, void *baseaddr); +void *mmalloc_detach (void *md); +int mmalloc_errno (void *md); +int mmalloc_setkey (void *md, int keynum, void *key); +void *mmalloc_getkey (void *md, int keynum); + +void *mmalloc (void *md, size_t size); +void *mrealloc (void *md, void *ptr, size_t size); +void *mvalloc (void *md, size_t size); +void mfree (void *md, void *ptr); +@end example + +@menu +* Compatibility:: Backwards Compatibility +* Functions:: Function Descriptions +@end menu + +@node Compatibility, Functions, Implementation, Implementation +@section Backwards Compatibility + +To allow a single malloc package to be used in a given application, +provision is made for the traditional @code{malloc}, @code{realloc}, and +@code{free} functions to be implemented as special cases of the +@code{mmalloc} functions. In particular, if any of the functions that +expect malloc descriptors are called with a @code{NULL} pointer rather than a +valid malloc descriptor, then they default to using a memory-mapped region +starting at the current @code{sbrk} value and mapped to @file{/dev/zero}. +Applications can simply include the following defines to use the +@code{mmalloc} versions: + +@example +#define malloc(size) mmalloc ((void *)0, (size)) +#define realloc(ptr,size) mrealloc ((void *)0, (ptr), (size)); +#define free(ptr) mfree ((void *)0, (ptr)) +@end example + +@noindent +or replace the existing @code{malloc}, @code{realloc}, and @code{free} +calls with the above patterns if using @code{#define} causes problems. + +Note that this does not prevent calls to @code{malloc}, @code{realloc}, +or @code{free} within libraries from continuing to use the library +version of malloc, so if this is a problem, the compatibility issue +needs to be dealt with in another way. + + +@node Functions, , Compatibility, Implementation +@section Function Descriptions + +These are the details on the functions that make up the @code{mmalloc} +package. + +@table @code +@item void *mmalloc_attach (int @var{fd}, void *@var{baseaddr}); +Initialize access to a @code{mmalloc} managed region. + +If @var{fd} is a valid file descriptor for an open file, then data for the +@code{mmalloc} managed region is mapped to that file. Otherwise +@file{/dev/zero} is used and the data will not exist in any filesystem object. + +If the open file corresponding to @var{fd} is from a previous use of +@code{mmalloc} and passes some basic sanity checks to ensure that it is +compatible with the current @code{mmalloc} package, then its data is +mapped in and is immediately accessible at the same addresses in +the current process as the process that created the file. + +If @var{baseaddr} is not @code{NULL}, the mapping is established +starting at the specified address in the process address space. If +@var{baseaddr} is @code{NULL}, the @code{mmalloc} package chooses a +suitable address at which to start the mapped region, which will be the +value of the previous mapping if opening an existing file which was +previously built by @code{mmalloc}, or for new files will be a value +chosen by @code{mmap}. + +Specifying @var{baseaddr} provides more control over where the regions +start and how big they can be before bumping into existing mapped +regions or future mapped regions. + +On success, returns a malloc descriptor which is used in subsequent +calls to other @code{mmalloc} package functions. It is explicitly +@samp{void *} (@samp{char *} for systems that don't fully support +@code{void}) so that users of the package don't have to worry about the +actual implementation details. + +On failure returns @code{NULL}. + +@item void *mmalloc_detach (void *@var{md}); +Terminate access to a @code{mmalloc} managed region identified by the +descriptor @var{md}, by closing the base file and unmapping all memory +pages associated with the region. + +Returns @code{NULL} on success. + +Returns the malloc descriptor on failure, which can subsequently +be used for further action (such as obtaining more information about +the nature of the failure). + +@item void *mmalloc (void *@var{md}, size_t @var{size}); +Given an @code{mmalloc} descriptor @var{md}, allocate additional memory of +@var{size} bytes in the associated mapped region. + +@item *mrealloc (void *@var{md}, void *@var{ptr}, size_t @var{size}); +Given an @code{mmalloc} descriptor @var{md} and a pointer to memory +previously allocated by @code{mmalloc} in @var{ptr}, reallocate the +memory to be @var{size} bytes long, possibly moving the existing +contents of memory if necessary. + +@item void *mvalloc (void *@var{md}, size_t @var{size}); +Like @code{mmalloc} but the resulting memory is aligned on a page boundary. + +@item void mfree (void *@var{md}, void *@var{ptr}); +Given an @code{mmalloc} descriptor @var{md} and a pointer to memory previously +allocated by @code{mmalloc} in @var{ptr}, free the previously allocated memory. + +@item int mmalloc_errno (void *@var{md}); +Given a @code{mmalloc} descriptor, if the last @code{mmalloc} operation +failed for some reason due to a system call failure, then +returns the associated @code{errno}. Returns 0 otherwise. +@end table + +@bye |