| \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, based on GNU malloc written by mike@@ai.mit.edu. |
| |
| 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 |
| @author Mike Haertel |
| @author Free Software Foundation |
| @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 obtaining memory from the |
| system, rather than @code{sbrk}. This gives it several advantages over the |
| more traditional malloc: |
| |
| @itemize @bullet |
| @item |
| Several different heaps can be used, each of them growing |
| or shinking under control of @code{mmap}, with the @code{mmalloc} functions |
| using a specific heap on a call by call basis. |
| |
| @item |
| By using @code{mmap}, it is easy to create heaps which are intended to |
| be persistent and exist as a filesystem object after the creating |
| process has gone away. |
| |
| @item |
| Because multiple heaps can be managed, data used for a |
| specific purpose can be allocated into its own heap, 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}. |
| |
| 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 an @code{sbrk} managed |
| region. |
| The @code{mmalloc} package provides compatible @code{malloc}, @code{realloc}, |
| and @code{free} functions using this mechanism internally. |
| Applications can avoid this extra interface layer by simply including the |
| following defines: |
| |
| @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. |
| |
| @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. |
| (This function is not yet implemented). |
| @end table |
| |
| @bye |