doc: add docs for 0.12, setup versioning (#18)

* doc: add docs for 0.12, setup versioning

Signed-off-by: MrCroxx <[email protected]>

* chore: update deps

Signed-off-by: MrCroxx <[email protected]>

---------

Signed-off-by: MrCroxx <[email protected]>

Author: MrCroxx

docs/02-tutorial/01-in-memory-cache.md

@@ -15,13 +15,13 @@ The hybrid cache `HybridCache` also provides a in-memory only mode. If you want
 Add this line to the `[dependencies]` section of your project's `Cargo.toml`.
 
 ```toml
-foyer = "0.11"
+foyer = "0.12"
 ```
 
 If you are using a nightly version of the rust toolchain, the `nightly` feature is needed.
 
 ```toml
-foyer = { version = "0.11", features = ["nightly"] }
+foyer = { version = "0.12", features = ["nightly"] }
 ```
 
 ## 2. Build a `Cache`

docs/02-tutorial/02-hybrid-cache.md

@@ -11,13 +11,13 @@ Let get through it!
 Add this line to the `[dependencies]` section of your project's `Cargo.toml`.
 
 ```toml
-foyer = "0.11"
+foyer = "0.12"
 ```
 
 If you are using a nightly version of the rust toolchain, the `nightly` feature is needed.
 
 ```toml
-foyer = { version = "0.11", features = ["nightly"] }
+foyer = { version = "0.12", features = ["nightly"] }
 ```
 
 ## 2. Build a `HybridCache`
@@ -58,13 +58,31 @@ The default configuration count the usage by entry count. If you needs to change
 
 ### 2.3 Build disk cache
 
-#### 2.3.1 Run on in-memory cache compatible mode
+After setting up the in-memory cache, you can move on to setup the disk cache.
 
-After setting up the in-memory cache, you can call `storage()` to move on to setup the disk cache.
+#### 2.3.1 Choose a proper engine
 
-```rust
-let mut builder = HybridCacheBuilder::new().memory(1024).storage();
-```
+To setup the disk cache, you need to choose a proper engine for your workload first. Currently, ***foyer*** support 3 kinds of engines:
+
+- `Engine::Large`: For cache entries larger than 2 KiB. Friendly to HDD/SSD while minimizing memory usage for indexing.
+- `Engine::Small`: For cache entries smaller than 2 KiB. A set-associated cache that does not use memory for indexing.
+- `Engine::Mixed(ratio)`: For cache entries in all sizes. Mixed `Engine::Large` and `Engine::Small`. Use `ratio` to control the proportion of the capacity of `Engine::Small`. Introducing a little overhead compared to using `Engine::Large` and `Engine::Small` separately.
+
+For more details about the engines, please refer to [Design - Architecture](/docs/design/architecture).
+
+:::warning
+
+`Engine::Small` and `Engine::Mixed` are preview version and have **NOT** undergone sufficient testing in production environments. Please use them with caution in production systems.
+
+If you have such needs, you can contact me via Github. We can work together to improve the system for production and make ***foyer*** better! 🥰
+
+:::
+
+#### 2.3.2 Setup shared options
+
+Some options are shared between engines, you can setup shared options before setting up engine-specific options.
+
+##### 2.3.2.1 Setup device options
 
 By default, the hybrid cache will **NOT** include a disk cache unless you specify a device. The hybrid cache will run on a in-memory cache compatible mode with the default configuration. All lookups to the disk will return a miss. It is useful if you want to support both in-memory cache or the hybrid cache based on your project's configuration or for debugging.
 
@@ -74,9 +92,7 @@ RisingWave[^risingwave] supports caching the LSM-tree meta and blocks in both hy
 
 :::
 
-#### 2.3.2 Run on hybrid cache mode with a device
-
-To specify a device for the hybrid cache, just call `with_device_config()`[^with-device-config] and provide the device config.
+To enable the hybrid cache mode, a device needs to be specified by calling `with_device_options()`[^with-device-options] and providing the device options.
 
 Currently, the storage of the hybrid cache supports 2 kinds of devices:
 
@@ -97,28 +113,27 @@ Let's take `DirectFsDevice` as an example:
 let hybrid: HybridCache<u64, String> = HybridCacheBuilder::new()
     .with_name("foyer")
     .memory(1024)
-    .storage()
-    .with_device_config(DirectFsDeviceOptionsBuilder::new("/data/foyer").build())
+    .storage(Engine::Large)
+    .with_device_options(DirectFsDeviceOptions::new("/data/foyer"))
     .build()
     .await
     .unwrap();
 ```
 
 This example uses directory `/data/foyer` to store disk cache data using a device options builder. With the default configuration, ***foyer*** will take 80% of the current free space as the disk cache capacity. You can also specify the disk cache capacity and per file size with the builder.
 
-For more details, please refer to the API document.[^direct-fs-device-options-builder] [^direct-file-device-options-builder]
+For more details, please refer to the API document.[^direct-fs-device-options] [^direct-file-device-options]
 
-#### 2.3.3 Restrict the throughput
+##### 2.3.2.2 Restrict the throughput
 
 The bandwidth of the disk is much lower than the bandwidth of the memory. To avoid excessive use of the disk bandwidth, it is **HIGHLY RECOMMENDED** to setup the admission picker with a rate limiter.
 
 ```rust
 let hybrid: HybridCache<u64, String> = HybridCacheBuilder::new()
     .with_name("foyer")
     .memory(1024)
-    .storage()
-    .with_device_config(DirectFsDeviceOptionsBuilder::new("/data/foyer").build())
-    .with_admission_picker(Arc::new(RateLimitPicker::new(100 * 1024 * 1024)))
+    .storage(Engine::Large)
+    .with_device_options(DirectFsDeviceOptions::new("/data/foyer"))
     .build()
     .await
     .unwrap();
@@ -134,17 +149,32 @@ For more details, please refer to [Design - Architecture](/docs/design/architect
 
 :::
 
-#### 2.3.4 Achieve better performance
+##### 2.3.2.3 Other shared options
 
-The hybrid cache builder also provides a lot of detailed arguments for tuning.
+There are also other shared options for tuning or other purposes.
 
-For example:
+- `with_runtime_options()`: Set the runtime options to enable and setup the dedicated runtime.
+- `with_compression()`: Set the compression algorithm for serialization and deserialization.
+- `with_recover_mode()`: Set the recover mode.
+- `with_flush()`: Set if trigger a flush operation after writing the disk.
+- ...
 
-- `with_indexer_shards()` can be used for mitigating hot shards of the indexer.
-- `with_flushers()`, `with_reclaimers()` and `with_recover_concurrency()` can be used to tune the concurrency of the inner components.
-- `with_runtime_config()` can be used to enable the dedicated runtime or further runtime splitting.
+For more details, please refer to the API document.[^hybrid-cache-builder]
 
-Tuning the optimized parameters requires an understanding of ***foyer*** interior design and benchmarking with the real workload. For more details, please refer to [Design - Architecture](/docs/design/architecture).
+:::tip
+
+Tuning the optimized parameters requires an understanding of ***foyer*** interior design and benchmarking with the real workload. For more details, please refer to [Topic - Tuning](/docs/topic/tuning) and [Design - Architecture](/docs/design/architecture).
+
+:::
+
+#### 2.3.3 Setup engine-specific options
+
+Each engine also has its specific options for tuning or other purposes.
+
+- `with_large_object_disk_cache_options()`[^with-large-object-disk-cache-options]: Set the options for the large object disk cache.
+- `with_small_object_disk_cache_options()`[^with-small-object-disk-cache-options]: Set the options for the small object disk cache.
+
+For more details, please refer to the API document [^large-engine-options] [^small-engine-options].
 
 ## 3. `HybridCache` Usage
 
@@ -193,7 +223,7 @@ The hybrid cache also provides a `writer()` interface for advanced usage, such a
 
 [^risingwave]: https://github.com/risingwavelabs/risingwave
 
-[^with-device-config]: https://docs.rs/foyer/latest/foyer/struct.HybridCacheBuilderPhaseStorage.html#method.with_device_config
+[^with-device-options]: https://docs.rs/foyer/latest/foyer/struct.HybridCacheBuilderPhaseStorage.html#method.with_device_options
 
 [^direct-fs-device]: https://docs.rs/foyer/latest/foyer/struct.DirectFsDevice.html
 
@@ -203,8 +233,16 @@ The hybrid cache also provides a `writer()` interface for advanced usage, such a
 
 [^direct-fs-device-options-builder]: https://docs.rs/foyer/latest/foyer/struct.DirectFsDeviceOptionsBuilder.html
 
-[^direct-file-device-options-builder]: https://docs.rs/foyer/latest/foyer/struct.DirectFileDeviceOptionsBuilder.html
+[^direct-file-device-options]: https://docs.rs/foyer/latest/foyer/struct.DirectFileDeviceOptions.html
 
 [^admission-picker]: https://docs.rs/foyer/latest/foyer/trait.AdmissionPicker.html
 
-[^hybrid-cache-writer]: https://docs.rs/foyer/latest/foyer/struct.HybridCacheWriter.html
+[^hybrid-cache-writer]: https://docs.rs/foyer/latest/foyer/struct.HybridCacheWriter.html
+
+[^with-large-object-disk-cache-options]: https://docs.rs/foyer/latest/foyer/struct.HybridCacheBuilderPhaseStorage.html#method.with_large_object_disk_cache_options
+
+[^with-small-object-disk-cache-options]: https://docs.rs/foyer/latest/foyer/struct.HybridCacheBuilderPhaseStorage.html#method.with_small_object_disk_cache_options
+
+[^large-engine-options]: https://docs.rs/foyer/latest/foyer/struct.LargeEngineOptions.html
+
+[^small-engine-options]: https://docs.rs/foyer/latest/foyer/struct.SmallEngineOptions.html

docs/03-topic/03-tuning.md

@@ -0,0 +1,3 @@
+# Tuning
+
+***TBC ... ...***

docusaurus.config.ts

@@ -42,6 +42,7 @@ const config: Config = {
           // Remove this to remove the "edit this page" links.
           editUrl:
             'https://github.com/foyer-rs/website/tree/main/',
+          includeCurrentVersion: false,
         },
         blog: {
           showReadingTime: true,
@@ -83,6 +84,11 @@ const config: Config = {
         },
         { to: '/blog', label: 'Blog', position: 'left' },
         { to: '/blog/remote/CHANGELOG', label: 'Changelog', position: 'left' },
+        {
+          type: 'docsVersionDropdown',
+          docsPluginId: "default",
+          position: 'right',
+        },
         {
           href: 'https://crates.io/crates/foyer',
           label: 'crates.io',
@@ -161,6 +167,7 @@ const config: Config = {
       ],
       copyright: `Copyright © ${new Date().getFullYear()} foyer. Built with Docusaurus.`,
     },
+    tableOfContents: { minHeadingLevel: 3, maxHeadingLevel: 5 },
     prism: {
       theme: prismThemes.dracula,
       darkTheme: prismThemes.dracula,

package-lock.json

@@ -0,0 +1,105 @@
+# Overview
+
+<p align="center">
+  <img src="/img/logo/slogan.min.svg" style="width: 280px;" />
+</p>
+
+<div style="text-align: center;">
+
+![Website](https://img.shields.io/website?url=https%3A%2F%2Ffoyer.rs&up_message=foyer.rs&style=for-the-badge&logo=rust&labelColor=555555)
+![Crates.io Version](https://img.shields.io/crates/v/foyer?style=for-the-badge&logo=docs.rs&labelColor=555555)
+![docs.rs](https://img.shields.io/docsrs/foyer?style=for-the-badge&logo=docs.rs&labelColor=555555)
+
+</div>
+
+## What is foyer?
+
+***foyer***, just as its slogan, is a hybrid cache library for the Rust programming language. 🦀
+
+## What is hybrid cache?
+
+A hybrid cache is a caching system that utilizes both memory and disk storage simultaneously.
+
+<div style="text-align: center;">
+
+  ![hybrid cache](./assets/hybrid-cache.svg)
+  
+</div>
+
+It is commonly used to extend the insufficient memory cache for the system uses Object Store Service (OSS, e.g. AWS S3) as its primary data storage[^oss-dia] to **improve performance** and **reduce costs**[^risingwave].
+
+## Why we need a hybrid cache?
+
+More and more systems are using OSS as their primary data storage. OSS has many great features, such as low storage cost, high availability and durability, and almost unlimited scalability.
+
+However, there are also downsides with OSS. For example, the latency is high and uncontrollable, and its price increases with each accesses. The downsides will be further amplified in a large working set because of more data exchange between cache and OSS.
+
+<div style="text-align: center;">
+
+  ![exchange](./assets/exchange.svg)
+  
+</div>
+
+With a hybrid cache, the ability to cache the working set can be extended from memory only to memory and disk. This can reduce data exchange between cache and OSS, thereby improving performance and reducing costs.
+
+<div style="text-align: center;">
+
+  ![exchange hybrid cache](./assets/exchange-hybrid-cache.svg)
+
+</div>
+
+## Highlights of foyer
+
+As a hybrid cache, ***foyer*** provides the following highlighted features:
+
+- **Hybrid Cache**: Seamlessly integrates both in-memory and disk cache for optimal performance and flexibility.
+- **Plug-and-Play Algorithms**: Empowers users with easily replaceable caching algorithms, ensuring adaptability to diverse use cases.
+- **Fearless Concurrency**: Built to handle high concurrency with robust thread-safe mechanisms, guaranteeing reliable performance under heavy loads.
+- **Zero-Copy Abstraction**: Leveraging Rust's robust type system, the in-memory cache in foyer achieves a better performance with zero-copy abstraction.
+- **User-Friendly Interface**: Offers a simple and intuitive API, making cache integration effortless and accessible for developers of all levels.
+- **Out-of-the-Box Observability**: Integrate popular observation systems such as Prometheus, Grafana, Opentelemetry, and Jaeger in just **ONE** line.
+
+## Why use foyer, when you have 'X'?
+
+Unfortunately, there is currently no general proposed hybrid cache library in the Rust community. If you have a need for hybrid cache, ***foyer*** would be your best choice.
+
+CacheLib[^cachelib] provides a Rust binding. However, it only provides limited interfaces. You still need to patch the C++ codebase if you have requirements such as logging, metrics, or tracing supports. Besides, ***foyer*** provides a better optimized storage engine implement over CacheLib. You can try both ***foyer*** and CacheLib to compare the benchmarks.
+
+For the needs as an in-memory only cache, ***foyer*** also provides compatible interfaces and competitive performance. Benchmarks[^benchmark] show that ***foyer*** outperforms moka[^moka] and is only second to quick-cache[^quick-cache].
+
+<div style="text-align: center;">
+
+  ![benchmarks](./assets/benchmarks.svg)
+
+</div>
+
+## What's next?
+
+- Learn how to use ***foyer*** in your project, goto [Tutorial](/docs/category/tutorial).
+- Learn how to solve various challenging situations with ***foyer***, goto [Topic](/docs/category/topic).
+- Learn how other projects use ***foyer***, goto [Case Study](/docs/category/case-study).
+- Learn the design of ***foyer***, goto [Design](/docs/category/design).
+
+## Acknowledgement
+
+***foyer*** draws inspiration from CacheLib[^cachelib], a well-known cache library written in C++, and Caffeine[^caffeine], a widely-used in-memory cache library in Java, among other projects like moka[^moka], intrusive-rs[^intrusive-rs], etc.
+
+Thank you for your efforts! 🥰
+
+[^oss-dia]: Systems using OSS as its primary data storage: [RisingWave](https://github.com/risingwavelabs/risingwave), [Chroma Cloud](https://github.com/chroma-core/chroma), [SlateDB](https://github.com/slatedb/slatedb), etc.
+
+[^risingwave]: How streaming database RisingWave use foyer to improve performance and reduce costs: [Case Study - RisingWave](/docs/case-study/risingwave).
+
+[^cachelib]: [FaceBook/CacheLib](https://github.com/facebook/cachelib).
+
+[^benchmark]: Benchmark with mokabench[^mokabench]: [PR comments](https://github.com/moka-rs/mokabench/pull/20#issuecomment-2080429290).
+
+[^moka]: [moka-rs/moka](https://github.com/moka-rs/moka).
+
+[^quick-cache]: [arthurprs/quick-cache](https://github.com/arthurprs/quick-cache).
+
+[^caffeine]: [ben-manes/caffeine](https://github.com/ben-manes/caffeine).
+
+[^intrusive-rs]: [Amanieu/intrusive-rs](https://github.com/Amanieu/intrusive-rs).
+
+[^mokabench]: [moka-rs/mokabench](https://github.com/moka-rs/mokabench).