259 lines
9.5 KiB
Plaintext
259 lines
9.5 KiB
Plaintext
\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
|