YBC - Yet another Blob Cache library.

This library implements fast in-process blob cache with persistence support.


===============================================================================

YBC features.

* Huge amounts of data can be cached. Cache size may exceed available RAM size
  by multiple orders of magnitude.
  * Very large objects may be cached (up to 2^64 bytes). Think of media files
    such as videos, audios and images.
  * Very large cache size is supported (up to 2^64 items and up to 2^64 bytes).
    In practice cache size is limited by free space on backing store,
    not by available RAM size.

* Persistence support. Cached objects survive process restart if the cache
  is explicitly backed by files.

* Data file layout is optimized for HDD and SSD devices. The code
  prefers sequential I/O instead of random I/O. If random I/O is inevitable,
  the code tries hard localizing it in the smallest possible memory region.

* Automatic robust recovery from corrupted index files. Corruptions in data
  files may be left unnoticed due to performance reasons - it may be quite
  expensive validating multi-GB blobs on every access.

* Built-in handling of dogpile effect (aka 'thundering herd').

* Cached objects may be sharded among available backing store devices.
  Such sharding may linearly increase cache performance if frequently accessed
  items don't fit available physical RAM.

* The library is thread-safe out of the box.

* Concurrent atomic updates. It is safe updating an item from multiple threads
  while other threads are reading old value for the item under the same key.

* 'Add transaction' support allows constructing object's value on the fly
  without serializing it into a temporary buffer (aka 'zero-copy').
  Uncommited transaction can be rolled back at any time.
  Think of videos streamed directly into the cache without usage of temporary
  buffers or complex objects requiring serialization from multiple distinct
  places before storing them into the cache.

* Readers and writers don't block each other while reading/writing data
  from/into the cache. The speed is actually limited by hardware memory
  bandwidth (if frequently accessed items fit RAM) or backing store
  random I/O bandwidth (if requently accessed items don't fit RAM).

* Instant invalidation of all items in the cache irregardless of cache size.

* Optimization for multi-tiered memory hierarchy in modern CPUs. The code avoids
  unnecessary random memory accesses and tightly packs frequently accessed data
  in order to reduce working set size and increase CPU cache hit ratio.

* The code avoids using dynamic memory allocations in frequently executed paths,
  so cache performance is almost independent of the efficiency of the provided
  malloc() implementation.

* The code avoids using expensive system calls in frequently executed paths.

* The code depends only on OS-supplied libraries.

* The code can be easily ported to new platforms. All platform-specific
  functions and types are hidden behind platform-independent wrappers.

* Public interface (ybc.h) is designed with future versions' compatibility
  in mind. It doesn't expose private structures' contents, so they can be freely
  modified in the future versions of the library without breaking applications
  dynamically linked against older versions.

* Small library size (can be packed to 22Kb with -Os).


===============================================================================

Use-cases.

* CDN cache.

* File hosting cache.

* Memcache-like shared cache.

* Per-process local cache in web-servers.

* Web-proxy or web-accelerator cache.

* Web-browser cache.

* Out-of-GC blob cache for programming languages with GC support.


================================================================================

Credits.

YBC design is inspired by Varnish's "Notes from the Architect" -
https://www.varnish-cache.org/trac/wiki/ArchitectNotes .


================================================================================

FAQ.

Q: Give me performance numbers!
A: Well, YBC achieves 25.8 Mops/s for get() calls and 5.8 Mops/s for set() calls
   on my not-so-fast laptop with 2.50GHz Intel i5 CPU when running in 4 threads.

Q: Does YBC work with /dev/shm/ ?
A: Yes. Just create data and index files on /dev/shm . This will completely
   eliminate page swapping at the cost of potential data loss on power failure
   or computer reboot.

Q: Is this yet another boring cache implementation?
A: No. YBC is designed for modern OSes running on modern hardware. It takes
   advantage of OS's and computer's hardware features, while simultaneouly
   avoiding their weaknesses. This results in high performance and low resource
   usage. Read 'Features' chapter for more details.

Q: OK, how to use it in my program?
A:   1. Investigate API provided by YBC at ybc.h . See tests/ folder
        for examples on how to properly use the API.
     2. Use this API in your program.
     3. Build either object file (ybc-[32|64]-[debug|release].o) or library
        (libybc-[debug|release].so) using the corresponding build target
        in the provided Makefile.
     4. Link the object file or library against your program.
     5. ?????
     6. PROFIT!!!

   Take a look also at bindings/ folder. It contains YBC bindings for various
   programming languages if you don't like programming in C. Though currently
   only Go is supported :)

   Other folders also worth investigation:
     * libs/ folder contains additional libraries built on top of YBC.
     * apps/ folder contains applications built on top of YBC. Currently
       there are the following apps here with self-describing names:
         * cdn-booster - caching HTTP proxy implementation on top
           of Go bindings.
         * cdn-booster-bench - benchmark tool for HTTP/1.1-compliant servers.
         * memcached - memcache server implementation on top of Go bindings
           for YBC. Unlike the original memcache server, it supports cache
           sizes exceeding available RAM by multiple orders of magnitude.
           It also provides cache persistence, so cached data survives server
           restarts or server crashes.
         * memcached-bench - benchmark tool for memcached servers.
   Makefile already contains build targets for all these apps.

Q: Why recently added items may disappear from the cache, while their ttl isn't
   expired yet?
A: Because YBC is a cache, not a storage. They serve different pruposes:
   - Storage is used for items' persistence. It guarantees that added items
     exist until they are explicitly deleted.
   - Cache is used as a performance booster. It doesn't guarantee that added
     items exist until they are explicitly deleted.
   YBC may delete any item at any time due to various reasons, which depend
   on implementation details. So always expect that the added item may disappear
   at any time during subsequent requests.

Q: Can YBC cache small items, not large blobs?
A: Yes. YBC works well with small items - it even supports zero-byte key and
   zero-byte value.

Q: Why YBC cannot adjust backing files' size on-demand? I.e. automatically
   shrink files when the number of items in the cache is small and automatically
   expand files when the number of items exceeds current files' capacity.
A: Because this is stupid idea due to the following reasons:
   - If cache size isn't bound, then backing files may eat all the available
     space on storage devices.
   - Automatic file size adjustment may significantly increase file
     fragmentation, which will lead to performance degradation.
   - File size adjustment may lead to arbitrary long delays in requests'
     serving.
   - This will complicate the implementation, which may result in more bugs.

Q: What's the purpose of cache persistence?
A: Cache persistence allows skipping cache warm-up step ater the application
   restart. This step can be very expensive and time-consuming for large caches
   and slow backends. You can also make a 'golden' copy of a persistent cache
   and start every node in the application cluster using their own copy
   of the 'golden' cache, thus avoiding warm-up step on all nodes
   in the cluster.

Q: How well YBC performance scales on multiple CPUs?
A: It scales perfectly if specially designed functions are used -
   ybc_config_disable_overwrite_protection(), ybc_simple_set()
   and ybc_simple_get().

Q: Are cache files platform-neutral?
A: No. Cache files are tightly tied to the platform they were created.
   Cache files created on one platform (for example, x86) will be completely
   broken when read on another platform (for example, x64). Though it is likely
   they will appear as empty.
   So copy cache files only between machines with identical platforms.