oracular (3) libatomic-malloc.3.gz

NAME

       libatomic-malloc - Library providing simple almost-lock-free malloc implementation

SYNOPSIS

       #include <atomic_ops_malloc.h>

       cc ... -latomic_ops_gpl

       Note that the AO_malloc implementation is licensed under the GPL, unlike the lower level routines.

       void *AO_malloc(size_t sz);
       void AO_free(void *p);
       void AO_malloc_enable_mmap(void);

DESCRIPTION

       A simple almost-lock-free malloc implementation.

       This  is  intended  as  a safe way to allocate memory from a signal handler, or to allocate memory in the
       context of a library that does not know what thread library it will be used with.  In either case locking
       is impossible.

       Note  that  the  operations  are only guaranteed to be 1-lock-free, i.e. a single blocked thread will not
       prevent progress, but multiple blocked threads may.  To safely use these operations in a signal  handler,
       the  handler  should be non-reentrant, i.e. it should not be interruptable by another handler using these
       operations.  Furthermore use outside  of  signal  handlers  in  a  multithreaded  application  should  be
       protected  by  a  lock,  so  that at most one invocation may be interrupted by a signal.  The header will
       define the macro AO_MALLOC_IS_LOCK_FREE on platforms on which malloc is completely lock-free,  and  hence
       these restrictions do not apply.

       In  the presence of threads, but absence of contention, the time performance of this package should be as
       good,  or  slightly  better  than,  most  system  malloc  implementations.   Its  space  performance   is
       theoretically optimal (to within a constant factor), but probably quite poor in practice.  In particular,
       no attempt is made to coalesce free small memory blocks.  Something like Doug Lea's malloc is  likely  to
       use significantly less memory for complex applications.

       Perfomance on platforms without an efficient compare-and-swap implementation will be poor.

       This  package  was  not  designed for processor-scalability in the face of high allocation rates.  If all
       threads happen to allocate different-sized objects, you might get lucky.  Otherwise expect contention and
       false-sharing  problems.  If this is an issue, something like Maged Michael's algorithm (PLDI 2004) would
       be technically a far better choice.  If you are concerned only with scalablity,  and  not  signal-safety,
       you  might also consider using Hoard instead.  We have seen a factor of 3 to 4 slowdown from the standard
       glibc malloc implementation with contention, even when the performance  without  contention  was  faster.
       (To make the implementation more scalable, one would need to replicate at least the free list headers, so
       that concurrent access is possible without cache conflicts.)

       Unfortunately there is no portable async-signal-safe way to obtain large chunks of memory  from  the  OS.
       Based  on  reading  of  the source code, mmap-based allocation appears safe under Linux, and probably BSD
       variants.  It is probably unsafe for operating systems built on Mach, such as  Apple's  Darwin.   Without
       use of mmap, the allocator is limited to a fixed size, statically preallocated heap (2MB by default), and
       will fail to allocate objects above a certain  size  (just  under  64K  by  default).   Use  of  mmap  to
       circumvent these limitations requires an explicit call.

       The entire interface to the AO_malloc package currently consists of:

       AO_malloc
              Allocate an area of memory

       AO_free
              Free a previously malloced memory area

       AO_malloc_enable_mmap
              Enable mmap for large malloc chunks

SEE ALSO

       libatomic-ops(3), libatomic-stack(3)

AUTHOR

       This  manual  page  was written by Ian Wienand <ianw@gelato.unsw.edu.au>, based on comments in the source
       code.  It was written for the Debian project (but may be used by others).