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