tlsf-bsd/README.md

   1 # TLSF-BSD
   2
   3 Two Level Segregated Fit memory allocator implementation with O(1)
   4 time complexity, distributed under the BSD License.
   5
   6 ## Features
   7
   8 * O(1) cost for malloc, free, realloc, memalign
   9 * Extremely low overhead per allocation (4 bytes)
  10 * Low overhead per TLSF management of pools (~3kB)
  11 * Low fragmentation
  12 * Compiles to only a few kB of code and data
  13 * Support for adding and removing memory pool regions on the fly
  14
  15 ## API Usage
  16
  17 You can essentially pass a memory pool for TLSF to manage.
  18 ```C
  19 enum { STATIC_POOL_SIZE = 1 << 20 };
  20 static char s_pool[STATIC_POOL_SIZE];
  21
  22 tlsf_t instance = tlsf_create_with_pool(s_pool, STATIC_POOL_SIZE);
  23
  24 void *data = tlsf_malloc(instance, 64);
  25 tlsf_free(instance, data);
  26 ```
  27
  28 ## Caveats
  29
  30 * Currently, assumes architecture can make 4-byte aligned accesses
  31 * Not designed to be thread safe; the user must provide this
  32
  33 ## Notes
  34 This code was based on the TLSF 1.4 spec and documentation found at:
  35     http://www.gii.upv.es/tlsf/main/docs
  36
  37 ## Reference
  38
  39 M. Masmano, I. Ripoll, A. Crespo, and J. Real.
  40 TLSF: a new dynamic memory allocator for real-time systems.
  41 In Proc. ECRTS (2004), IEEE Computer Society, pp. 79-86.
  42
  43 This implementation was written to the specification of the document,
  44 therefore no GPL restrictions apply.
  45
  46 It also leverages the TLSF 2.0 improvement to shrink the per-block overhead
  47 from 8 to 4 bytes.
  48
  49 ## Known Issues
  50
  51 * Due to the internal block structure size and the implementation
  52 details of `tlsf_memalign`, there is worst-case behavior when requesting
  53 small (<16 byte) blocks aligned to 8-byte boundaries. Overuse of memalign
  54 will generally increase fragmentation, but this particular case will leave
  55 lots of unusable "holes" in the pool. The solution would be to internally
  56 align all blocks to 8 bytes, but this will require significantl changes
  57 to the implementation.
  58
  59 ## Licensing
  60
  61 TLSF-BSD is freely redistributable under the two-clause BSD License.
  62 Use of this source code is governed by a BSD-style license that can be found
  63 in the `LICENSE` file.