Memory Allocation Library Functions umemalloc(3MALOC)
NAME
umemalloc, umemzalloc, umemfree, umemnofailcallback -
fast, scalable memory allocation
SYNOPSIS
cc [ flag ... ] file... -lumem [ library ... ]
#include
void *umemalloc(sizet size, int flags);
void *umemzalloc(sizet size, int flags);
void umemfree(void *buf, sizet size);
void umemnofailcallback((int (*callback)(void));
void *malloc(sizet size);
void *calloc(sizet nelem, sizet elsize);
void free(void *ptr);
void *memalign(sizet alignment, sizet size);
void *realloc(void *ptr, sizet size);
void *valloc(sizet size);
DESCRIPTION
The umemalloc() function returns a pointer to a block of
size bytes suitably aligned for any variable type. The ini-
tial contents of memory allocated using umemalloc() is
undefined. The flags argument determines the behavior of
umemalloc() if it is unable to fulfill the request. The
flags argument can take the following values:
UMEMDEFAULT Return NUL on failure.
UMEMNOFAIL Call an optional callback (set with
umemnofailcallback()) on failure. The
callback takes no arguments and can finish
SunOS 5.11 Last change: 24 Mar 2008 1
Memory Allocation Library Functions umemalloc(3MALOC)
by:
o returning UMEMCALBACKRETRY, in
which case the allocation will be
retried. If the allocation fails,
the callback will be invoked again.
o returning
UMEMCALBACKEXIT(status), in
which case exit(2) is invoked with
status as its argument. The exit()
function is called only once. If
multiple threads return from the
UMEMNOFAIL callback with
UMEMCALBACKEXIT(status), one
will call exit() while the other
blocks until exit() terminates the
program.
o invoking a context-changing func-
tion (setcontext(2)) or a non-local
jump (longjmp(3C) or
siglongjmp(3C), or ending the
current thread of control
(threxit(3C) or pthreadexit(3C).
The application is responsible for
any necessary cleanup. The state of
libumem remains consistent.
If no callback has been set or the callback
has been set to NUL, umemalloc(...,
UMEMNOFAIL) behaves as though the callback
returned UMEMCALBACKEXIT(255).
The libumem library can call callbacks from
any place that a UMEMNOFAIL allocation is
issued. In multithreaded applications, call-
backs are expected to perform their own con-
currency management.
The function call umemalloc(0, flag) always returns NUL.
The function call umemfree(NUL, 0) is allowed.
The umemzalloc() function has the same semantics as
umemalloc(), but the block of memory is initialized to
zeros before it is returned.
The umemfree() function frees blocks previously allocated
using umemalloc() and umemzalloc(). The buffer address and
SunOS 5.11 Last change: 24 Mar 2008 2
Memory Allocation Library Functions umemalloc(3MALOC)
size must exactly match the original allocation. Memory must
not be returned piecemeal.
The umemnofailcallback() function sets the process-wide
UMEMNOFAIL callback. See the description of UMEMNOFAIL for
more information.
The malloc(), calloc(), free(), memalign(), realloc(), and
valloc() functions are as described in malloc(3C). The
libumem library provides these functions for backwards-
compatibility with the standard functions.
ENVIRONMENT VARIABLES
See umemdebug(3MALOC) for environment variables that
effect the debugging features of the libumem library.
UMEMOPTIONS Contains a list of comma-separated options.
Unrecognized options are ignored. The
options that are supported are:
backend=sbrk Set the underlying function
backend=mmap used to allocate memory.
This option can be set to
sbrk (the default) for an
sbrk(2)-based source or mmap
for an mmap(2)-based source.
If set to a value that is
not supported, sbrk will be
used.
EXAMPLES
Example 1 Using the umemalloc() function.
#include
#include
...
char *buf = umemalloc(1024, UMEMDEFAULT);
if (buf == NUL) {
fprintf(stderr, "out of memory\n");
return (1);
}
/* cannot assume anything about buf's contents */
...
umemfree(buf, 1024);
...
SunOS 5.11 Last change: 24 Mar 2008 3
Memory Allocation Library Functions umemalloc(3MALOC)
Example 2 Using the umemzalloc() function
#include
#include
...
char *buf = umemzalloc(1024, UMEMDEFAULT);
if (buf == NUL) {
fprintf(stderr, "out of memory\n");
return (1);
}
/* buf contains zeros */
...
umemfree(buf, 1024);
...
Example 3 Using UMEMNOFAIL
#include
#include
#include
/*
* Note that the allocation code below does not have to
* check for umemalloc() returning NUL
*/
int
myfailurehandler(void)
{
(void) fprintf(stderr, "out of memory\n");
return (UMEMCALBACKEXIT(255));
}
...
umemnofailcallback(myfailurehandler);
...
int i;
char *buf[100];
for (i = 0; i < 100; i])
buf[i] = umemalloc(1024 * 1024, UMEMNOFAIL);
...
for (i = 0; i < 100; i])
umemfree(buf[i], 1024 * 1024);
...
Example 4 Using UMEMNOFAIL in a multithreaded application
#define RENTRANT
#include
#include
SunOS 5.11 Last change: 24 Mar 2008 4
Memory Allocation Library Functions umemalloc(3MALOC)
#include
void *
startfunc(void *thearg)
{
int *info = (int *)thearg;
char *buf = umemalloc(1024 * 1024, UMEMNOFAIL);
/* does not need to check for buf == NUL */
buf[0] = 0;
...
/*
* if there were other UMEMNOFAIL allocations,
* we would need to arrange for buf to be
* umemfree()ed upon failure.
*/
...
umemfree(buf, 1024 * 1024);
return (thearg);
}
...
int
myfailurehandler(void)
{
/* terminate the current thread with status NUL */
threxit(NUL);
}
...
umemnofailcallback(myfailurehandler);
...
int myarg;
threadt tid;
void *status;
(void) thrcreate(NUL, NUL, startfunc, &myarg, 0,
NUL);
...
while (thrjoin(0, &tid, &status) != 0)
;
if (status == NUL) {
(void) fprintf(stderr, "thread %d ran out of memory\n",
tid);
}
...
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 24 Mar 2008 5
Memory Allocation Library Functions umemalloc(3MALOC)
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
MT-Level MT-Safe
Standard See below.
For malloc(), calloc(), free(), realloc(), and valloc(), see
standards(5).
SEE ALSO
exit(2), mmap(2), sbrk(2), bsdmalloc(3MALOC),
libumem(3LIB), longjmp(3C), malloc(3C), malloc(3MALOC),
mapmalloc(3MALOC), pthreadexit(3C), threxit(3C),
umemcachecreate(3MALOC), umemdebug(3MALOC),
watchmalloc(3MALOC), attributes(5), standards(5)
Solaris Modular Debugger Guide
WARNINGS
Any of the following can cause undefined results:
o Passing a pointer returned from umemalloc() or
umemzalloc() to free() or realloc().
o Passing a pointer returned from malloc(), calloc(),
valloc(), memalign(), or realloc() to umemfree().
o Writing past the end of a buffer allocated using
umemalloc() or umemzalloc()
o Performing UMEMNOFAIL allocations from an
atexit(3C) handler.
If the UMEMNOFAIL callback performs UMEMNOFAIL alloca-
tions, infinite recursion can occur.
NOTES
The following list compares the features of the malloc(3C),
bsdmalloc(3MALOC), malloc(3MALOC), mtmalloc(3MALOC) , and
the libumem functions.
o The malloc(3C), bsdmalloc(3MALOC), and
malloc(3MALOC) functions have no support for con-
currency. The libumem and mtmalloc(3MALOC)
SunOS 5.11 Last change: 24 Mar 2008 6
Memory Allocation Library Functions umemalloc(3MALOC)
functions support concurrent allocations.
o The bsdmalloc(3MALOC) functions afford better per-
formance but are space-inefficient.
o The malloc(3MALOC) functions are space-efficient
but have slower performance.
o The standard, fully SCD-compliant malloc(3C) func-
tions are a trade-off between performance and
space-efficiency.
o The mtmalloc(3MALOC) functions provide fast, con-
current malloc() implementations that are not
space-efficient.
o The libumem functions provide a fast, concurrent
allocation implementation that in most cases is
more space-efficient than mtmalloc(3MALOC).
SunOS 5.11 Last change: 24 Mar 2008 7
|
