Man Linux: Main Page and Category List

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).