1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
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
|
