diff options
Diffstat (limited to 'mmalloc/mmalloc.texi')
| -rw-r--r-- | mmalloc/mmalloc.texi | 272 |
1 files changed, 0 insertions, 272 deletions
diff --git a/mmalloc/mmalloc.texi b/mmalloc/mmalloc.texi deleted file mode 100644 index 6de4944c547..00000000000 --- a/mmalloc/mmalloc.texi +++ /dev/null @@ -1,272 +0,0 @@ -\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 |