folly/docs/Overview.md

   1 ### `folly/`
   2
   3 For a high level overview see the [README](folly/README.md)
   4
   5 ### Components
   6
   7 Below is a list of Folly components in alphabetical order, along with
   8 a brief description of each.
   9
  10 #### `Arena.h`, `ThreadCachedArena.h`
  11
  12 Simple arena for memory allocation: multiple allocations get freed all
  13 at once. With threaded version.
  14
  15 #### [`AtomicHashMap.h`, `AtomicHashArray.h`](AtomicHashMap.md)
  16
  17 High-performance atomic hash map with almost lock-free operation.
  18
  19 #### [`Benchmark.h`](Benchmark.md)
  20
  21 A small framework for benchmarking code. Client code registers
  22 benchmarks, optionally with an argument that dictates the scale of the
  23 benchmark (iterations, working set size etc). The framework runs
  24 benchmarks (subject to a command-line flag) and produces formatted
  25 output with timing information.
  26
  27 #### `Bits.h`
  28
  29 Various bit manipulation utilities optimized for speed; includes functions
  30 that wrap the
  31 [ffsl(l)](http://linux.die.net/man/3/ffsll) primitives in a uniform
  32 interface.
  33
  34 #### `ConcurrentSkipList.h`
  35
  36 An implementation of the structure described in [A Provably Correct
  37 Scalable Concurrent Skip
  38 List](http://www.cs.tau.ac.il/~shanir/nir-pubs-web/Papers/OPODIS2006-BA.pdf)
  39 by Herlihy et al.
  40
  41 #### [`Conv.h`](Conv.md)
  42
  43 A variety of data conversion routines (notably to and from string),
  44 optimized for speed and safety.
  45
  46 #### `DiscriminatedPtr.h`
  47
  48 Similar to `boost::variant`, but restricted to pointers only. Uses the
  49 highest-order unused 16 bits in a pointer as discriminator. So
  50 `sizeof(DiscriminatedPtr<int, string, Widget>) == sizeof(void*)`.
  51
  52 #### [`dynamic.h`](Dynamic.md)
  53
  54 Dynamically-typed object, created with JSON objects in mind.
  55
  56 #### `Endian.h`
  57
  58 Endian conversion primitives.
  59
  60 ####`Escape.h`
  61
  62 Escapes a string in C style.
  63
  64 ####`eventfd.h`
  65
  66 Wrapper around the
  67 [`eventfd`](http://www.kernel.org/doc/man-pages/online/pages/man2/eventfd.2.html)
  68 system call.
  69
  70 ####[`FBString.h`](FBString.md)
  71
  72 A drop-in implementation of `std::string` with a variety of optimizations.
  73
  74 ####[`FBVector.h`](FBVector.md)
  75
  76 A mostly drop-in implementation of `std::vector` with a variety of
  77 optimizations.
  78
  79 ####`Foreach.h`
  80
  81 Pseudo-statements (implemented as macros) for iteration.
  82
  83 ####[`Format.h`](Format.md)
  84
  85 Python-style formatting utilities.
  86
  87 ####[`GroupVarint.h`](GroupVarint.md)
  88
  89 [Group Varint
  90 encoding](http://www.ir.uwaterloo.ca/book/addenda-06-index-compression.html)
  91 for 32-bit values.
  92
  93 ####`Hash.h`
  94
  95 Various popular hash function implementations.
  96
  97 ####[`Histogram.h`](Histogram.md)
  98
  99 A simple class for collecting histogram data.
 100
 101 ####`IntrusiveList.h`
 102
 103 Convenience type definitions for using `boost::intrusive_list`.
 104
 105 ####`json.h`
 106
 107 JSON serializer and deserializer. Uses `dynamic.h`.
 108
 109 ####`Likely.h`
 110
 111 Wrappers around [`__builtin_expect`](http://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html).
 112
 113 ####`Malloc.h`
 114
 115 Memory allocation helpers, particularly when using jemalloc.
 116
 117 ####`MapUtil.h`
 118
 119 Helpers for finding items in associative containers (such as
 120 `std::map` and `std::unordered_map`).
 121
 122 ####[`PackedSyncPtr.h`](PackedSyncPtr.md)
 123
 124 A highly specialized data structure consisting of a pointer, a 1-bit
 125 spin lock, and a 15-bit integral, all inside one 64-bit word.
 126
 127 ####`Preprocessor.h`
 128
 129 Necessarily evil stuff.
 130
 131 ####`PrettyPrint.h`
 132
 133 Pretty-printer for numbers that appends suffixes of unit used: bytes
 134 (kb, MB, ...), metric suffixes (k, M, G, ...), and time (s, ms, us,
 135 ns, ...).
 136
 137 ####[`ProducerConsumerQueue.h`](ProducerConsumerQueue.md)
 138
 139 Lock free single-reader, single-writer queue.
 140
 141 ####`Random.h`
 142
 143 Defines only one function---`randomNumberSeed()`.
 144
 145 ####`Range.h`
 146
 147 Boost-style range facility and the `StringPiece` specialization.
 148
 149 ####`RWSpinLock.h`
 150
 151 Fast and compact reader-writer spin lock.
 152
 153 ####`ScopeGuard.h`
 154
 155 C++11 incarnation of the old [ScopeGuard](http://drdobbs.com/184403758) idiom.
 156
 157 ####[`SmallLocks.h`](SmallLocks.md)
 158
 159 Very small spin locks (1 byte and 1 bit).
 160
 161 ####`small_vector.h`
 162
 163 Vector with the small buffer optimization and an optional embedded
 164 `PicoSpinLock`.
 165
 166 ####`sorted_vector_types.h`
 167
 168 Collections similar to `std::map` but implemented as sorted vectors.
 169
 170 ####`StlAllocator.h`
 171
 172 STL allocator wrapping a simple allocate/deallocate interface.
 173
 174 ####`String.h`
 175
 176 String utilities that connect `folly::fbstring` with `std::string`.
 177
 178 ####`Subprocess.h`
 179
 180 Subprocess library, modeled after Python's subprocess module.
 181
 182 ####[`Synchronized.h`](Synchronized.md)
 183
 184 High-level synchronization library.
 185
 186 ####`System.h`
 187
 188 Demangling and errno utilities.
 189
 190 ####[`ThreadCachedInt.h`](ThreadCachedInt.md)
 191
 192 High-performance atomic increment using thread caching.
 193
 194 ####[`ThreadLocal.h`](ThreadLocal.md)
 195
 196 Improved thread local storage for non-trivial types.
 197
 198 ####`TimeoutQueue.h`
 199
 200 Queue with per-item timeout.
 201
 202 ####`Traits.h`
 203
 204 Type traits that complement those defined in the standard C++11 header
 205 `<traits>`.
 206
 207 ####`Unicode.h`
 208
 209 Defines the `codePointToUtf8` function.