| blob | b29079bb98eca6920f74546fd1e5a6b2d5200a4e |
1 .\" Id: memcluster.mdoc,v 1.3 2004/03/09 06:30:08 marka Exp
2 .\"
3 .\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
4 .\" Copyright (c) 1995-1999 by Internet Software Consortium
5 .\"
6 .\" Permission to use, copy, modify, and distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
9 .\"
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR
13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
16 .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 .\"
18 .\" The following six UNCOMMENTED lines are required.
19 .Dd Month day, year
20 .\"Os OPERATING_SYSTEM [version/release]
21 .Os BSD 4
22 .\"Dt DOCUMENT_TITLE [section number] [volume]
23 .Dt MEMCLUSTER 3
24 .Sh NAME
25 .Nm meminit ,
26 .Nm memget ,
27 .Nm memput ,
28 .Nm memstats
29 .Nd memory allocation/deallocation system
30 .Sh SYNOPSIS
31 .Fd #include \&<isc/memcluster.h\&>
32 .Ft void *
33 .Fn memget "size_t size"
34 .Ft void
35 .Fn memput "void *mem" "size_t size"
36 .Ft void
37 .Fn memstats "FILE *out"
38 .Sh DESCRIPTION
39 These functions access a memory management system which allows callers to not
40 fragment memory to the extent which can ordinarily occur through many random
41 calls to
42 .Xr malloc 3 .
43 Instead,
44 .Fn memget
45 gets a large contiguous chunk of blocks of the requested
46 .Fa size
47 and parcels out these blocks as requested. The symmetric call is
48 .Fn memput ,
49 which callers use to return a piece of memory obtained from
50 .Fn memget .
51 Statistics about memory usage are returned by
52 .Fn memstats ,
53 which prints a report on the stream
54 .Fa out .
55 .Ss INTERNALS
56 Internally, linked lists of free memory blocks are stored in an array.
57 The size of this array is determined by the value
58 .Dv MEM_FREECOUNT ,
59 currently set to 1100. In general, for any requested blocksize
60 .Dq Fa size ,
61 any free blocks will be stored on the linked list at that index.
62 No free lists are managed for blocks greater than or equal to
63 .Dv MEM_FREECOUNT
64 bytes; instead, calls to
65 .Xr malloc 3
66 or
67 .Xr free 3
68 are made, directly.
69 .Pp
70 Since the blocks are actually stored as linked lists, they must at least
71 be large enough to hold a pointer to the next block. This size, which is
72 .Dv SMALL_SIZE_LIMIT ,
73 is currently defined as
74 .Bd -literal -offset indent
75 #define SMALL_SIZE_LIMIT sizeof(struct { void *next; })
76 .Ed
77 .Pp
78 Both
79 .Fn memget
80 and
81 .Fn memput
82 enforce this limit; for example, any call to
83 .Fn memget
84 requesting a block smaller than
85 .Dv SMALL_SIZE_LIMIT
86 bytes will actually be considered to be of size
87 .Dv SMALL_SIZE_LIMIT
88 internally. (Such a caller request will be logged for
89 .Fn memstats
90 purposes using the caller-requested
91 .Fa size ;
92 see the discussion of
93 .Fn memstats ,
94 below, for more information.)
95 .Pp
96 Additionally, the requested
97 .Fa size
98 will be adjusted so that when a large
99 .Xr malloc 3 Ns No -d
100 chunk of memory is broken up into a linked list, the blocks will all fall on
101 the correct memory alignment boundaries. Thus, one can conceptualize a call
102 which mentions
103 .Fa size
104 as resulting in a
105 .Fa new_size
106 which is used internally.
107 .Pp
108 In order to more efficiently allocate memory, there is a
109 .Dq target
110 size for calls to
111 .Xr malloc 3 .
112 It is given by the pre-defined value
113 .Dv MEM_TARGET ,
114 which is currently 4096 bytes.
115 For any requested block
116 .Fa size ,
117 enough memory is
118 .Xr malloc 3 Ns No -d
119 in order to fill up a block of about
120 .Dv MEM_TARGET
121 bytes.
122 .No [ Ns Sy NOTE :
123 For allocations larger than
124 .Dv MEM_TARGET Ns No /2
125 bytes, there is a
126 .Dq fudge factor
127 introduced which boosts the target size by 25% of
128 .Dv MEM_TARGET .
129 This means that enough memory for two blocks
130 will actually be allocated for any
131 .Fa size
132 such that
133 .Pq Dv MEM_TARGET Ns No / 3
134 .No < Fa size No <
135 .Pq Dv MEM_TARGET Ns No *5/8 ,
136 provided that the value of
137 .Dv MEM_FREECOUNT
138 is at least as large as the upper limit shown above.]
139 .Pp
140 .Ss FUNCTION DESCRIPTIONS
141 .Pp
142 The function
143 .Fn memget
144 returns a pointer to a block of memory of at least the requested
145 .Fa size .
146 After adjusting
147 .Fa size
148 to the value
149 .Va new_size
150 as mentioned above in the
151 .Sx INTERNALS
152 subsection, the internal array of free lists is checked.
153 If there is no block of the needed
154 .Va new_size ,
155 then
156 .Fn memget
157 will
158 .Xr malloc 3
159 a chunk of memory which is as many times as
160 .Va new_size
161 will fit into the target size. This memory is then turned into a linked list
162 of
163 .Va new_size Ns No -sized
164 blocks which are given out as requested; the last such block is the first one
165 returned by
166 .Fn memget .
167 If the requested
168 .Fa size
169 is zero or negative, then
170 .Dv NULL
171 is returned and
172 .Va errno
173 is set to
174 .Dv EINVAL ;
175 if
176 .Fa size
177 is larger than or equal to the pre-defined maximum size
178 .Dv MEM_FREECOUNT ,
179 then only a single block of exactly
180 .Fa size
181 will be
182 .Xr malloc 3 Ns No -d
183 and returned.
184 .Pp
185 The
186 .Fn memput
187 call is used to return memory once the caller is finished with it.
188 After adjusting
189 .Fa size
190 the the value
191 .Va new_size
192 as mentioned in the
193 .Sx INTERNALS
194 subsection, above, the block is placed at the head of the free list of
195 .Va new_size Ns -sized
196 blocks.
197 If the given
198 .Fa size
199 is zero or negative, then
200 .Va errno
201 is set to
202 .Dv EINVAL ,
203 as for
204 .Fn memget .
205 If
206 .Fa size
207 is larger than or equal to the pre-defined maximum size
208 .Dv MEM_FREECOUNT ,
209 then the block is immediately
210 .Xr free 3 Ns No -d .
211 .Pp
212 .Sy NOTE :
213 It is important that callers give
214 .Fn memput
215 .Em only
216 blocks of memory which were previously obtained from
217 .Fn memget
218 if the block is
219 .Em actually
220 less than
221 .Dv SMALL_SIZE_LIMIT
222 bytes in size. Since all blocks will be added to a free list, any block
223 which is not at least
224 .Dv SMALL_SIZE_LIMIT
225 bytes long will not be able to hold a pointer to the next block in the
226 free list.
227 .Pp
228 The
229 .Fn memstats
230 function will summarize the number of calls to
231 .Fn memget
232 and
233 .Fn memput
234 for any block size from 1 byte up to
235 .Pq Dv MEM_FREECOUNT No - 1
236 bytes, followed by a single line for any calls using a
237 .Fa size
238 greater than or equal to
239 .Dv MEM_FREECOUNT ;
240 a brief header with shell-style comment lines prefaces the report and
241 explains the information. The
242 .Dv FILE
243 pointer
244 .Fa out
245 identifies the stream which is used for this report. Currently,
246 .Fn memstat
247 reports the number of calls to
248 .Fn memget
249 and
250 .Fn memput
251 using the caller-supplied value
252 .Fa size ;
253 the percentage of outstanding blocks of a given size (i.e., the percentage
254 by which calls to
255 .Fn memget
256 exceed
257 .Fn memput )
258 are also reported on the line for blocks of the given
259 .Fa size .
260 However, the percent of blocks used is computed using the number of
261 blocks allocated according to the internal parameter
262 .Va new_size ;
263 it is the percentage of blocks used to those available at a given
264 .Va new_size ,
265 and is computed using the
266 .Em total
267 number of caller
268 .Dq gets
269 for any caller
270 .Fa size Ns No -s
271 which map to the internally-computed
272 .Va new_size .
273 Keep in mind that
274 .Va new_size
275 is generally
276 .Em not
277 equal to
278 .Fa size ,
279 which has these implications:
280 .Bl -enum -offset indent
281 .It
282 For
283 .Fa size
284 smaller than
285 .Dv SMALL_SIZE_LIMIT ,
286 .Fn memstat
287 .Em will
288 show statistics for caller requests under
289 .Fa size ,
290 but "percent used" information about such blocks will be reported under
291 .Dv SMALL_SIZE_LIMIT Ns No -sized
292 blocks.
293 .It
294 As a general case of point 1, internal statistics are reported on the the
295 line corresponding to
296 .Va new_size ,
297 so that, for a given caller-supplied
298 .Fa size ,
299 the associated internal information will appear on that line or on the next
300 line which shows "percent used" information.
301 .El
302 .Pp
303 .Sy NOTE :
304 If the caller returns blocks of a given
305 .Fa size
306 and requests others of
307 .Fa size Ns No -s
308 which map to the same internal
309 .Va new_size ,
310 it is possible for
311 .Fn memstats
312 to report usage of greater than 100% for blocks of size
313 .Va new_size .
314 This should be viewed as A Good Thing.
315 .Sh RETURN VALUES
316 The function
317 .Fn memget
318 returns a
319 .No non- Ns Dv NULL
320 pointer to a block of memory of the requested
321 .Fa size .
322 It returns
323 .Dv NULL
324 if either the
325 .Fa size
326 is invalid (less than or equal to zero) or a
327 .Xr malloc 3
328 of a new block of memory fails. In the former case,
329 .Va errno
330 is set to
331 .Dv EINVAL ;
332 in the latter, it is set to
333 .Dv ENOMEM .
334 .Pp
335 Neither
336 .Fn memput
337 nor
338 .Fn memstats
339 return a value.
340 .\" This next request is for sections 1, 6, 7 & 8 only
341 .\" .Sh ENVIRONMENT
342 .\" .Sh FILES
343 .\" .Sh EXAMPLES
344 .\" This next request is for sections 1, 6, 7 & 8 only
345 .\" (command return values (to shell) and
346 .\" fprintf/stderr type diagnostics)
347 .\" .Sh DIAGNOSTICS
348 .\" The next request is for sections 2 and 3 error
349 .\" and signal handling only.
350 .Sh ERRORS
351 .Va errno
352 is set as follows:
353 .Bl -tag -width "ENOMEM " -offset indent
354 .It Dv EINVAL
355 set by both
356 .Fn memget
357 and
358 .Fn memput
359 if the
360 .Fa size
361 is zero or negative
362 .It Dv ENOMEM
363 set by
364 .Fn memget
365 if a call to
366 .Xr malloc 3
367 fails
368 .El
369 .Sh SEE ALSO
370 .Xr free 3 ,
371 .Xr malloc 3 .
372 .\" .Sh STANDARDS
373 .\" .Sh HISTORY
374 .Sh AUTHORS
375 Steven J. Richardson and Paul Vixie, Vixie Enterprises.
376 .\" .Sh BUGS