Commit | Line | Data |
---|---|---|
c906108c SS |
1 | \input texinfo @c -*- Texinfo -*- |
2 | @setfilename mmalloc.info | |
3 | ||
4 | @ifinfo | |
5 | @format | |
6 | START-INFO-DIR-ENTRY | |
7 | * Mmalloc: (mmalloc). The GNU mapped-malloc package. | |
8 | END-INFO-DIR-ENTRY | |
9 | @end format | |
10 | ||
11 | This file documents the GNU mmalloc (mapped-malloc) package, written by | |
12 | fnf@@cygnus.com, based on GNU malloc written by mike@@ai.mit.edu. | |
13 | ||
14 | Copyright (C) 1992 Free Software Foundation, Inc. | |
15 | ||
16 | Permission is granted to make and distribute verbatim copies of | |
17 | this manual provided the copyright notice and this permission notice | |
18 | are preserved on all copies. | |
19 | ||
20 | @ignore | |
21 | Permission is granted to process this file through Tex and print the | |
22 | results, provided the printed document carries copying permission | |
23 | notice identical to this one except for the removal of this paragraph | |
24 | (this paragraph not being relevant to the printed manual). | |
25 | ||
26 | @end ignore | |
27 | Permission is granted to copy and distribute modified versions of this | |
28 | manual under the conditions for verbatim copying, provided also that the | |
29 | entire resulting derived work is distributed under the terms of a | |
30 | permission notice identical to this one. | |
31 | ||
32 | Permission is granted to copy and distribute translations of this manual | |
33 | into another language, under the above conditions for modified versions. | |
34 | @end ifinfo | |
35 | @iftex | |
36 | @c @finalout | |
37 | @setchapternewpage odd | |
38 | @settitle MMALLOC, the GNU memory-mapped malloc package | |
39 | @titlepage | |
40 | @title mmalloc | |
41 | @subtitle The GNU memory-mapped malloc package | |
42 | @author Fred Fish | |
43 | @author Cygnus Support | |
44 | @author Mike Haertel | |
45 | @author Free Software Foundation | |
46 | @page | |
47 | ||
48 | @tex | |
49 | \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ | |
50 | \xdef\manvers{\$Revision$} % For use in headers, footers too | |
51 | {\parskip=0pt | |
52 | \hfill Cygnus Support\par | |
53 | \hfill fnf\@cygnus.com\par | |
54 | \hfill {\it MMALLOC, the GNU memory-mapped malloc package}, \manvers\par | |
55 | \hfill \TeX{}info \texinfoversion\par | |
56 | } | |
57 | @end tex | |
58 | ||
59 | @vskip 0pt plus 1filll | |
60 | Copyright @copyright{} 1992 Free Software Foundation, Inc. | |
61 | ||
62 | Permission is granted to make and distribute verbatim copies of | |
63 | this manual provided the copyright notice and this permission notice | |
64 | are preserved on all copies. | |
65 | ||
66 | Permission is granted to copy and distribute modified versions of this | |
67 | manual under the conditions for verbatim copying, provided also that | |
68 | the entire resulting derived work is distributed under the terms of a | |
69 | permission notice identical to this one. | |
70 | ||
71 | Permission is granted to copy and distribute translations of this manual | |
72 | into another language, under the above conditions for modified versions. | |
73 | @end titlepage | |
74 | @end iftex | |
75 | ||
76 | @ifinfo | |
77 | @node Top, Overview, (dir), (dir) | |
78 | @top mmalloc | |
79 | This file documents the GNU memory-mapped malloc package mmalloc. | |
80 | ||
81 | @menu | |
82 | * Overview:: Overall Description | |
83 | * Implementation:: Implementation | |
84 | ||
85 | --- The Detailed Node Listing --- | |
86 | ||
87 | Implementation | |
88 | ||
89 | * Compatibility:: Backwards Compatibility | |
90 | * Functions:: Function Descriptions | |
91 | @end menu | |
92 | ||
93 | @end ifinfo | |
94 | ||
95 | @node Overview, Implementation, Top, Top | |
96 | @chapter Overall Description | |
97 | ||
98 | This is a heavily modified version of GNU @code{malloc}. It uses | |
99 | @code{mmap} as the basic mechanism for obtaining memory from the | |
100 | system, rather than @code{sbrk}. This gives it several advantages over the | |
101 | more traditional malloc: | |
102 | ||
103 | @itemize @bullet | |
104 | @item | |
105 | Several different heaps can be used, each of them growing | |
106 | or shinking under control of @code{mmap}, with the @code{mmalloc} functions | |
107 | using a specific heap on a call by call basis. | |
108 | ||
109 | @item | |
110 | By using @code{mmap}, it is easy to create heaps which are intended to | |
111 | be persistent and exist as a filesystem object after the creating | |
112 | process has gone away. | |
113 | ||
114 | @item | |
115 | Because multiple heaps can be managed, data used for a | |
116 | specific purpose can be allocated into its own heap, making | |
117 | it easier to allow applications to ``dump'' and ``restore'' initialized | |
118 | malloc-managed memory regions. For example, the ``unexec'' hack popularized | |
119 | by GNU Emacs could potentially go away. | |
120 | @end itemize | |
121 | ||
122 | @node Implementation, , Overview, Top | |
123 | @chapter Implementation | |
124 | ||
125 | The @code{mmalloc} functions contain no internal static state. All | |
126 | @code{mmalloc} internal data is allocated in the mapped in region, along | |
127 | with the user data that it manages. This allows it to manage multiple | |
128 | such regions and to ``pick up where it left off'' when such regions are | |
129 | later dynamically mapped back in. | |
130 | ||
131 | In some sense, malloc has been ``purified'' to contain no internal state | |
132 | information and generalized to use multiple memory regions rather than a | |
133 | single region managed by @code{sbrk}. However the new routines now need an | |
134 | extra parameter which informs @code{mmalloc} which memory region it is dealing | |
135 | with (along with other information). This parameter is called the | |
136 | @dfn{malloc descriptor}. | |
137 | ||
138 | The functions initially provided by @code{mmalloc} are: | |
139 | ||
140 | @example | |
141 | void *mmalloc_attach (int fd, void *baseaddr); | |
142 | void *mmalloc_detach (void *md); | |
143 | int mmalloc_errno (void *md); | |
144 | int mmalloc_setkey (void *md, int keynum, void *key); | |
145 | void *mmalloc_getkey (void *md, int keynum); | |
146 | ||
147 | void *mmalloc (void *md, size_t size); | |
148 | void *mrealloc (void *md, void *ptr, size_t size); | |
149 | void *mvalloc (void *md, size_t size); | |
150 | void mfree (void *md, void *ptr); | |
151 | @end example | |
152 | ||
153 | @menu | |
154 | * Compatibility:: Backwards Compatibility | |
155 | * Functions:: Function Descriptions | |
156 | @end menu | |
157 | ||
158 | @node Compatibility, Functions, Implementation, Implementation | |
159 | @section Backwards Compatibility | |
160 | ||
161 | To allow a single malloc package to be used in a given application, | |
162 | provision is made for the traditional @code{malloc}, @code{realloc}, and | |
163 | @code{free} functions to be implemented as special cases of the | |
164 | @code{mmalloc} functions. In particular, if any of the functions that | |
165 | expect malloc descriptors are called with a @code{NULL} pointer rather than a | |
166 | valid malloc descriptor, then they default to using an @code{sbrk} managed | |
167 | region. | |
168 | The @code{mmalloc} package provides compatible @code{malloc}, @code{realloc}, | |
169 | and @code{free} functions using this mechanism internally. | |
170 | Applications can avoid this extra interface layer by simply including the | |
171 | following defines: | |
172 | ||
173 | @example | |
174 | #define malloc(size) mmalloc ((void *)0, (size)) | |
175 | #define realloc(ptr,size) mrealloc ((void *)0, (ptr), (size)); | |
176 | #define free(ptr) mfree ((void *)0, (ptr)) | |
177 | @end example | |
178 | ||
179 | @noindent | |
180 | or replace the existing @code{malloc}, @code{realloc}, and @code{free} | |
181 | calls with the above patterns if using @code{#define} causes problems. | |
182 | ||
183 | @node Functions, , Compatibility, Implementation | |
184 | @section Function Descriptions | |
185 | ||
186 | These are the details on the functions that make up the @code{mmalloc} | |
187 | package. | |
188 | ||
189 | @table @code | |
190 | @item void *mmalloc_attach (int @var{fd}, void *@var{baseaddr}); | |
191 | Initialize access to a @code{mmalloc} managed region. | |
192 | ||
193 | If @var{fd} is a valid file descriptor for an open file, then data for the | |
194 | @code{mmalloc} managed region is mapped to that file. Otherwise | |
195 | @file{/dev/zero} is used and the data will not exist in any filesystem object. | |
196 | ||
197 | If the open file corresponding to @var{fd} is from a previous use of | |
198 | @code{mmalloc} and passes some basic sanity checks to ensure that it is | |
199 | compatible with the current @code{mmalloc} package, then its data is | |
200 | mapped in and is immediately accessible at the same addresses in | |
201 | the current process as the process that created the file. | |
202 | ||
203 | If @var{baseaddr} is not @code{NULL}, the mapping is established | |
204 | starting at the specified address in the process address space. If | |
205 | @var{baseaddr} is @code{NULL}, the @code{mmalloc} package chooses a | |
206 | suitable address at which to start the mapped region, which will be the | |
207 | value of the previous mapping if opening an existing file which was | |
208 | previously built by @code{mmalloc}, or for new files will be a value | |
209 | chosen by @code{mmap}. | |
210 | ||
211 | Specifying @var{baseaddr} provides more control over where the regions | |
212 | start and how big they can be before bumping into existing mapped | |
213 | regions or future mapped regions. | |
214 | ||
215 | On success, returns a malloc descriptor which is used in subsequent | |
216 | calls to other @code{mmalloc} package functions. It is explicitly | |
217 | @samp{void *} (@samp{char *} for systems that don't fully support | |
218 | @code{void}) so that users of the package don't have to worry about the | |
219 | actual implementation details. | |
220 | ||
221 | On failure returns @code{NULL}. | |
222 | ||
223 | @item void *mmalloc_detach (void *@var{md}); | |
224 | Terminate access to a @code{mmalloc} managed region identified by the | |
225 | descriptor @var{md}, by closing the base file and unmapping all memory | |
226 | pages associated with the region. | |
227 | ||
228 | Returns @code{NULL} on success. | |
229 | ||
230 | Returns the malloc descriptor on failure, which can subsequently | |
231 | be used for further action (such as obtaining more information about | |
232 | the nature of the failure). | |
233 | ||
234 | @item void *mmalloc (void *@var{md}, size_t @var{size}); | |
235 | Given an @code{mmalloc} descriptor @var{md}, allocate additional memory of | |
236 | @var{size} bytes in the associated mapped region. | |
237 | ||
238 | @item *mrealloc (void *@var{md}, void *@var{ptr}, size_t @var{size}); | |
239 | Given an @code{mmalloc} descriptor @var{md} and a pointer to memory | |
240 | previously allocated by @code{mmalloc} in @var{ptr}, reallocate the | |
241 | memory to be @var{size} bytes long, possibly moving the existing | |
242 | contents of memory if necessary. | |
243 | ||
244 | @item void *mvalloc (void *@var{md}, size_t @var{size}); | |
245 | Like @code{mmalloc} but the resulting memory is aligned on a page boundary. | |
246 | ||
247 | @item void mfree (void *@var{md}, void *@var{ptr}); | |
248 | Given an @code{mmalloc} descriptor @var{md} and a pointer to memory previously | |
249 | allocated by @code{mmalloc} in @var{ptr}, free the previously allocated memory. | |
250 | ||
251 | @item int mmalloc_errno (void *@var{md}); | |
252 | Given a @code{mmalloc} descriptor, if the last @code{mmalloc} operation | |
253 | failed for some reason due to a system call failure, then | |
254 | returns the associated @code{errno}. Returns 0 otherwise. | |
255 | (This function is not yet implemented). | |
256 | @end table | |
257 | ||
258 | @bye |