aboutsummaryrefslogtreecommitdiff
path: root/mmalloc
diff options
context:
space:
mode:
Diffstat (limited to 'mmalloc')
-rw-r--r--mmalloc/mmalloc.info219
1 files changed, 219 insertions, 0 deletions
diff --git a/mmalloc/mmalloc.info b/mmalloc/mmalloc.info
new file mode 100644
index 0000000..5c8b54a
--- /dev/null
+++ b/mmalloc/mmalloc.info
@@ -0,0 +1,219 @@
+This is Info file ./mmalloc.info, produced by Makeinfo version 1.68
+from the input file mmalloc.texi.
+
+START-INFO-DIR-ENTRY
+* Mmalloc: (mmalloc). The GNU mapped-malloc package.
+END-INFO-DIR-ENTRY
+
+ 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.
+
+ 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.
+
+
+File: mmalloc.info, Node: Top, Next: Overview, Prev: (dir), Up: (dir)
+
+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
+
+
+File: mmalloc.info, Node: Overview, Next: Implementation, Prev: Top, Up: Top
+
+Overall Description
+*******************
+
+ This is a heavily modified version of GNU `malloc'. It uses `mmap'
+as the basic mechanism for obtaining memory from the system, rather
+than `sbrk'. This gives it several advantages over the more
+traditional malloc:
+
+ * Several different heaps can be used, each of them growing or
+ shinking under control of `mmap', with the `mmalloc' functions
+ using a specific heap on a call by call basis.
+
+ * By using `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.
+
+ * 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.
+
+
+File: mmalloc.info, Node: Implementation, Prev: Overview, Up: Top
+
+Implementation
+**************
+
+ The `mmalloc' functions contain no internal static state. All
+`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 `sbrk'. However the new routines now
+need an extra parameter which informs `mmalloc' which memory region it
+is dealing with (along with other information). This parameter is
+called the "malloc descriptor".
+
+ The functions initially provided by `mmalloc' are:
+
+ 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);
+
+* Menu:
+
+* Compatibility:: Backwards Compatibility
+* Functions:: Function Descriptions
+
+
+File: mmalloc.info, Node: Compatibility, Next: Functions, Prev: Implementation, Up: Implementation
+
+Backwards Compatibility
+=======================
+
+ To allow a single malloc package to be used in a given application,
+provision is made for the traditional `malloc', `realloc', and `free'
+functions to be implemented as special cases of the `mmalloc'
+functions. In particular, if any of the functions that expect malloc
+descriptors are called with a `NULL' pointer rather than a valid malloc
+descriptor, then they default to using an `sbrk' managed region. The
+`mmalloc' package provides compatible `malloc', `realloc', and `free'
+functions using this mechanism internally. Applications can avoid this
+extra interface layer by simply including the following defines:
+
+ #define malloc(size) mmalloc ((void *)0, (size))
+ #define realloc(ptr,size) mrealloc ((void *)0, (ptr), (size));
+ #define free(ptr) mfree ((void *)0, (ptr))
+
+or replace the existing `malloc', `realloc', and `free' calls with the
+above patterns if using `#define' causes problems.
+
+
+File: mmalloc.info, Node: Functions, Prev: Compatibility, Up: Implementation
+
+Function Descriptions
+=====================
+
+ These are the details on the functions that make up the `mmalloc'
+package.
+
+`void *mmalloc_attach (int FD, void *BASEADDR);'
+ Initialize access to a `mmalloc' managed region.
+
+ If FD is a valid file descriptor for an open file, then data for
+ the `mmalloc' managed region is mapped to that file. Otherwise
+ `/dev/zero' is used and the data will not exist in any filesystem
+ object.
+
+ If the open file corresponding to FD is from a previous use of
+ `mmalloc' and passes some basic sanity checks to ensure that it is
+ compatible with the current `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 BASEADDR is not `NULL', the mapping is established starting at
+ the specified address in the process address space. If BASEADDR
+ is `NULL', the `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 `mmalloc', or for new files will be a value chosen by
+ `mmap'.
+
+ Specifying 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 `mmalloc' package functions. It is explicitly
+ `void *' (`char *' for systems that don't fully support `void') so
+ that users of the package don't have to worry about the actual
+ implementation details.
+
+ On failure returns `NULL'.
+
+`void *mmalloc_detach (void *MD);'
+ Terminate access to a `mmalloc' managed region identified by the
+ descriptor MD, by closing the base file and unmapping all memory
+ pages associated with the region.
+
+ Returns `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).
+
+`void *mmalloc (void *MD, size_t SIZE);'
+ Given an `mmalloc' descriptor MD, allocate additional memory of
+ SIZE bytes in the associated mapped region.
+
+`*mrealloc (void *MD, void *PTR, size_t SIZE);'
+ Given an `mmalloc' descriptor MD and a pointer to memory
+ previously allocated by `mmalloc' in PTR, reallocate the memory to
+ be SIZE bytes long, possibly moving the existing contents of
+ memory if necessary.
+
+`void *mvalloc (void *MD, size_t SIZE);'
+ Like `mmalloc' but the resulting memory is aligned on a page
+ boundary.
+
+`void mfree (void *MD, void *PTR);'
+ Given an `mmalloc' descriptor MD and a pointer to memory previously
+ allocated by `mmalloc' in PTR, free the previously allocated
+ memory.
+
+`int mmalloc_errno (void *MD);'
+ Given a `mmalloc' descriptor, if the last `mmalloc' operation
+ failed for some reason due to a system call failure, then returns
+ the associated `errno'. Returns 0 otherwise. (This function is
+ not yet implemented).
+
+
+
+Tag Table:
+Node: Top963
+Node: Overview1397
+Node: Implementation2425
+Node: Compatibility3818
+Node: Functions4892
+
+End Tag Table