diff options
Diffstat (limited to 'mmalloc')
| -rw-r--r-- | mmalloc/mmalloc.info | 219 |
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 |