 |
Index for
Section 3 |
|
 |
Alphabetical
listing for A |
|
 |
Bottom of
page |
|
amalloc(3)
NAME
acalloc, acreate, adelete, afree, amallinfo, amalloc, amallopt,
amallocblksize, 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
compatibility:
int amallopt(
int cmd,
int value,
void *ap );
struct mallinfo amallinfo(
void *ap );
LIBRARY
Standard C Library (libc.so, libc.a)
PARAMETERS
addr
A pointer to a buffer used to hold the arena header information.
len The size of the buffer in bytes (minimum 1K).
flags
Attributes of the arena as the bitwise inclusive OR of any combination
of MEM_NOAUTOGROW and MEM_NONCONCURRENT.
ushdr
Currently unused and must be NULL.
grow_func
For non-growing arenas, NULL; for growing arenas, a function to be
called when the allocator requires more memory.
attr
Points to the memory allocation policy and attributes to be used for
allocations from the new arena.
ap A pointer to the arena.
size
A number of bytes of memory.
ptr A pointer to a block of memory.
num_elts
The number of elements in an array.
elt_size
The size of each element in an array.
cmd 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 standard
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 specifies
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 multithreaded. In this case,
allocations and frees using the arena may happen 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:
acreate
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.
nacreate
Allocates 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 outside the arena.
adelete
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().
amalloc
Returns a pointer to a block of at least size bytes suitably aligned
for any use.
afree
Destroys the contents of a block previously allocated by amalloc(),
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().
arealloc
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() degenerates to amalloc(). A zero size
causes the passed block to be freed.
acalloc
Allocates space for an array of num_elts elements of size elt_size. The
space is initialized to zeros.
amallocblksize
Returns the actual size of the block pointed to by ptr. The returned
size may be greater than the original requested size.
amallopt
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.
amallinfo
Provides 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)
|
Index for
Section 3 |
|
|
Alphabetical
listing for A |
|
 |
Top of
page |
|