gc-7.2/libatomic_ops/doc/README_malloc.txt

   1 The libatomic_ops_gpl includes a simple almost-lock-free malloc implementation.
   2
   3 This is intended as a safe way to allocate memory from a signal handler,
   4 or to allocate memory in the context of a library that does not know what
   5 thread library it will be used with.  In either case locking is impossible.
   6
   7 Note that the operations are only guaranteed to be 1-lock-free, i.e. a
   8 single blocked thread will not prevent progress, but multiple blocked
   9 threads may.  To safely use these operations in a signal handler,
  10 the handler should be non-reentrant, i.e. it should not be interruptable
  11 by another handler using these operations.  Furthermore use outside
  12 of signal handlers in a multithreaded application should be protected
  13 by a lock, so that at most one invocation may be interrupted by a signal.
  14 The header will define the macro "AO_MALLOC_IS_LOCK_FREE" on platforms
  15 on which malloc is completely lock-free, and hence these restrictions
  16 do not apply.
  17
  18 In the presence of threads, but absence of contention, the time performance
  19 of this package should be as good, or slightly better than, most system
  20 malloc implementations.  Its space performance
  21 is theoretically optimal (to within a constant factor), but probably
  22 quite poor in practice.  In particular, no attempt is made to
  23 coalesce free small memory blocks.  Something like Doug Lea's malloc is
  24 likely to use significantly less memory for complex applications.
  25
  26 Performance on platforms without an efficient compare-and-swap implementation
  27 will be poor.
  28
  29 This package was not designed for processor-scalability in the face of
  30 high allocation rates.  If all threads happen to allocate different-sized
  31 objects, you might get lucky.  Otherwise expect contention and false-sharing
  32 problems.  If this is an issue, something like Maged Michael's algorithm
  33 (PLDI 2004) would be technically a far better choice.  If you are concerned
  34 only with scalability, and not signal-safety, you might also consider
  35 using Hoard instead.  We have seen a factor of 3 to 4 slowdown from the
  36 standard glibc malloc implementation with contention, even when the
  37 performance without contention was faster.  (To make the implementation
  38 more scalable, one would need to replicate at least the free list headers,
  39 so that concurrent access is possible without cache conflicts.)
  40
  41 Unfortunately there is no portable async-signal-safe way to obtain large
  42 chunks of memory from the OS.  Based on reading of the source code,
  43 mmap-based allocation appears safe under Linux, and probably BSD variants.
  44 It is probably unsafe for operating systems built on Mach, such as
  45 Apple's Darwin.  Without use of mmap, the allocator is
  46 limited to a fixed size, statically preallocated heap (2MB by default),
  47 and will fail to allocate objects above a certain size (just under 64K
  48 by default).  Use of mmap to circumvent these limitations requires an
  49 explicit call.
  50
  51 The entire interface to the AO_malloc package currently consists of:
  52
  53 #include <atomic_ops_malloc.h> /* includes atomic_ops.h */
  54
  55 void *AO_malloc(size_t sz);
  56 void AO_free(void *p);
  57 void AO_malloc_enable_mmap(void);