amalloc(3)amalloc(3)NAME
acalloc, acreate, adelete, afree, amallinfo, amalloc, amallopt, amal‐
locblksize, arealloc, nacreate - arena memory allocator
SYNOPSIS
#include <sys/types.h> #include <malloc.h> #include <numa.h>
void *acreate(
void *addr,
size_t len,
int flags,
void *ushdr,
void *(*grow_func)(size_t, void *) ); void *nacreate(
int flags,
memalloc_attr_t *attr ); int adelete(
void *ap ); void *amalloc(
size_t size,
void *ap ); void afree(
void *ptr,
void *ap ); void *arealloc(
void *ptr,
size_t size,
void *ap ); void *acalloc(
size_t num_elts,
size_t elt_size,
void *ap ); size_t amallocblksize(
void *ptr,
void *ap );
The following function definitions are provided only for System V com‐
patibility: int amallopt(
int cmd,
int value,
void *ap ); struct mallinfo amallinfo(
void *ap );
LIBRARY
Standard C Library (libc.so, libc.a)
PARAMETERS
A pointer to a buffer used to hold the arena header information. The
size of the buffer in bytes (minimum 1K). Attributes of the arena as
the bitwise inclusive OR of any combination of MEM_NOAUTOGROW and
MEM_NONCONCURRENT. Currently unused and must be NULL. For non-growing
arenas, NULL; for growing arenas, a function to be called when the
allocator requires more memory. Points to the memory allocation policy
and attributes to be used for allocations from the new arena. A
pointer to the arena. A number of bytes of memory. A pointer to a
block of memory. The number of elements in an array. The size of each
element in an array. A command for the amallopt() function.
DESCRIPTION
The amalloc family of routines provides a main memory allocator based
on the malloc(3) memory allocator. This allocator has been extended so
that an arbitrary memory space (“arena”) can be set up as an area from
which to allocate memory.
Calls to the amalloc family of routines differ from calls to the stan‐
dard malloc(3) only in that an arena pointer must be supplied. This
arena pointer is returned by a call to acreate() or nacreate().
For the acreate() and nacreate() functions, the flags parameter speci‐
fies the attributes of a newly created arena: MEM_NOAUTOGROW -- Causes
the grow_func argument to be ignored and inhibits any attempt to expand
the arena beyond the size len of the initial buffer. This parameter is
not allowed in nacreate(). MEM_NONCONCURRENT -- Turns off all attempts
to use locking and atomic updates for this arena when allocating and
freeing memory. This has an affect only when the calling code is multi‐
threaded. In this case, allocations and frees using the arena may hap‐
pen faster, but the user must be extremely careful to guarantee that no
two threads reference this arena at the same time in arena operations.
Function descriptions: Sets up an area defined as starting at virtual
address addr and extending for len bytes. Arenas can be either growing
or non-growing.
An arena that is non-growing is constrained to use only up to
len bytes of memory. The grow_func parameter should be NULL in
this case.
If the arena is “growable”, len specifies the original size
(minimum of 1K bytes) and the grow_func parameter specifies a
function that will be called when the allocator requires more
memory. Note that the original buffer addr will be used only for
the arena header; the first time more memory is required, the
“grow” function will be called.
The grow function will be called with two parameters: the number
of bytes required and a pointer to the arena requiring the
space. The number of bytes requested will always be a multiple
of M_BLKSZ (see <malloc.h> header file). The function should
return the address of a suitably large block of memory. This
block does not need to be contiguous with the original arena
memory. This block could be obtained from a number of sources,
such as by mapping in another file (by means of mmap(2)) or by
calling malloc(3) to enlarge the program's data space. If the
grow function decides that it cannot provide any more space, it
must return (void*)-1.
The ushdr function is currently unused and must be NULL. Allo‐
cates an arena header and sets up a new growable arena. The
location for the arena is determined automatically. The arena
will use nmmap() internally to obtain memory from the operating
system, passing in the saved attr parameter.
Note that use of the MEM_NOAUTOGROW flag is not allowed in calls
to nacreate(). The returned arena may be used in all other arena
malloc functions; however, it is not specified whether memory
freed by afree() from this arena is ever released for reuse out‐
side the arena. Causes any resources allocated for the arena
(for example, mutexes) to be freed. Nothing is done with the
arena memory itself. No additional calls to any arena functions
can be made after calling adelete(). Returns a pointer to a
block of at least size bytes suitably aligned for any use.
Destroys the contents of a block previously allocated by amal‐
loc(), arealloc(), or acalloc() and makes this space available
for future allocation. The argument to afree() is a pointer to
the block previously allocated by amalloc(), arealloc(), or
acalloc().
Undefined results will occur if the space assigned by any of the
three arena allocator functions is overrun or if some random
number is handed to afree(). It is always permitted to pass NULL
to afree(). Changes the size of the block pointed to by ptr to
size bytes and returns a pointer to the (possibly moved) block.
The contents will be unchanged, up to the lesser of the new and
old sizes. In the special case of a null ptr, arealloc() degen‐
erates to amalloc(). A zero size causes the passed block to be
freed. Allocates space for an array of num_elts elements of
size elt_size. The space is initialized to zeros. Returns the
actual size of the block pointed to by ptr. The returned size
may be greater than the original requested size. Provides for
control over the allocation algorithm. The available values for
cmd are defined in the <malloc.h> header file.
The amallopt() function can be called repeatedly but, for most
commands, not after the first small block is allocated. Pro‐
vides instrumentation describing space usage. It returns the
mallinfo() structure defined in the <malloc.h> header file. The
structure is zero until after the first space has been allocated
from the arena.
Each of the allocation routines returns a pointer to space suitably
aligned for storage of any type of object.
RETURN VALUES
The acreate() function returns NULL and sets errno if either len is
less than 1K or the MEM_SHARED flag is passed.
The amalloc(), arealloc(), and acalloc() functions return a NULL
pointer if there is not enough available memory. When arealloc()
returns NULL, the block pointed to by ptr is left intact. If amallopt()
is called after any allocation (for most cmd arguments) or if cmd or
value is invalid, nonzero is returned. Otherwise, it returns zero.
SEE ALSO
Functions: malloc(3), nmmap(2), numa_intro(3), numa_types(4)amalloc(3)