Document huge-page (HugeTLB) cache backing

Summary:
Documents the huge-page support added lower in this stack.

- `Cache_persistence.md`: adds a "Back the cache with huge pages (HugeTLB)"
  section covering `enableHugePages`, out-of-band pool provisioning, the
  SysV/temp/heap vs POSIX (hugetlbfs mount dir) distinction, and the
  cross-host-persistence limitation.
- `CacheLib_configs.md`: adds an `enableHugePages` bullet to the
  SharedMemoryManager config reference, next to `usePosixForShm`.

Reviewed By: AlnisM

Differential Revision: D113902667

fbshipit-source-id: d45539eb7ef492e9f30c9330d67e9ff2ea6bd7f2

Author: rlyerly

website/docs/Cache_Library_User_Guides/CacheLib_configs.md

@@ -16,6 +16,7 @@ The sections below list out the `config setters` in the order of the config they
 * SharedMemoryManager: The component that controls the shared memory (new, attaching, etc)
    * `enableCachePersistence`: setting cache directory.
    * `usePosixForShm`: setting whether to Posix.
+   * `enableHugePages`: back the slab memory and access-container hash tables with HugeTLB pages; the metadata segment stays on normal pages. Takes a huge-page size in bytes and for POSIX shm, a mounted `hugetlbfs` directory. The HugeTLB pool must be reserved out-of-band. See [Cache persistence](Cache_persistence) for details.
 * Memory allocator: The components that manages memory allocations. (Carving out slabs, pool managers)
    * `setDefaultAllocSizes`: set the default allocation sizes, by either supplying the sizes directly or specifying min, max, size factor and
    * `enableCachePersistence`: the baseAddr is used here as the slab base address (if supplied).

website/docs/Cache_Library_User_Guides/Cache_persistence.md

@@ -85,6 +85,30 @@ if (!attached) {
 ```
 
 
+## Back the cache with huge pages (HugeTLB)
+
+CacheLib can back the *slab memory (main cache)* and the *access-container hash tables* with [HugeTLB](https://docs.kernel.org/admin-guide/mm/hugetlbpage.html) pages to lower TLB pressure. Enable huge pages with `enableHugePages`, passing a huge-page size that the kernel supports (see available sizes in the subdirectories of `/sys/kernel/mm/hugepages`):
+
+```cpp
+Cache::Config config;
+config.setCacheSize(/* size of cache in bytes */);
+config.enableCachePersistence(/* directory for shared memory related metadata */);
+// Back slabs and hash tables with 2MB huge pages.
+config.enableHugePages(cachelib::PageSize(2 * 1024 * 1024));
+```
+
+The HugeTLB pool must be provisioned out-of-band by reserving pages via `/proc/sys/vm/nr_hugepages`, `hugeadm` or [kernel command line args](https://docs.kernel.org/admin-guide/mm/hugetlbpage.html). CacheLib only draws from the already-reserved pool and fails cache creation if there aren't enough huge pages available.
+
+Huge pages are supported for SysV shared memory (the default), POSIX shared memory, temporary shared memory (cache with memory monitoring enabled but no persistence), and plain (non-persistent) heap memory with no memory monitoring. For POSIX shared memory you must also pass a mounted `hugetlbfs` directory as the second argument; cache creation throws if it is empty:
+
+```cpp
+config.enableCachePersistence(/* cache directory */)
+    .usePosixForShm()
+    .enableHugePages(cachelib::PageSize(2 * 1024 * 1024), "/mnt/hugetlbfs");
+```
+
+Huge pages are not supported with cross-host cache persistence.  They're also not supported with memory monitoring when the huge page size is bigger than the slab size - for example, you can't punch a slab-sized hole in a 1GB huge page.
+
 ## Drop persistent cache
 
 Sometimes you would like your cache to be not persistent when you restart your process. There are two ways to accomplish this: