From cd18497b3b9c694b0181a297b6ef9c4016a3d9ca Mon Sep 17 00:00:00 2001 From: Croxx Date: Mon, 16 Sep 2024 21:01:07 +0800 Subject: [PATCH] doc: add docs for in-memory cache (#9) Signed-off-by: MrCroxx --- docs/01-overview/index.md | 3 - docs/02-tutorial/01-in-memory-cache.md | 118 +++++++++++++++++++++++++ docs/02-tutorial/01-setup.md | 50 ----------- docs/02-tutorial/02-hybrid-cache.md | 7 ++ docusaurus.config.ts | 3 + 5 files changed, 128 insertions(+), 53 deletions(-) create mode 100644 docs/02-tutorial/01-in-memory-cache.md delete mode 100644 docs/02-tutorial/01-setup.md create mode 100644 docs/02-tutorial/02-hybrid-cache.md diff --git a/docs/01-overview/index.md b/docs/01-overview/index.md index c5b60f1..34c2db3 100644 --- a/docs/01-overview/index.md +++ b/docs/01-overview/index.md @@ -18,7 +18,6 @@ A hybrid cache is a caching system that utilizes both memory and disk storage si - 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? @@ -27,7 +26,6 @@ More and more systems are using OSS as their primary data storage. OSS has many 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. -
![exchange](./assets/exchange.svg) @@ -36,7 +34,6 @@ However, there are also downsides with OSS. For example, the latency is high and 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. -
![exchange hybrid cache](./assets/exchange-hybrid-cache.svg) diff --git a/docs/02-tutorial/01-in-memory-cache.md b/docs/02-tutorial/01-in-memory-cache.md new file mode 100644 index 0000000..ce25077 --- /dev/null +++ b/docs/02-tutorial/01-in-memory-cache.md @@ -0,0 +1,118 @@ +# Setup In-memory Cache + +This article will guide you through the process of setting up an in-memory cache. + +:::tip for hybrid cache users + +The in-memory cache `Cache` is literally an in-memory only cache. Which provides non-overhead in-memory cache implement for users only want to replace their in-memory cache with ***foyer***, and cannot upgrade to a hybrid cache later. + +The hybrid cache `HybridCache` also provides a in-memory only mode. If you want to try ***foyer*** out with the in-memory mode and have the needs of a hybrid cache, please use `HybridCache`. See [Tutorial - Hybrid Cache](/docs/tutorial/hybrid-cache). + +::: + +## 1. Add foyer as a dependency + +Add this line to the `[dependencies]` section of your project's `Cargo.toml`. + +```toml +foyer = "0.11" +``` + +If you are using a nightly version of the rust toolchain, the `nightly` feature is needed. + +```toml +foyer = { version = "0.11", features = ["nightly"] } +``` + +## 2. Build a `Cache` + +### 2.1 Build with a builder + +`Cache`[^cache] can be built from `CacheBuilder`[^cache-builder]. For the default configuration, only `capacity` is required. + +```rust +use foyer::{Cache, CacheBuilder}; + +// ... ... + +let cache: Cache = CacheBuilder::new(16).build(); +``` + +### 2.2 Count entries by weight + +By default, `Cache` counts its usage for eviction by entry count. In the case below, which is 16. + +Counting by entry count may be not suitable for all cases. So, ***foyer*** also provides an interface to let the user decide how to count the usage. + +```rust +let cache: Cache = CacheBuilder::new(10000) + .with_weighter(|key, value| key.len() + value.len()) + .build(); +``` + +With `with_weighter`[^with-weighter], you can customize how `Cache` counts its usage. In the case below, the usage is counted by the total character length of the entry. + +The weighter can be implemented to count anything. Count, length, memory usage, or anything you want. + +### 2.3 Mitigate hot shards + +The in-memory cache in ***foyer*** is a sharded cache. Each shard is protected by an individual mutex. Sometimes, one or more shards can be much hotter than others and cause performance regression. + +There are two ways to mitigate the hot shards. + +1. Scale the shards + +Scaling the shard may reduce the possibility to create hot shards. You can scale the shards to a higher number with `with_shards`.[^with-shards] + +```rust +let cache: Cache = CacheBuilder::new(1024) + .with_shards(64) + .build(); +``` + +2. Use a customized hasher + +By default, ***foyer*** uses `ahash`[^ahash] as the hasher to determine which shard a key belongs to. You can use your own hasher with `with_hash_builder`.[^with-hash-builder] + +```rust +let cache: Cache = CacheBuilder::new(1024) + .with_hash_builder(CustomizedRandomState::default()) + .build(); +``` + +### 2.4 More configurations + +Please refer to the API document.[^cache-builder] + +## 3. Use `Cache` as any other cache library + +`Cache` provides familiar interface as any other cache library. + +Here is an example. + +```rust +use foyer::{Cache, CacheBuilder}; + +fn main() { + let cache: Cache = CacheBuilder::new(16).build(); + + let entry = cache.insert("hello".to_string(), "world".to_string()); + let e = cache.get("hello").unwrap(); + + assert_eq!(entry.value(), e.value()); +} +``` + +For other interfaces, please refer to the API document.[^cache] + +[^cache]: https://docs.rs/foyer/latest/foyer/enum.Cache.html + +[^cache-builder]: https://docs.rs/foyer/latest/foyer/struct.CacheBuilder.html + +[^with-weighter]: https://docs.rs/foyer/latest/foyer/struct.CacheBuilder.html#method.with_weighter + +[^with-shards]: https://docs.rs/foyer/latest/foyer/struct.CacheBuilder.html#method.with_shards + +[^ahash]: https://crates.io/crates/ahash + +[^with-hash-builder]: https://docs.rs/foyer/latest/foyer/struct.CacheBuilder.html#method.with_hash_builder \ No newline at end of file diff --git a/docs/02-tutorial/01-setup.md b/docs/02-tutorial/01-setup.md deleted file mode 100644 index 507efec..0000000 --- a/docs/02-tutorial/01-setup.md +++ /dev/null @@ -1,50 +0,0 @@ -# Setup - -***foyer***, just as its slogan, is a hybrid cache library for the Rust programming language. It provides a unified abstraction to utilize and manage cache on both memory and disk. - -***TBC ... ...*** - -***foyer*** draws inspiration from [Facebook/CacheLib](https://github.com/facebook/cachelib), a highly-regarded hybrid cache library in C++, and [ben-manes/caffeine](https://github.com/ben-manes/caffeine), a popular caching library in Java, among other projects. - - -Let's discover **Docusaurus in less than 5 minutes**. - -## Getting Started - -Get started by **creating a new site**. - -Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**. - -### What you'll need - -- [Node.js](https://nodejs.org/en/download/) version 18.0 or above: - - When installing Node.js, you are recommended to check all checkboxes related to dependencies. - -## Generate a new site - -Generate a new Docusaurus site using the **classic template**. - -The classic template will automatically be added to your project after you run the command: - -```bash -npm init docusaurus@latest my-website classic -``` - -You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor. - -The command also installs all necessary dependencies you need to run Docusaurus. - -## Start your site - -Run the development server: - -```bash -cd my-website -npm run start -``` - -The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there. - -The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/. - -Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes. diff --git a/docs/02-tutorial/02-hybrid-cache.md b/docs/02-tutorial/02-hybrid-cache.md new file mode 100644 index 0000000..6e7f249 --- /dev/null +++ b/docs/02-tutorial/02-hybrid-cache.md @@ -0,0 +1,7 @@ +# Setup Hybrid Cache + +This article will guide you through the process of setting up a hybrid cache. + +Setting up a hybrid is a little bit complex than setting up an in-memory cache, but not much. Let get through it! + +***TBC ... ...*** \ No newline at end of file diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 0f391b7..3dfeab5 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -169,6 +169,9 @@ const config: Config = { markdown: { format: 'detect', + remarkRehypeOptions: { + footnoteBackLabel: 'References', + } }, plugins: [