Converted from Fred's original README; no changes in substance.
This commit is contained in:
Roland Pesch
parent
e05ba37d1f
commit
d203e17273
1 changed files with 272 additions and 0 deletions
272
mmalloc/mmalloc.texi
Normal file
272
mmalloc/mmalloc.texi
Normal file
|
|
@ -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
|
||||
Loading…
Reference in a new issue