folly

Folly: Foundational Open-source Library
=======================================

[![linux](https://github.com/meta/folly/actions/workflows/linux.yml/badge.svg)](https://github.com/meta/folly/actions/workflows/linux.yml)
[![macos](https://github.com/meta/folly/actions/workflows/macos.yml/badge.svg)](https://github.com/meta/folly/actions/workflows/macos.yml)
[![windows](https://github.com/meta/folly/actions/workflows/windows.yml/badge.svg)](https://github.com/meta/folly/actions/workflows/windows.yml)

# What is `folly`?

<img src="static/logo.svg" alt="Logo Folly" width="15%" align="right" />

Folly (originally an acronym for Facebook Open-source Library) is a
library of C++20 components designed with practicality and efficiency
in mind. **Folly contains a variety of core library components used extensively
at Meta**. In particular, it's often a dependency of Meta's other
open source C++ efforts and place where those projects can share code.

It builds on the C++ standard library and fills its gaps. We add a
component when the standard library doesn't provide it, or doesn't meet
the performance, scalability or interface Meta's code needs. When the
standard library provides an equivalent, we move folly and its users to
the standard one and keep the folly name only as long as users need it.

Performance concerns permeate much of Folly, sometimes leading to
designs that are more idiosyncratic than they would otherwise be (see
e.g. `PackedSyncPtr.h`, `SmallLocks.h`). Good performance at large
scale is a unifying theme in all of Folly.

## Check it out in the intro video
[![Explain Like I’m 5: Folly](https://img.youtube.com/vi/Wr_IfOICYSs/0.jpg)](https://www.youtube.com/watch?v=Wr_IfOICYSs)

# Logical Design

Folly is a collection of relatively independent components, some as
simple as a few symbols. There is no restriction on internal
dependencies, meaning that a given folly module may use any other
folly components.

All symbols are defined in the top-level namespace `folly`, except of
course macros. Macro names are ALL_UPPERCASE and should be prefixed
with `FOLLY_`. Namespace `folly` defines other internal namespaces
such as `internal` or `detail`. User code should not depend on symbols
in those namespaces.

# Physical Design

The sources live in the `folly/` directory, so headers are included
with the library name as a prefix, e.g. `#include <folly/Conv.h>`.

The directory structure is flat (mimicking the namespace structure),
i.e. we don't have an elaborate directory hierarchy (it is possible
this will change in future versions). The subdirectory `experimental`
contains files that are used inside folly and possibly at Meta but
not considered stable enough for client use. Your code should not use
files in `folly/experimental` lest it may break when you update Folly.

The `folly/test` subdirectory includes the unittests for all
components, usually named `ComponentXyzTest.cpp` for each
`ComponentXyz.*`. The `folly/docs` directory contains
documentatio