2 .\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright (c) 2012 Joyent, Inc. All Rights Reserved.
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH UMEM_ALLOC 3MALLOC "Mar 24, 2008"
9 umem_alloc, umem_zalloc, umem_free, umem_nofail_callback \- fast, scalable
14 cc [ \fIflag \&.\|.\|.\fR ] \fIfile\fR\&.\|.\|. \fB-lumem\fR [ \fIlibrary \&.\|.\|.\fR ]
17 \fBvoid *\fR\fBumem_alloc\fR(\fBsize_t\fR \fIsize\fR, \fBint\fR \fIflags\fR);
22 \fBvoid *\fR\fBumem_zalloc\fR(\fBsize_t\fR \fIsize\fR, \fBint\fR \fIflags\fR);
27 \fBvoid\fR \fBumem_free\fR(\fBvoid *\fR\fIbuf\fR, \fBsize_t\fR \fIsize\fR);
32 \fBvoid\fR \fBumem_nofail_callback\fR(\fB(int (*\fR\fIcallback\fR)(void));
37 \fBvoid *\fR\fBmalloc\fR(\fBsize_t\fR \fIsize\fR);
42 \fBvoid *\fR\fBcalloc\fR(\fBsize_t\fR \fInelem\fR, \fBsize_t\fR \fIelsize\fR);
47 \fBvoid\fR \fBfree\fR(\fBvoid *\fR\fIptr\fR);
52 \fBvoid *\fR\fBmemalign\fR(\fBsize_t\fR \fIalignment\fR, \fBsize_t\fR \fIsize\fR);
57 \fBvoid *\fR\fBrealloc\fR(\fBvoid *\fR\fIptr\fR, \fBsize_t\fR \fIsize\fR);
62 \fBvoid *\fR\fBvalloc\fR(\fBsize_t\fR \fIsize\fR);
68 The \fBumem_alloc()\fR function returns a pointer to a block of \fIsize\fR
69 bytes suitably aligned for any variable type. The initial contents of memory
70 allocated using \fBumem_alloc()\fR is undefined. The \fIflags\fR argument
71 determines the behavior of \fBumem_alloc()\fR if it is unable to fulfill the
72 request. The \fIflags\fR argument can take the following values:
76 \fB\fBUMEM_DEFAULT\fR\fR
79 Return \fINULL\fR on failure.
85 \fB\fBUMEM_NOFAIL\fR\fR
88 Call an optional \fIcallback\fR (set with \fBumem_nofail_callback()\fR) on
89 failure. The \fIcallback\fR takes no arguments and can finish by:
94 returning \fBUMEM_CALLBACK_RETRY\fR, in which case the allocation will be
95 retried. If the allocation fails, the callback will be invoked again.
101 returning \fBUMEM_CALLBACK_EXIT\fR(\fIstatus\fR), in which case \fBexit\fR(2)
102 is invoked with \fIstatus\fR as its argument. The \fBexit()\fR function is
103 called only once. If multiple threads return from the \fBUMEM_NOFAIL\fR
104 callback with \fBUMEM_CALLBACK_EXIT\fR(\fIstatus\fR), one will call
105 \fBexit()\fR while the other blocks until \fBexit()\fR terminates the program.
111 invoking a context-changing function (\fBsetcontext\fR(2)) or a non-local jump
112 (\fBlongjmp\fR(3C) or \fBsiglongjmp\fR(3C), or ending the current thread of
113 control (\fBthr_exit\fR(3C) or \fBpthread_exit\fR(3C). The application is
114 responsible for any necessary cleanup. The state of \fBlibumem\fR remains
117 If no callback has been set or the callback has been set to \fINULL\fR,
118 \fBumem_alloc\fR(..., \fBUMEM_NOFAIL\fR) behaves as though the callback
119 returned \fBUMEM_CALLBACK_EXIT\fR(255).
121 The \fBlibumem\fR library can call callbacks from any place that a
122 \fBUMEM_NOFAIL\fR allocation is issued. In multithreaded applications,
123 callbacks are expected to perform their own concurrency management.
128 The function call \fBumem_alloc\fR(0, \fIflag\fR) always returns \fINULL\fR.
129 The function call \fBumem_free\fR(\fINULL\fR, 0) is allowed.
132 The \fBumem_zalloc()\fR function has the same semantics as \fBumem_alloc()\fR,
133 but the block of memory is initialized to zeros before it is returned.
136 The \fBumem_free()\fR function frees blocks previously allocated using
137 \fBumem_alloc()\fR and \fBumem_zalloc()\fR. The buffer address and size must
138 exactly match the original allocation. Memory must not be returned piecemeal.
141 The \fBumem_nofail_callback()\fR function sets the process-wide UMEM_NOFAIL
142 callback. See the description of UMEM_NOFAIL for more information.
145 The \fBmalloc()\fR, \fBcalloc()\fR, \fBfree()\fR, \fBmemalign()\fR,
146 \fBrealloc()\fR, and \fBvalloc()\fR functions are as described in
147 \fBmalloc\fR(3C). The \fBlibumem\fR library provides these functions for
148 backwards-compatibility with the standard functions.
149 .SH ENVIRONMENT VARIABLES
152 See \fBumem_debug\fR(3MALLOC) for environment variables that effect the
153 debugging features of the \fBlibumem\fR library.
157 \fB\fBUMEM_OPTIONS\fR\fR
160 Contains a list of comma-separated options. Unrecognized options are ignored.
161 The options that are supported are:
165 \fB\fBbackend\fR=\fBsbrk\fR\fR
169 \fB\fBbackend\fR=\fBmmap\fR\fR
172 Set the underlying function used to allocate memory. This option can be set to
173 \fBsbrk\fR (the default) for an \fBsbrk\fR(2)-based source or \fBmmap\fR for an
174 \fBmmap\fR(2)-based source. If set to a value that is not supported, \fBsbrk\fR
180 \fB\fBperthread_cache\fR=\fBsize\fR\fR
183 libumem allows for each thread to cache recently freed small allocations for
184 future allocations. The size argument, which accepts k, m, g, and t, suffixes
185 denotes the maximum amount of memory each thread can use for this purpose. The
186 default amount used is 1 MB. Any buffers in the per-thread cache are freed when
187 the thread exits. The efficacy of the per-thread cache can be determined with
188 the \fB::umastat\fR \fBmdb\fR(1) \fIdcmd\fR debugger command.
193 \fB\fBallocator\fR=\fBbest\fR\fR
197 \fB\fBallocator\fR=\fBfirst\fR\fR
201 \fB\fBallocator\fR=\fBinstant\fR\fR
205 \fB\fBallocator\fR=\fBnext\fR\fR
208 Set the underlying allocation strategy. The \fBbest\fR fit strategy tells
209 libumem to use the smallest free segment possible. The \fBinstant\fR fit
210 strategy approximates the best fit strategy in constant cpu time. The
211 \fBfirst\fR fit strategy takes the first free segment that can honor the
212 allocation. The \fBnext\fR fit strategy uses the next free segment after the
213 previously allocated one.
220 \fBExample 1 \fRUsing the \fBumem_alloc()\fR function.
227 char *buf = umem_alloc(1024, UMEM_DEFAULT);
230 fprintf(stderr, "out of memory\en");
233 /* cannot assume anything about buf's contents */
235 umem_free(buf, 1024);
241 \fBExample 2 \fRUsing the \fBumem_zalloc()\fR function
248 char *buf = umem_zalloc(1024, UMEM_DEFAULT);
251 fprintf(stderr, "out of memory\en");
254 /* buf contains zeros */
256 umem_free(buf, 1024);
262 \fBExample 3 \fRUsing UMEM_NOFAIL
271 * Note that the allocation code below does not have to
272 * check for umem_alloc() returning NULL
275 my_failure_handler(void)
277 (void) fprintf(stderr, "out of memory\en");
278 return (UMEM_CALLBACK_EXIT(255));
281 umem_nofail_callback(my_failure_handler);
286 for (i = 0; i < 100; i++)
287 buf[i] = umem_alloc(1024 * 1024, UMEM_NOFAIL);
289 for (i = 0; i < 100; i++)
290 umem_free(buf[i], 1024 * 1024);
296 \fBExample 4 \fRUsing UMEM_NOFAIL in a multithreaded application
305 start_func(void *the_arg)
307 int *info = (int *)the_arg;
308 char *buf = umem_alloc(1024 * 1024, UMEM_NOFAIL);
310 /* does not need to check for buf == NULL */
314 * if there were other UMEM_NOFAIL allocations,
315 * we would need to arrange for buf to be
316 * umem_free()ed upon failure.
319 umem_free(buf, 1024 * 1024);
324 my_failure_handler(void)
326 /* terminate the current thread with status NULL */
330 umem_nofail_callback(my_failure_handler);
337 (void) thr_create(NULL, NULL, start_func, &my_arg, 0,
340 while (thr_join(0, &tid, &status) != 0)
343 if (status == NULL) {
344 (void) fprintf(stderr, "thread %d ran out of memory\en",
354 See \fBattributes\fR(5) for descriptions of the following attributes:
362 ATTRIBUTE TYPE ATTRIBUTE VALUE
364 Interface Stability Committed
373 For \fBmalloc()\fR, \fBcalloc()\fR, \fBfree()\fR, \fBrealloc()\fR, and
374 \fBvalloc()\fR, see \fBstandards\fR(5).
378 \fBexit\fR(2), \fBmmap\fR(2), \fBsbrk\fR(2), \fBbsdmalloc\fR(3MALLOC),
379 \fBlibumem\fR(3LIB), \fBlongjmp\fR(3C), \fBmalloc\fR(3C),
380 \fBmalloc\fR(3MALLOC), \fBmapmalloc\fR(3MALLOC), \fBpthread_exit\fR(3C),
381 \fBthr_exit\fR(3C), \fBumem_cache_create\fR(3MALLOC),
382 \fBumem_debug\fR(3MALLOC), \fBwatchmalloc\fR(3MALLOC), \fBattributes\fR(5),
386 \fISolaris Modular Debugger Guide\fR
390 Any of the following can cause undefined results:
395 Passing a pointer returned from \fBumem_alloc()\fR or \fBumem_zalloc()\fR to
396 \fBfree()\fR or \fBrealloc()\fR.
402 Passing a pointer returned from \fBmalloc()\fR, \fBcalloc()\fR, \fBvalloc()\fR,
403 \fBmemalign()\fR, or \fBrealloc()\fR to \fBumem_free()\fR.
409 Writing past the end of a buffer allocated using \fBumem_alloc()\fR or
416 Performing \fBUMEM_NOFAIL\fR allocations from an \fBatexit\fR(3C) handler.
420 If the \fBUMEM_NOFAIL\fR callback performs \fBUMEM_NOFAIL\fR allocations,
421 infinite recursion can occur.
425 The following list compares the features of the \fBmalloc\fR(3C),
426 \fBbsdmalloc\fR(3MALLOC), \fBmalloc\fR(3MALLOC), \fBmtmalloc\fR(3MALLOC) , and
427 the \fBlibumem\fR functions.
432 The \fBmalloc\fR(3C), \fBbsdmalloc\fR(3MALLOC), and \fBmalloc\fR(3MALLOC)
433 functions have no support for concurrency. The \fBlibumem\fR and
434 \fBmtmalloc\fR(3MALLOC) functions support concurrent allocations.
440 The \fBbsdmalloc\fR(3MALLOC) functions afford better performance but are
447 The \fBmalloc\fR(3MALLOC) functions are space-efficient but have slower
454 The standard, fully SCD-compliant \fBmalloc\fR(3C) functions are a trade-off
455 between performance and space-efficiency.
461 The \fBmtmalloc\fR(3MALLOC) functions provide fast, concurrent \fBmalloc()\fR
462 implementations that are not space-efficient.
468 The \fBlibumem\fR functions provide a fast, concurrent allocation
469 implementation that in most cases is more space-efficient than
470 \fBmtmalloc\fR(3MALLOC).