folly/docs/Overview.md

   1 ### `folly/`
   2
   3 For a high level overview see the [README](../../README.md)
   4
   5 ### Components
   6
   7 Below is a list of (some) 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), `AtomicHashArray.h`, `AtomicLinkedList.h`, ...
  16
  17 High-performance atomic data-structures. Many of these are built with very specific
  18 tradeoffs and constraints in mind that make them faster than their more general
  19 counterparts. Each header should contain information about what these tradeoffs are.
  20
  21 #### `Baton.h`
  22
  23 A Baton allows a thread to block once and be awoken: it captures a single handoff. It is
  24 essentially a (very small, very fast) semaphore that supports only a single call to `sem_call`
  25 and `sem_wait`.
  26
  27 #### [`Benchmark.h`](Benchmark.md)
  28
  29 A small framework for benchmarking code. Client code registers
  30 benchmarks, optionally with an argument that dictates the scale of the
  31 benchmark (iterations, working set size etc). The framework runs
  32 benchmarks (subject to a command-line flag) and produces formatted
  33 output with timing information.
  34
  35 #### `Bits.h`
  36
  37 Various bit manipulation utilities optimized for speed; includes functions
  38 that wrap the
  39 [ffsl(l)](http://linux.die.net/man/3/ffsll) primitives in a uniform
  40 interface.
  41
  42 #### `ConcurrentSkipList.h`
  43
  44 An implementation of the structure described in [A Provably Correct
  45 Scalable Concurrent Skip
  46 List](http://www.cs.tau.ac.il/~shanir/nir-pubs-web/Papers/OPODIS2006-BA.pdf)
  47 by Herlihy et al.
  48
  49 #### [`Conv.h`](Conv.md)
  50
  51 A variety of data conversion routines (notably to and from string),
  52 optimized for speed and safety.
  53
  54 #### `Demangle.h`
  55
  56 Pretty-printing C++ types.
  57
  58 #### `DiscriminatedPtr.h`
  59
  60 Similar to `boost::variant`, but restricted to pointers only. Uses the
  61 highest-order unused 16 bits in a pointer as discriminator. So
  62 `sizeof(DiscriminatedPtr<int, string, Widget>) == sizeof(void*)`.
  63
  64 #### [`dynamic.h`](Dynamic.md)
  65
  66 Dynamically-typed object, created with JSON objects in mind. `DynamicConverter.h` is
  67 a utility for effeciently converting from a `dynamic` to a more concrete structure when
  68 the scheme is known (e.g. json -> `map<int,int>`).
  69
  70 #### `EvictingCacheMap.h`
  71
  72 A simple LRU hash map.
  73
  74 #### [`FBString.h`](FBString.md)
  75
  76 A drop-in implementation of `std::string` with a variety of optimizations.
  77
  78 #### [`FBVector.h`](FBVector.md)
  79
  80 A mostly drop-in implementation of `std::vector` with a variety of
  81 optimizations.
  82
  83 #### `File.h`
  84
  85 A C++ abstraction around files.
  86
  87 #### `Fingerprint.h`
  88
  89 Rabin fingerprinting.
  90
  91 ### [`Function.h`](Function.md)
  92
  93 A polymorphic wrapper for callables similar to `std::function` but not copyable and therefore able to wrap non-copyable callables, such as lambdas that capture move-only types like `std::unique_ptr` or `folly::Promise`.
  94
  95 ### [`futures/`](../futures/README.md)
  96
  97 Futures is a framework for expressing asynchronous code in C++ using the Promise/Future pattern.
  98
  99 #### [`Format.h`](Format.md)
 100
 101 Python-style formatting utilities.
 102
 103 #### `gen/`
 104
 105 This library makes it possible to write declarative comprehensions for
 106 processing sequences of values efficiently in C++ akin to C#'s LINQ.
 107
 108 #### [`GroupVarint.h`](GroupVarint.md)
 109
 110 [Group Varint
 111 encoding](http://www.ir.uwaterloo.ca/book/addenda-06-index-compression.html)
 112 for 32-bit values.
 113
 114 #### `IpAddress.h`
 115
 116 A collection of utilities to deal with IPAddresses, including ipv4 and ipv6.
 117
 118 #### `io/`
 119
 120 A collection of useful of abstractions for high-performance io. This is heavily relied upon
 121 in Facebook's internally networking code.
 122
 123 #### `Hash.h`
 124
 125 Various popular hash function implementations.
 126
 127 #### [`Histogram.h`](Histogram.md)
 128
 129 A simple class for collecting histogram data.
 130
 131 #### `IntrusiveList.h`
 132
 133 Convenience type definitions for using `boost::intrusive_list`.
 134
 135 #### `json.h`
 136
 137 JSON serializer and deserializer. Uses `dynamic.h`.
 138
 139 #### `Likely.h`
 140
 141 Wrappers around [`__builtin_expect`](http://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html).
 142
 143 #### `Malloc.h`, `Memory.h`
 144
 145 Memory allocation helpers, particularly when using jemalloc.
 146
 147 #### `MicroSpinLock.h`
 148
 149 A really, *really* small spinlock for fine-grained locking of lots of teeny-tiny data.
 150
 151 #### `MPMCQueue.h`
 152
 153 MPMCQueue<typename> is a high-performance bounded concurrent queue that
 154 supports multiple producers, multiple consumers, and optional blocking.
 155 The queue has a fixed capacity, for which all memory will be allocated
 156  up front.
 157
 158 The additional utility `MPMCPipeline.h` is an extension that lets you
 159 chain several queues together with processing steps in between.
 160
 161 #### [`PackedSyncPtr.h`](PackedSyncPtr.md)
 162
 163 A highly specialized data structure consisting of a pointer, a 1-bit
 164 spin lock, and a 15-bit integral, all inside one 64-bit word.
 165
 166 #### [`Poly.h`](Poly.md)
 167
 168 A class template that makes it relatively easy to define a type-erasing
 169 polymorphic object wrapper.
 170
 171 #### `Preprocessor.h`
 172
 173 Necessarily evil stuff.
 174
 175 #### [`ProducerConsumerQueue.h`](ProducerConsumerQueue.md)
 176
 177 Lock free single-reader, single-writer queue.
 178
 179 #### `Random.h`
 180
 181 Defines only one function---`randomNumberSeed()`.
 182
 183 #### `Range.h`
 184
 185 Boost-style range facility and the `StringPiece` specialization.
 186
 187 #### `RWSpinLock.h`
 188
 189 Fast and compact reader-writer spin lock.
 190
 191 #### `ScopeGuard.h`
 192
 193 C++11 incarnation of the old [ScopeGuard](http://drdobbs.com/184403758) idiom.
 194
 195 #### `Singleton.h`
 196
 197 A singleton to rule the singletons. This is an attempt to insert a layer between
 198 C++ statics and the fiasco that ensues, so that things can be created, and destroyed,
 199 correctly upon program creation, program end and sometimes `dlopen` and `fork`.
 200
 201 Singletons are bad for you, but this may help.
 202
 203 #### [`SmallLocks.h`](SmallLocks.md)
 204
 205 Very small spin locks (1 byte and 1 bit).
 206
 207 #### `small_vector.h`
 208
 209 Vector with the small buffer optimization and an optional embedded
 210 `PicoSpinLock`.
 211
 212 #### `sorted_vector_types.h`
 213
 214 Collections similar to `std::map` but implemented as sorted vectors.
 215
 216 #### `stats/`
 217
 218 A collection of efficient utilities for collecting statistics (often of
 219 time series data).
 220
 221 #### `StlAllocator.h`
 222
 223 STL allocator wrapping a simple allocate/deallocate interface.
 224
 225 #### `String.h`
 226
 227 String utilities that connect `folly::fbstring` with `std::string`.
 228
 229 #### `Subprocess.h`
 230
 231 Subprocess library, modeled after Python's subprocess module.
 232
 233 #### [`Synchronized.h`](Synchronized.md)
 234
 235 High-level synchronization library.
 236
 237 #### `System.h`
 238
 239 Demangling and errno utilities.
 240
 241 #### [`ThreadCachedInt.h`](ThreadCachedInt.md)
 242
 243 High-performance atomic increment using thread caching.
 244
 245 #### [`ThreadLocal.h`](ThreadLocal.md)
 246
 247 Improved thread local storage for non-trivial types.
 248
 249 #### `TimeoutQueue.h`
 250
 251 Queue with per-item timeout.
 252
 253 #### `Traits.h`
 254
 255 Type traits that complement those defined in the standard C++11 header
 256 `<traits>`.
 257
 258 #### `Unicode.h`
 259
 260 Defines the `codePointToUtf8` function.
 261
 262 #### `Uri.h`
 263
 264 A collection of utilities to deal with URIs.