Greatly expand the components overview in Overview.md

Summary: See title. This is create a big flat mess, which I may clean up in a follow on to highlight the biggest and most generally useful libraries.

Reviewed By: fugalh

Differential Revision: D2902152

fb-gh-sync-id: 028633448ab97f47a3419f31fa58c79b77a89e52

diff --git a/folly/docs/Overview.md b/folly/docs/Overview.md
index 338ed09328467378bf0f82b02620342866921bd1..5722e2349aaa209800586b4ab0b9534ccd83ffcf 100644 (file)
--- a/folly/docs/Overview.md
+++ b/folly/docs/Overview.md
@@ -4,7 +4,7 @@ For a high level overview see the [README](folly/README.md)
 
 ### Components
 
-Below is a list of Folly components in alphabetical order, along with
+Below is a list of (some) Folly components in alphabetical order, along with
 a brief description of each.
 
 #### `Arena.h`, `ThreadCachedArena.h`
@@ -12,9 +12,17 @@ a brief description of each.
 Simple arena for memory allocation: multiple allocations get freed all
 at once. With threaded version.
 
-#### [`AtomicHashMap.h`, `AtomicHashArray.h`](AtomicHashMap.md)
+#### [`AtomicHashMap.h`, `AtomicHashArray.h`](AtomicHashMap.md), `AtomicHashArray.h`, `AtomicLinkedList.h`, ...
 
-High-performance atomic hash map with almost lock-free operation.
+High-performance atomic data-structures. Many of these are built with very specific
+tradeoffs and constraints in mind that make them faster than their more general
+counterparts. Each header should contain information about what these tradeoffs are.
+
+#### `Baton.h`
+
+A Baton allows a thread to block once and be awoken: it captures a single handoff. It is
+essentially a (very small, very fast) semaphore that supports only a single call to `sem_call`
+and `sem_wait`.
 
 #### [`Benchmark.h`](Benchmark.md)
 
@@ -43,6 +51,10 @@ by Herlihy et al.
 A variety of data conversion routines (notably to and from string),
 optimized for speed and safety.
 
+#### `Demangle.h`
+
+Pretty-printing C++ types.
+
 #### `DiscriminatedPtr.h`
 
 Similar to `boost::variant`, but restricted to pointers only. Uses the
@@ -51,21 +63,13 @@ highest-order unused 16 bits in a pointer as discriminator. So
 
 #### [`dynamic.h`](Dynamic.md)
 
-Dynamically-typed object, created with JSON objects in mind.
-
-#### `Endian.h`
-
-Endian conversion primitives.
-
-####`Escape.h`
-
-Escapes a string in C style.
+Dynamically-typed object, created with JSON objects in mind. `DynamicConverter.h` is
+a utility for effeciently converting from a `dynamic` to a more concrete structure when
+the scheme is known (e.g. json -> `map<int,int>`).
 
-####`eventfd.h`
+#### `EvictingCacheMap.h`
 
-Wrapper around the
-[`eventfd`](http://www.kernel.org/doc/man-pages/online/pages/man2/eventfd.2.html)
-system call.
+A simple LRU hash map.
 
 ####[`FBString.h`](FBString.md)
 
@@ -76,20 +80,42 @@ A drop-in implementation of `std::string` with a variety of optimizations.
 A mostly drop-in implementation of `std::vector` with a variety of
 optimizations.
 
-####`Foreach.h`
+#### `File.h`
 
-Pseudo-statements (implemented as macros) for iteration.
+A C++ abstraction around files.
+
+#### `Fingerprint.h`
+
+Rabin fingerprinting.
+
+### [`futures/`](folly/futures/Readme.md)
+
+Futures is a framework for expressing asynchronous code in C++ using the Promise/Future pattern.
 
 ####[`Format.h`](Format.md)
 
 Python-style formatting utilities.
 
+#### `gen/`
+
+This library makes it possible to write declarative comprehensions for
+processing sequences of values efficiently in C++ akin to C#'s LINQ.
+
 ####[`GroupVarint.h`](GroupVarint.md)
 
 [Group Varint
 encoding](http://www.ir.uwaterloo.ca/book/addenda-06-index-compression.html)
 for 32-bit values.
 
+####`IpAddress.h`
+
+A collection of utilities to deal with IPAddresses, including ipv4 and ipv6.
+
+#### `io/`
+
+A collection of useful of abstractions for high-performance io. This is heavily relied upon
+in Facebook's internally networking code.
+
 ####`Hash.h`
 
 Various popular hash function implementations.
@@ -110,14 +136,23 @@ JSON serializer and deserializer. Uses `dynamic.h`.
 
 Wrappers around [`__builtin_expect`](http://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html).
 
-####`Malloc.h`
+####`Malloc.h`, `Memory.h`
 
 Memory allocation helpers, particularly when using jemalloc.
 
-####`MapUtil.h`
+####`MicroSpinLock.h`
+
+A really, *really* small spinlock for fine-grained locking of lots of teeny-tiny data.
 
-Helpers for finding items in associative containers (such as
-`std::map` and `std::unordered_map`).
+####`MPMCQueue.h`
+
+MPMCQueue<typename> is a high-performance bounded concurrent queue that
+supports multiple producers, multiple consumers, and optional blocking.
+The queue has a fixed capacity, for which all memory will be allocated
+ up front.
+
+The additional utility `MPMCPipeline.h` is an extension that lets you
+chain several queues together with processing steps in between.
 
 ####[`PackedSyncPtr.h`](PackedSyncPtr.md)
 
@@ -128,12 +163,6 @@ spin lock, and a 15-bit integral, all inside one 64-bit word.
 
 Necessarily evil stuff.
 
-####`PrettyPrint.h`
-
-Pretty-printer for numbers that appends suffixes of unit used: bytes
-(kb, MB, ...), metric suffixes (k, M, G, ...), and time (s, ms, us,
-ns, ...).
-
 ####[`ProducerConsumerQueue.h`](ProducerConsumerQueue.md)
 
 Lock free single-reader, single-writer queue.
@@ -154,6 +183,14 @@ Fast and compact reader-writer spin lock.
 
 C++11 incarnation of the old [ScopeGuard](http://drdobbs.com/184403758) idiom.
 
+####`Singleton.h`
+
+A singleton to rule the singletons. This is an attempt to insert a layer between
+C++ statics and the fiasco that ensues, so that things can be created, and destroyed,
+correctly upon program creation, program end and sometimes `dlopen` and `fork`.
+
+Singletons are bad for you, but this may help.
+
 ####[`SmallLocks.h`](SmallLocks.md)
 
 Very small spin locks (1 byte and 1 bit).
@@ -167,6 +204,11 @@ Vector with the small buffer optimization and an optional embedded
 
 Collections similar to `std::map` but implemented as sorted vectors.
 
+#### `stats/`
+
+A collection of efficient utilities for collecting statistics (often of
+time series data).
+
 ####`StlAllocator.h`
 
 STL allocator wrapping a simple allocate/deallocate interface.
@@ -207,3 +249,7 @@ Type traits that complement those defined in the standard C++11 header
 ####`Unicode.h`
 
 Defines the `codePointToUtf8` function.
+
+####`Uri.h`
+
+A collection of utilities to deal with URIs.
\ No newline at end of file