Foyer

https://docs.rs/foyer/0.22.3
Admin
Foyer is an efficient and user-friendly hybrid cache library in Rust that seamlessly integrates both...
Tokens:407,062
Snippets:3,166
Trust Score:9.7
Update:7 months ago
Show doc for...
Tokens:
Raw
### In-Memory Cache Setup in Rust

Source: https://docs.rs/foyer/0.22.3/foyer/index.html?search=

Demonstrates the straightforward setup of an in-memory cache using foyer's CacheBuilder. This example shows how to build a cache with a specified capacity and perform basic insert and get operations.

```rust
use foyer::{Cache, CacheBuilder};

let cache: Cache<String, String> = 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());
```

--------------------------------

### Hybrid Cache Setup in Rust

Source: https://docs.rs/foyer/0.22.3/foyer/index.html?search=

Illustrates the easy setup of a hybrid cache (in-memory and disk) using foyer's HybridCacheBuilder. This example configures a file system device for the disk cache and sets capacities for both memory and storage.

```rust
use foyer::{BlockEngineConfig, DeviceBuilder, FsDeviceBuilder, HybridCache, HybridCacheBuilder};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let dir = tempfile::tempdir()?;

    let device = FsDeviceBuilder::new(dir.path())
        .with_capacity(256 * 1024 * 1024)
        .build()?;

    let hybrid: HybridCache<u64, String> = HybridCacheBuilder::new()
        .memory(64 * 1024 * 1024)
        .storage()
        // use block-based disk cache engine with default configuration
        .with_engine_config(BlockEngineConfig::new(device))
        .build()
        .await?;

    hybrid.insert(42, "The answer to life, the universe, and everything.".to_string());
    assert_eq!(
        hybrid.get(&42).await?.unwrap().value(),
        "The answer to life, the universe, and everything."
    );

    Ok(())
}
```

--------------------------------

### Configure Fully Featured Hybrid Cache in Rust

Source: https://docs.rs/foyer/0.22.3/foyer/index.html?search=

Demonstrates a comprehensive hybrid cache setup in Rust using Foyer. It showcases various configuration options for storage, I/O, eviction policies, and spawner settings. This example requires the 'tokio' runtime.

```rust
use std::{hash::BuildHasherDefault, num::NonZeroUsize};

use foyer::{
    BlockEngineConfig,
    DeviceBuilder,
    FifoPicker,
    FsDeviceBuilder,
    HybridCache,
    HybridCacheBuilder,
    HybridCachePolicy,
    IopsCounter,
    LruConfig,
    PsyncIoEngineConfig,
    RecoverMode,
    RejectAll,
    StorageFilter,
    Throttle,
};
use tempfile::tempdir;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let dir = tempdir()?;

    let device = FsDeviceBuilder::new(dir.path())
        .with_capacity(64 * 1024 * 1024)
        .with_throttle(
            Throttle::new()
                .with_read_iops(4000)
                .with_write_iops(2000)
                .with_write_throughput(100 * 1024 * 1024)
                .with_read_throughput(800 * 1024 * 1024)
                .with_iops_counter(IopsCounter::PerIoSize(NonZeroUsize::new(128 * 1024).unwrap())),
        )
        .build()?;

    let hybrid: HybridCache<u64, String> = HybridCacheBuilder::new()
        .with_name("my-hybrid-cache")
        .with_policy(HybridCachePolicy::WriteOnEviction)
        .memory(1024)
        .with_shards(4)
        .with_eviction_config(LruConfig {
            high_priority_pool_ratio: 0.1,
        })
        .with_hash_builder(BuildHasherDefault::default())
        .with_weighter(|_key, value: &String| value.len())
        .with_filter(|_, _| true)
        .storage()
        .with_io_engine_config(PsyncIoEngineConfig::new())
        .with_engine_config(
            BlockEngineConfig::new(device)
                .with_block_size(16 * 1024 * 1024)
                .with_indexer_shards(64)
                .with_recover_concurrency(8)
                .with_flushers(2)
                .with_reclaimers(2)
                .with_buffer_pool_size(256 * 1024 * 1024)
                .with_clean_block_threshold(4)
                .with_eviction_pickers(vec![Box::<FifoPicker>::default()])
                .with_admission_filter(StorageFilter::new())
                .with_reinsertion_filter(StorageFilter::new().with_condition(RejectAll))
                .with_tombstone_log(false),
        )
        .with_recover_mode(RecoverMode::Quiet)
        .with_compression(foyer::Compression::Lz4)
        .with_spawner(
            tokio::runtime::Builder::new_multi_thread()
                .enable_all()
                .worker_threads(4)
                .max_blocking_threads(2)
                .build()
                .unwrap()
                .into(),
        )
        .build()
        .await?;

    hybrid.insert(42, "The answer to life, the universe, and everything.".to_string());
    assert_eq!(
        hybrid.get(&42).await?.unwrap().value(),
        "The answer to life, the universe, and everything."
    );

    let e = hybrid
        .get_or_fetch(&20230512, || async {
            // Mock fetching data from remote source
            let now = jiff::Zoned::now();
            if format!("{}{}{}", now.year(), now.month(), now.day()) == "20230512" {
                return Err(anyhow::anyhow!("Hi, time traveler!"));
            }
            Ok("Hello, foyer.".to_string())
        })
        .await?;
    assert_eq!(e.key(), &20230512);
    assert_eq!(e.value(), "Hello, foyer.");

    hybrid.close().await?;
    Ok(())
}

```

--------------------------------

### Rust Documentation Search Examples

Source: https://docs.rs/foyer/0.22.3/foyer/struct.FifoPicker.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides examples of effective search queries for finding Rust documentation. These examples cover searching for specific types, type conversions, and generic types with associated functions.

```text
std::vec
u32 -> bool
Option<T>, (T -> U) -> Option<U>
```

--------------------------------

### Rust Crate Setup and Imports (foyer/lib.rs)

Source: https://docs.rs/foyer/0.22.3/src/foyer/lib.rs.html?search=

This Rust code snippet from foyer/lib.rs demonstrates the basic setup of a crate. It includes license information, feature flags for nightly and documentation compilation, and imports modules from foyer_common, foyer_memory, and foyer_storage. It also re-exports items from the prelude module.

```rust
1// Copyright 2026 foyer Project Authors
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15#![doc = include_str!(concat!(env!("OUT_DIR"), "/foyer-docs.md"))]
16#![cfg_attr(feature = "nightly", feature(allocator_api))]
17#![cfg_attr(docsrs, feature(doc_cfg))]
18
19use foyer_common as common;
20use foyer_memory as memory;
21use foyer_storage as storage;
22
23mod hybrid;
24
25mod prelude;
26pub use prelude::*;

```

--------------------------------

### Rust Example Searches for Types and Signatures

Source: https://docs.rs/foyer/0.22.3/foyer/struct.Block.html?search=

Provides examples of common search queries used to find information about Rust types and function signatures. These examples illustrate how to search for standard library types like `std::vec`, primitive type conversions like `u32 -> bool`, and generic function transformations such as `Option<T>, (T -> U) -> Option<U>`.

```text
Example searches:
  * std::vec
  * u32 -> bool
  * Option<T>, (T -> U) -> Option<U>
```

--------------------------------

### Configure Hybrid Cache with Foyer in Rust

Source: https://docs.rs/foyer/0.22.3/foyer

Demonstrates a comprehensive hybrid cache setup using Foyer in Rust. It configures storage, I/O engines, eviction policies, compression, and spawner settings. This example requires the `tokio` and `tempfile` crates.

```rust
use std::{hash::BuildHasherDefault, num::NonZeroUsize};

use foyer::{
    BlockEngineConfig, DeviceBuilder, FifoPicker, FsDeviceBuilder, HybridCache, HybridCacheBuilder, HybridCachePolicy,
    IopsCounter, LruConfig, PsyncIoEngineConfig, RecoverMode, RejectAll, StorageFilter, Throttle,
};
use tempfile::tempdir;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let dir = tempdir()?;

    let device = FsDeviceBuilder::new(dir.path())
        .with_capacity(64 * 1024 * 1024)
        .with_throttle(
            Throttle::new()
                .with_read_iops(4000)
                .with_write_iops(2000)
                .with_write_throughput(100 * 1024 * 1024)
                .with_read_throughput(800 * 1024 * 1024)
                .with_iops_counter(IopsCounter::PerIoSize(NonZeroUsize::new(128 * 1024).unwrap())),
        )
        .build()?;

    let hybrid: HybridCache<u64, String> = HybridCacheBuilder::new()
        .with_name("my-hybrid-cache")
        .with_policy(HybridCachePolicy::WriteOnEviction)
        .memory(1024)
        .with_shards(4)
        .with_eviction_config(LruConfig {
            high_priority_pool_ratio: 0.1,
        })
        .with_hash_builder(BuildHasherDefault::default())
        .with_weighter(|_key, value: &String| value.len())
        .with_filter(|_, _| true)
        .storage()
        .with_io_engine_config(PsyncIoEngineConfig::new())
        .with_engine_config(
            BlockEngineConfig::new(device)
                .with_block_size(16 * 1024 * 1024)
                .with_indexer_shards(64)
                .with_recover_concurrency(8)
                .with_flushers(2)
                .with_reclaimers(2)
                .with_buffer_pool_size(256 * 1024 * 1024)
                .with_clean_block_threshold(4)
                .with_eviction_pickers(vec![Box::<FifoPicker>::default()])
                .with_admission_filter(StorageFilter::new())
                .with_reinsertion_filter(StorageFilter::new().with_condition(RejectAll))
                .with_tombstone_log(false),
        )
        .with_recover_mode(RecoverMode::Quiet)
        .with_compression(foyer::Compression::Lz4)
        .with_spawner(
            tokio::runtime::Builder::new_multi_thread()
                .enable_all()
                .worker_threads(4)
                .max_blocking_threads(2)
                .build()
                .unwrap()
                .into(),
        )
        .build()
        .await?;

    hybrid.insert(42, "The answer to life, the universe, and everything.".to_string());
    assert_eq!(
        hybrid.get(&42).await?.unwrap().value(),
        "The answer to life, the universe, and everything."
    );

    let e = hybrid
        .get_or_fetch(&20230512, || async {
            // Mock fetching data from remote source
            let now = jiff::Zoned::now();
            if format!("{}{}{}", now.year(), now.month(), now.day()) == "20230512" {
                return Err(anyhow::anyhow!("Hi, time traveler!"));
            }
            Ok("Hello, foyer.".to_string())
        })
        .await?;
    assert_eq!(e.key(), &20230512);
    assert_eq!(e.value(), "Hello, foyer.");

    hybrid.close().await?;
    Ok(())
}

```

--------------------------------

### Rust Example Searches

Source: https://docs.rs/foyer/0.22.3/foyer/type.Result.html?search=

These are example search queries demonstrating common patterns for exploring Rust's standard library and type system. They cover searching for specific types like `std::vec`, type conversions such as `u32 -> bool`, and generic type manipulation with `Option<T>`.

```rust
* std::vec
```

```rust
* u32 -> bool
```

```rust
* Option<T>, (T -> U) -> Option<U>
```

--------------------------------

### Rust: Cache Information and Utility Methods

Source: https://docs.rs/foyer/0.22.3/foyer/enum.Cache.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Illustrates Rust methods for retrieving information about the cache's state and utilities, such as clearing the cache, getting its capacity and current usage, counting entries, hashing keys, accessing the hash builder, and getting the number of shards.

```rust
pub fn clear(&self)
```

```rust
pub fn capacity(&self) -> usize
```

```rust
pub fn usage(&self) -> usize
```

```rust
pub fn entries(&self) -> usize
```

```rust
pub fn hash<Q>(&self, key: &Q) -> u64
where
    Q: Hash + ?Sized,
```

```rust
pub fn hash_builder(&self) -> &Arc<S>
```

```rust
pub fn shards(&self) -> usize
```

--------------------------------

### Create New CombinedDeviceBuilder (Rust)

Source: https://docs.rs/foyer/0.22.3/foyer/struct.CombinedDeviceBuilder.html?search=

Creates a new instance of `CombinedDeviceBuilder` with an empty set of devices. This is the starting point for building a combined device.

```rust
pub fn new() -> CombinedDeviceBuilder
```

--------------------------------

### Transition to Disk Cache Configuration in Rust

Source: https://docs.rs/foyer/0.22.3/foyer/struct.HybridCacheBuilderPhaseMemory.html?search=

Returns a builder for configuring the disk cache, allowing for a continuation of the cache setup process from in-memory to disk.

```rust
pub fn storage(self) -> HybridCacheBuilderPhaseStorage<K, V, S>
```

--------------------------------

### Create New HybridCacheBuilder (Rust)

Source: https://docs.rs/foyer/0.22.3/foyer/struct.HybridCacheBuilder.html

Instantiates a new HybridCacheBuilder. This is the starting point for configuring a hybrid cache.

```rust
pub fn new() -> Self
```

--------------------------------

### FsDeviceBuilder::new - Initialize FsDeviceBuilder

Source: https://docs.rs/foyer/0.22.3/foyer/struct.FsDeviceBuilder.html

Creates a new FsDeviceBuilder instance. It takes a path as input, which will be used as the base directory for the file device. This is the starting point for configuring a new filesystem device.

```rust
pub fn new(dir: impl AsRef<Path>) -> FsDeviceBuilder
```

--------------------------------

### Spawner Blanket Implementations (Examples)

Source: https://docs.rs/foyer/0.22.3/foyer/enum.Spawner.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Showcases various blanket implementations for `Spawner`, demonstrating its compatibility with traits like `Any`, `Borrow`, `CloneToUninit`, `From`, `Instrument`, `Into`, `IntoEither`, `Scope`, `ToOwned`, and `TryFrom`/`TryInto`. These highlight its generic capabilities.

```rust
impl<T> Any for T
where
    T: 'static + ?Sized,
```

```rust
impl<T, U> TryInto<U> for T
where
    U: TryFrom<T>,
```

```rust
impl<T> Scope for T
```

```rust
impl<T> ToOwned for T
where
    T: Clone,
```

--------------------------------

### Implement Default for PsyncIoEngineConfig (Rust)

Source: https://docs.rs/foyer/0.22.3/foyer/struct.PsyncIoEngineConfig.html

Implements the `Default` trait for PsyncIoEngineConfig, allowing instances to be created using the `default()` method. This provides a convenient way to get a default configuration.

```rust
fn default() -> PsyncIoEngineConfig {
    PsyncIoEngineConfig {}
}

```

--------------------------------

### Rust Crate Setup in lib.rs

Source: https://docs.rs/foyer/0.22.3/src/foyer/lib.rs.html?search=std%3A%3Avec

This Rust code snippet from lib.rs demonstrates the initialization of the foyer crate. It includes the crate's main documentation from an external file and conditionally enables features like 'allocator_api' and 'doc_cfg' based on build configurations. It also imports and re-exports modules from foyer_common, foyer_memory, and foyer_storage, along with a local 'hybrid' module and a 'prelude' for common usage.

```rust
1// Copyright 2026 foyer Project Authors
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15#![doc = include_str!(concat!(env!("OUT_DIR"), "/foyer-docs.md"))]
16#![cfg_attr(feature = "nightly", feature(allocator_api))]
17#![cfg_attr(docsrs, feature(doc_cfg))]
18
19use foyer_common as common;
20use foyer_memory as memory;
21use foyer_storage as storage;
22
23mod hybrid;
24
25mod prelude;
26pub use prelude::*;
```

--------------------------------

### PartialDeviceBuilder - Build Method

Source: https://docs.rs/foyer/0.22.3/foyer/struct.PartialDeviceBuilder.html?search=u32+-%3E+bool

Details on how to build the final device from the PartialDeviceBuilder.

```APIDOC
## Implementations

### impl DeviceBuilder for PartialDeviceBuilder

#### fn build(self) -> Result<Arc<dyn Device>, Error>

##### Description
Build a device from the given configuration.

##### Method
POST

##### Endpoint
`/partial-device-builder/build`

##### Parameters

###### Request Body
- **self** (PartialDeviceBuilder) - Required - The partial device builder instance to build from.

##### Response

#### Success Response (200)
- **device** (Arc<dyn Device>) - The built device.

#### Error Response (400)
- **error** (Error) - An error occurred during the build process.

#### Response Example
```json
{
  "device": "..."
}
```
```

--------------------------------

### RangeBoundsExt Trait Definition and Methods in Rust

Source: https://docs.rs/foyer/0.22.3/foyer/trait.RangeBoundsExt.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Defines the RangeBoundsExt trait, which extends the standard RangeBounds trait in Rust. It includes methods for getting start and end bounds, manipulating bounds with default values, calculating range size, checking for empty or full ranges, and mapping range values. The trait has several trait bounds on the generic type T.

```rust
pub trait RangeBoundsExt<T>: RangeBounds<T>
where
    T: PartialOrd + Add<Output = T> + Sub<Output = T> + Clone + Copy + Send + Sync + 'static + ZeroOne,
{
    // Provided methods
    fn start(&self) -> Option<T> { ... }
    fn end(&self) -> Option<T> { ... }
    fn start_with_bound(&self, bound: T) -> T { ... }
    fn end_with_bound(&self, bound: T) -> T { ... }
    fn bounds(&self, range: Range<T>) -> Range<T> { ... }
    fn size(&self) -> Option<T> { ... }
    fn is_empty(&self) -> bool { ... }
    fn is_full(&self) -> bool { ... }
    fn map<F, R>(&self, f: F) -> (Bound<R>, Bound<R>)
       where F: Fn(&T) -> R { ... }
}
```

--------------------------------

### FileDeviceBuilder Initialization and Configuration

Source: https://docs.rs/foyer/0.22.3/foyer/struct.FileDeviceBuilder.html

Methods for initializing and configuring a FileDeviceBuilder. `new` sets the file path, `with_capacity` sets the storage size, `with_throttle` applies a throttle, and `with_direct` enables direct I/O on Linux.

```rust
pub fn new(path: impl AsRef<Path>) -> FileDeviceBuilder

pub fn with_capacity(self, capacity: usize) -> FileDeviceBuilder

pub fn with_throttle(self, throttle: Throttle) -> FileDeviceBuilder

pub fn with_direct(self, direct: bool) -> FileDeviceBuilder
```

--------------------------------

### Get Type ID (Rust)

Source: https://docs.rs/foyer/0.22.3/foyer/enum.Cache.html

Gets the `TypeId` of `self`. This is useful for runtime type introspection.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### PartialDeviceBuilder - Constructor and Capacity

Source: https://docs.rs/foyer/0.22.3/foyer/struct.PartialDeviceBuilder.html?search=u32+-%3E+bool

This section details how to create a new PartialDeviceBuilder and set its capacity.

```APIDOC
## PartialDeviceBuilder

### Description
Builder for a partial device that wraps another device and allows access to only a subset of capacity.

## Implementations

### impl PartialDeviceBuilder

#### pub fn new(device: Arc<dyn Device>) -> PartialDeviceBuilder

##### Description
Create a new partial device builder with the specified device.

##### Method
POST

##### Endpoint
`/partial-device-builder/new`

##### Parameters

###### Query Parameters
- **device** (Arc<dyn Device>) - Required - The device to wrap.

##### Response

#### Success Response (200)
- **PartialDeviceBuilder** (PartialDeviceBuilder) - The newly created partial device builder.

#### Response Example
```json
{
  "builder": "..."
}
```

#### pub fn with_capacity(self, capacity: usize) -> PartialDeviceBuilder

##### Description
Set the capacity of the partial device. The capacity must be less than or equal to the inner device’s capacity. The sum of all capacities of the inner device’s partial devices must be less than or equal to the inner device’s capacity.

##### Method
PUT

##### Endpoint
`/partial-device-builder/{capacity}`

##### Parameters

###### Path Parameters
- **capacity** (usize) - Required - The desired capacity for the partial device.

###### Query Parameters
- **self** (PartialDeviceBuilder) - Required - The current partial device builder instance.

##### Response

#### Success Response (200)
- **PartialDeviceBuilder** (PartialDeviceBuilder) - The updated partial device builder with the specified capacity.

#### Response Example
```json
{
  "builder": "..."
}
```
```

--------------------------------

### Rust: Configure Hybrid Get Tracing Threshold

Source: https://docs.rs/foyer/0.22.3/foyer/struct.TracingOptions.html

Sets the threshold duration for recording hybrid cache 'get' operations. This helps in identifying slow cache retrieval operations.

```rust
pub fn with_record_hybrid_get_threshold( self, threshold: Duration, ) -> TracingOptions
```

--------------------------------

### Start Span on Future Poll in Rust

Source: https://docs.rs/foyer/0.22.3/foyer/struct.HybridGetOrFetch.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Implements the `FutureExt::enter_on_poll` method. This starts a `LocalSpan` every time the future's `poll` method is called, creating short spans for each poll.

```rust
fn enter_on_poll(self, name: impl Into<Cow<'static, str>>) -> EnterOnPoll<Self>
```

--------------------------------

### PartialDeviceBuilder API

Source: https://docs.rs/foyer/0.22.3/foyer/struct.PartialDeviceBuilder.html?search=

Documentation for the PartialDeviceBuilder struct and its associated methods.

```APIDOC
## Struct PartialDeviceBuilder

### Description
Builder for a partial device that wraps another device and allows access to only a subset of capacity.

### Methods

#### `new(device: Arc<dyn Device>) -> PartialDeviceBuilder`

*   **Description**: Create a new partial device builder with the specified device.
*   **Method**: POST (conceptual, as this is a builder pattern)
*   **Endpoint**: N/A (struct method)
*   **Parameters**:
    *   **Path Parameters**: None
    *   **Query Parameters**: None
    *   **Request Body**: None

#### `with_capacity(self, capacity: usize) -> PartialDeviceBuilder`

*   **Description**: Set the capacity of the partial device. The capacity must be less than or equal to the inner device’s capacity. The sum of all capacities of the inner device’s partial devices must be less than or equal to the inner device’s capacity.
*   **Method**: POST (conceptual, as this is a builder pattern)
*   **Endpoint**: N/A (struct method)
*   **Parameters**:
    *   **Path Parameters**: None
    *   **Query Parameters**: None
    *   **Request Body**: None
    *   **field1**: `capacity` (usize) - Required - The desired capacity for the partial device.

#### `build(self) -> Result<Arc<dyn Device>, Error>`

*   **Description**: Build a device from the given configuration.
*   **Method**: POST (conceptual, as this is a builder pattern)
*   **Endpoint**: N/A (struct method)
*   **Parameters**:
    *   **Path Parameters**: None
    *   **Query Parameters**: None
    *   **Request Body**: None

### Response

#### Success Response (200)
*   **field1**: `Arc<dyn Device>` - The built partial device.

#### Error Response
*   **field1**: `Error` - An error occurred during the build process.
```

--------------------------------

### Get Cache Entry (Rust)

Source: https://docs.rs/foyer/0.22.3/foyer/struct.HybridCache.html

Retrieves a cache entry using its key. This method is generic and requires the key type `Q` to be hashable, equivalent to `K`, and convertible to `K`. It returns a `HybridGet` object, which represents the result of the get operation.

```rust
pub fn get<Q>(&self, key: &Q) -> HybridGet<K, V, S>
where
    Q: Hash + Equivalent<K> + ?Sized + ToOwned<Owned = K>,
```

--------------------------------

### Test Concurrent Get and Fetch Operations

Source: https://docs.rs/foyer/0.22.3/src/foyer/hybrid/cache.rs.html?search=

Tests the hybrid cache's ability to handle concurrent 'get' and 'get_or_fetch' operations for the same key. It uses barriers and a load holder to synchronize operations and ensures that both operations return the same data, even when one is waiting for the other to complete.

```rust
let dir = tempfile::tempdir().unwrap();

        let load_holder = Holder::default();
        let hybrid = open_with(dir.path(), |b| b, |b| b.with_load_holder(load_holder.clone())).await;

        // Test non-concurrent get returns none.
        assert!(hybrid.get(&42).await.unwrap().is_none());

        let barrier = Arc::new(Barrier::new(2));

        // Hold disk cache load to wait for fetch op.
        load_holder.hold();
        let get = hybrid.get(&42);
        let b = barrier.clone();
        let fetch = hybrid.get_or_fetch(&42, || async move {
            b.wait().await;
            Ok::<_, Error>(vec![b'x'; 42])
        });
        load_holder.unhold();

        // Release fetch to proceed.
        barrier.wait().await;
        // Poll get first.
        let r_get = get.await.unwrap();
        // Poll fetch later.
        let r_fetch = fetch.await.unwrap();
        assert_eq!(r_get.unwrap().value(), r_fetch.value());
```

--------------------------------

### Initialize BlockEngineConfig (Rust)

Source: https://docs.rs/foyer/0.22.3/foyer/struct.BlockEngineConfig.html

Creates a new BlockEngineConfig builder with default configurations. It requires an Arc<dyn Device> as input, representing the storage device for the cache.

```rust
pub fn new(device: Arc<dyn Device>) -> BlockEngineConfig<K, V, P>
```

--------------------------------

### Create New PsyncIoEngineConfig (Rust)

Source: https://docs.rs/foyer/0.22.3/foyer/struct.PsyncIoEngineConfig.html

Provides a constructor function `new()` for PsyncIoEngineConfig. This function creates a new instance of the configuration with default settings, ready for use with the synchronous I/O engine.

```rust
pub fn new() -> PsyncIoEngineConfig {
    PsyncIoEngineConfig {}
}

```

--------------------------------

### CacheProperties Methods

Source: https://docs.rs/foyer/0.22.3/foyer/struct.CacheProperties.html?search=u32+-%3E+bool

Methods available for the CacheProperties struct, including setting and getting hints.

```APIDOC
## impl CacheProperties

### `with_hint(self, hint: Hint) -> CacheProperties`

Set entry hint.

### `hint(&self) -> Hint`

Get entry hint.
```

--------------------------------

### Get Throttle Configuration in Rust

Source: https://docs.rs/foyer/0.22.3/foyer/struct.Statistics.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves a reference to the 'Throttle' configuration object associated with the statistics.

```rust
pub fn throttle(&self) -> &Throttle
```

--------------------------------

### Rust: Get foyer Error kind

Source: https://docs.rs/foyer/0.22.3/foyer/struct.Error.html

Provides a method to retrieve the `ErrorKind` from a `foyer::Error` instance.

```Rust
pub fn kind(&self) -> ErrorKind
Get the error kind.
```

--------------------------------

### CombinedDeviceBuilder API

Source: https://docs.rs/foyer/0.22.3/foyer/struct.CombinedDeviceBuilder.html

This section details the methods available for the CombinedDeviceBuilder, including initialization, adding devices, and configuring settings.

```APIDOC
## Struct CombinedDeviceBuilder

### Description
Builder for a combined device that wraps multiple devices and allows access to their blocks. The throttle and statistics of the combined device will override the inner devices’ throttles and statistics. NOTE: The kind of device is a preview, the throttle and statistics strategy is likely to be modified later.

### Methods

#### `new()`
- **Description**: Create a new combined device builder with empty devices.
- **Method**: `pub fn new() -> CombinedDeviceBuilder`

#### `with_device(device: Arc<dyn Device>)`
- **Description**: Add a device to the combined device builder.
- **Method**: `pub fn with_device(self, device: Arc<dyn Device>) -> CombinedDeviceBuilder`
- **Parameters**:
  - **device** (Arc<dyn Device>) - Required - The device to add.

#### `with_throttle(throttle: Throttle)`
- **Description**: Set the throttle for the combined device to override the inner devices’ throttles. The throttles of the combined devices are disabled by default.
- **Method**: `pub fn with_throttle(self, throttle: Throttle) -> CombinedDeviceBuilder`
- **Parameters**:
  - **throttle** (Throttle) - Required - The throttle configuration to apply.

#### `build()`
- **Description**: Build a device from the given configuration.
- **Method**: `fn build(self) -> Result<Arc<dyn Device>, Error>`
- **Returns**: A `Result` containing either an `Arc<dyn Device>` on success or an `Error` on failure.

### Trait Implementations

#### `Debug`
- **Description**: Formats the value using the given formatter.
- **Method**: `fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>`

#### `Default`
- **Description**: Returns the “default value” for a type.
- **Method**: `fn default() -> CombinedDeviceBuilder`
```

--------------------------------

### Get foyer Error Message

Source: https://docs.rs/foyer/0.22.3/foyer/struct.Error.html?search=u32+-%3E+bool

Returns a reference to the error message string associated with the `Error` instance.

```rust
pub fn message(&self) -> &str
```

--------------------------------

### NoopDeviceBuilder

Source: https://docs.rs/foyer/0.22.3/foyer/struct.NoopDeviceBuilder.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Provides methods for creating and configuring a no-operation mock device.

```APIDOC
## Struct NoopDeviceBuilder

### Description
Builder for a no-operation mock device.

### Methods

#### `new(capacity: usize) -> NoopDeviceBuilder`
Create a new no-operation mock device builder with the specified capacity.

### Implementations

#### `impl Debug for NoopDeviceBuilder`
##### `fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>`
Formats the value using the given formatter.

#### `impl Default for NoopDeviceBuilder`
##### `default() -> NoopDeviceBuilder`
Returns the “default value” for a type.

#### `impl DeviceBuilder for NoopDeviceBuilder`
##### `build(self) -> Result<Arc<dyn Device>, Error>`
Build a device from the given configuration.

### Auto Trait Implementations
- `Freeze`
- `RefUnwindSafe`
- `Send`
- `Sync`
- `Unpin`
- `UnwindSafe`

### Blanket Implementations
- `Any`
- `Borrow<T>`
- `BorrowMut<T>`
- `From<T>`
- `Instrument`
- `Into<U>`
- `IntoEither`
- `Scope`
- `TryFrom<U>`
- `TryInto<U>`
- `VZip<V>`
- `WithSubscriber`
- `Value`
```

--------------------------------

### Type ID Retrieval in Rust

Source: https://docs.rs/foyer/0.22.3/foyer/struct.Block.html?search=std%3A%3Avec

Provides a method to get the `TypeId` of a given type `T`. This is part of the `Any` trait implementation.

```Rust
fn type_id(&self) -> TypeId
Gets the `TypeId` of `self`. Read more
```

--------------------------------

### Get Spawner from foyer Store (Rust)

Source: https://docs.rs/foyer/0.22.3/foyer/struct.Store.html

Returns a reference to the spawner used for managing asynchronous tasks within the `Store`.

```rust
pub fn spawner(&self) -> &Spawner
```

--------------------------------

### Rust Crate Initialization and Configuration (foyer-0.22.3)

Source: https://docs.rs/foyer/0.22.3/src/foyer/lib.rs.html

This Rust code snippet initializes the foyer crate, sets up documentation features, and configures build attributes. It includes license information and re-exports essential modules like common, memory, and storage.

```rust
#![doc = include_str!(concat!(env!("OUT_DIR"), "/foyer-docs.md"))]
#![cfg_attr(feature = "nightly", feature(allocator_api))]
#![cfg_attr(docsrs, feature(doc_cfg))]

use foyer_common as common;
use foyer_memory as memory;
use foyer_storage as storage;

mod hybrid;

mod prelude;
pub use prelude::*;

```

--------------------------------

### Get foyer Error Backtrace

Source: https://docs.rs/foyer/0.22.3/foyer/struct.Error.html?search=u32+-%3E+bool

Returns an optional reference to the `Backtrace` associated with the `Error` instance, if one was captured.

```rust
pub fn backtrace(&self) -> Option<&Backtrace>
```

--------------------------------

### Get foyer Error Context

Source: https://docs.rs/foyer/0.22.3/foyer/struct.Error.html?search=u32+-%3E+bool

Retrieves the context associated with the `Error` instance as a vector of key-value string pairs.

```rust
pub fn context(&self) -> &Vec<(&'static str, String)>
```

--------------------------------

### NoopDeviceBuilder

Source: https://docs.rs/foyer/0.22.3/foyer/struct.NoopDeviceBuilder.html?search=

Provides functionality to build a no-operation mock device with a specified capacity.

```APIDOC
## Struct NoopDeviceBuilder

### Description
Builder for a no-operation mock device.

### Methods

#### `new(capacity: usize) -> NoopDeviceBuilder`
Create a new no-operation mock device builder with the specified capacity.

#### `build(self) -> Result<Arc<dyn Device>, Error>`
Build a device from the given configuration.

### Implementations

#### `Debug`
Formats the value using the given formatter.

#### `Default`
Returns the “default value” for a type.

#### `DeviceBuilder`
See `build` method description.

#### Auto Trait Implementations
- `Freeze`
- `RefUnwindSafe`
- `Send`
- `Sync`
- `Unpin`
- `UnwindSafe`

#### Blanket Implementations
- `Any`
- `Borrow<T>`
- `BorrowMut<T>`
- `From<T>`
- `Instrument`
- `Into<U>`
- `IntoEither`
- `Scope`
- `TryFrom<U>`
- `TryInto<U>`
- `VZip<V>`
- `WithSubscriber`
- `Value`
```

--------------------------------

### HybridCache Builder Initialization (Rust)

Source: https://docs.rs/foyer/0.22.3/src/foyer/hybrid/cache.rs.html?search=

Provides a static method `builder()` to create a new `HybridCacheBuilder`. This is the entry point for configuring and constructing a `HybridCache` instance with default hasher.

```Rust
impl<K, V> HybridCache<K, V, DefaultHasher>
where
    K: StorageKey,
    V: StorageValue,
{
    /// Create a new hybrid cache builder.
    pub fn builder() -> HybridCacheBuilder<K, V> {
        HybridCacheBuilder::new()
    }
}
```

--------------------------------

### Get foyer Error Kind

Source: https://docs.rs/foyer/0.22.3/foyer/struct.Error.html?search=u32+-%3E+bool

Retrieves the `ErrorKind` variant of the `Error` instance. This provides a categorized view of the error.

```rust
pub fn kind(&self) -> ErrorKind
```

--------------------------------

### Create NoopDeviceBuilder Instance in Rust

Source: https://docs.rs/foyer/0.22.3/foyer/struct.NoopDeviceBuilder.html

Provides a constructor function `new` for the NoopDeviceBuilder. This function initializes a new mock device builder with a specified capacity, which might influence internal resource allocation or behavior.

```rust
pub fn new(capacity: usize) -> NoopDeviceBuilder
```

--------------------------------

### Create New CacheBuilder in Rust

Source: https://docs.rs/foyer/0.22.3/foyer/struct.CacheBuilder.html?search=

Initializes a new CacheBuilder with a specified capacity. This is the starting point for configuring an in-memory cache.

```rust
pub fn new(capacity: usize) -> CacheBuilder<K, V, BuildHasherDefault<Hasher>>

```

--------------------------------

### Get Disk Cache IO Operations in Rust

Source: https://docs.rs/foyer/0.22.3/foyer/struct.Statistics.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves the number of disk cache Input/Output operations. Returns a 'usize' value.

```rust
pub fn disk_write_ios(&self) -> usize
```

```rust
pub fn disk_read_ios(&self) -> usize
```

--------------------------------

### NoopIoEngineConfig

Source: https://docs.rs/foyer/0.22.3/foyer/struct.NoopIoEngineConfig.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Configuration for a no-operation mock I/O engine.

```APIDOC
## Struct NoopIoEngineConfig

### Description
Config for a no-operation mock I/O engine.

### Method
N/A (Struct definition)

### Endpoint
N/A (Struct definition)

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### Trait Implementations

#### `Debug` for `NoopIoEngineConfig`
Formats the value using the given formatter.

#### `Default` for `NoopIoEngineConfig`
Returns the “default value” for a type.

#### `IoEngineConfig` for `NoopIoEngineConfig`
##### `build`
Build an I/O engine from the given configuration.

##### `boxed`
Box the config.

### Auto Trait Implementations
- `Freeze`
- `RefUnwindSafe`
- `Send`
- `Sync`
- `Unpin`
- `UnwindSafe`

### Blanket Implementations
- `Any`
- `Borrow`
- `BorrowMut`
- `From`
- `Instrument`
- `Into`
- `IntoEither`
- `Scope`
- `TryFrom`
- `TryInto`
- `VZip`
- `WithSubscriber`
- `Value`
```

--------------------------------

### PsyncIoEngineConfig

Source: https://docs.rs/foyer/0.22.3/foyer/struct.PsyncIoEngineConfig.html?search=

Configuration for a synchronous I/O engine using pread(2)/pwrite(2).

```APIDOC
## Struct PsyncIoEngineConfig

### Description
Config for synchronous I/O engine with pread(2)/pwrite(2).

### Methods

#### `new()`
```rust
pub fn new() -> PsyncIoEngineConfig
```
Create a new synchronous I/O engine config with default configurations.

### Trait Implementations

#### `Debug`
Formats the value using the given formatter.

#### `Default`
Returns the “default value” for a type.

#### `IoEngineConfig`

##### `build(self: Box<PsyncIoEngineConfig>, ctx: IoEngineBuildContext) -> Pin<Box<dyn Future<Output = Result<Arc<dyn IoEngine>, Error>> + Send>>`
Build an I/O engine from the given configuration.

##### `boxed(self) -> Box<Self>`
Box the config.

### Auto Trait Implementations
`Freeze`, `RefUnwindSafe`, `Send`, `Sync`, `Unpin`, `UnwindSafe`

### Blanket Implementations
`Any`, `Borrow`, `BorrowMut`, `From`, `Instrument`, `Into`, `IntoEither`, `Scope`, `TryFrom`, `TryInto`, `VZip`, `WithSubscriber`, `Value`
```

--------------------------------

### Get Disk Cache Bytes in Rust

Source: https://docs.rs/foyer/0.22.3/foyer/struct.Statistics.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Retrieves the number of bytes written to or read from the disk cache. Returns a 'usize' value.

```rust
pub fn disk_write_bytes(&self) -> usize
```

```rust
pub fn disk_read_bytes(&self) -> usize
```

--------------------------------

### Rust: Get foyer Error backtrace

Source: https://docs.rs/foyer/0.22.3/foyer/struct.Error.html

Provides a method to retrieve an optional reference to the `Backtrace` associated with a `foyer::Error` instance.

```Rust
pub fn backtrace(&self) -> Option<&Backtrace>
Get the error backtrace.
```

--------------------------------

### BlockEngineConfig Build Method

Source: https://docs.rs/foyer/0.22.3/foyer/struct.BlockEngineConfig.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Builds the block-based disk cache engine with the given configurations.

```APIDOC
## POST /websites/rs_foyer_0_22_3/build

### Description
Build the block-based disk cache engine with the given configurations.

### Method
POST

### Endpoint
/websites/rs_foyer_0_22_3/build

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **__arg1** (EngineBuildContext) - Required - The build context for the engine.

### Request Example
```json
{
  "__arg1": { ... } 
}
```

### Response
#### Success Response (200)
- **BlockEngineConfig** (Arc<BlockEngine<K, V, P>>) - A boxed and dynamically dispatched BlockEngineConfig.

#### Response Example
```json
{
  "engine": { ... } 
}
```
```

--------------------------------

### CacheProperties Struct

Source: https://docs.rs/foyer/0.22.3/foyer/struct.CacheProperties.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Represents entry properties for an in-memory cache. Provides methods to set and get hints, and manage phantom entries.

```APIDOC
## Struct CacheProperties

### Description
Entry properties for in-memory only cache.

### Methods

#### `with_hint(self, hint: Hint) -> CacheProperties`
Set entry hint.

#### `hint(&self) -> Hint`
Get entry hint.

#### `with_phantom(self, phantom: bool) -> CacheProperties`
Set entry as a phantom entry.

#### `phantom(&self) -> Option<bool>`
If the entry is a phantom entry.

#### `with_location(self, _: Location) -> CacheProperties`
Set entry location.

#### `location(&self) -> Option<Location>`
Entry location.

#### `with_age(self, _: Age) -> CacheProperties`
Set entry age.

#### `age(&self) -> Option<Age>`
Entry age.

### Implementations

#### `Clone`
- `clone(&self) -> CacheProperties`: Returns a duplicate of the value.
- `clone_from(&mut self, source: &Self)`: Performs copy-assignment from `source`.

#### `Debug`
- `fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>`: Formats the value using the given formatter.

#### `Default`
- `default() -> CacheProperties`: Returns the "default value" for a type.

#### `Properties`
(See methods listed under `CacheProperties` struct for `Properties` trait implementations)

### Auto Trait Implementations
- `Freeze`
- `RefUnwindSafe`
- `Send`
- `Sync`
- `Unpin`
- `UnwindSafe`

### Blanket Implementations
- `Any`
- `Borrow<T>`
- `BorrowMut<T>`
- `CloneToUninit` (Nightly-only experimental)
- `From<T>`
- `Instrument`
- `Into<U>`
- `IntoEither`
- `Scope`
- `ToOwned`
- `TryFrom<U>`
- `TryInto<U>`
```

--------------------------------

### Create FileDeviceBuilder with Path (Rust)

Source: https://docs.rs/foyer/0.22.3/foyer/struct.FileDeviceBuilder.html?search=

Initializes a new FileDeviceBuilder with a specified file path. The path can be any type that can be converted into a Path.

```rust
pub fn new(path: impl AsRef<Path>) -> FileDeviceBuilder
```

--------------------------------

### Configure Fully Featured Hybrid Cache in Rust

Source: https://docs.rs/foyer/0.22.3/index.html

Demonstrates the setup of a hybrid cache with extensive configuration options in Rust using the Foyer library. This includes defining storage capacity, I/O throttling, eviction policies, hashing, filtering, and recovery modes. It requires the `tokio` runtime for asynchronous operations.

```rust
use std::{hash::BuildHasherDefault, num::NonZeroUsize};

use foyer::{
    BlockEngineConfig, DeviceBuilder, FifoPicker, FsDeviceBuilder, HybridCache,
    HybridCacheBuilder, HybridCachePolicy, IopsCounter, LruConfig,
    PsyncIoEngineConfig, RecoverMode, RejectAll, StorageFilter, Throttle,
};
use tempfile::tempdir;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let dir = tempdir()?;

    let device = FsDeviceBuilder::new(dir.path())
        .with_capacity(64 * 1024 * 1024)
        .with_throttle(
            Throttle::new()
                .with_read_iops(4000)
                .with_write_iops(2000)
                .with_write_throughput(100 * 1024 * 1024)
                .with_read_throughput(800 * 1024 * 1024)
                .with_iops_counter(IopsCounter::PerIoSize(NonZeroUsize::new(128 * 1024).unwrap())),
        )
        .build()?;

    let hybrid: HybridCache<u64, String> = HybridCacheBuilder::new()
        .with_name("my-hybrid-cache")
        .with_policy(HybridCachePolicy::WriteOnEviction)
        .memory(1024)
        .with_shards(4)
        .with_eviction_config(LruConfig {
            high_priority_pool_ratio: 0.1,
        })
        .with_hash_builder(BuildHasherDefault::default())
        .with_weighter(|_key, value: &String| value.len())
        .with_filter(|_, _| true)
        .storage()
        .with_io_engine_config(PsyncIoEngineConfig::new())
        .with_engine_config(
            BlockEngineConfig::new(device)
                .with_block_size(16 * 1024 * 1024)
                .with_indexer_shards(64)
                .with_recover_concurrency(8)
                .with_flushers(2)
                .with_reclaimers(2)
                .with_buffer_pool_size(256 * 1024 * 1024)
                .with_clean_block_threshold(4)
                .with_eviction_pickers(vec![Box::<FifoPicker>::default()])
                .with_admission_filter(StorageFilter::new())
                .with_reinsertion_filter(StorageFilter::new().with_condition(RejectAll))
                .with_tombstone_log(false),
        )
        .with_recover_mode(RecoverMode::Quiet)
        .with_compression(foyer::Compression::Lz4)
        .with_spawner(
            tokio::runtime::Builder::new_multi_thread()
                .enable_all()
                .worker_threads(4)
                .max_blocking_threads(2)
                .build()
                .unwrap()
                .into(),
        )
        .build()
        .await?;

    hybrid.insert(42, "The answer to life, the universe, and everything.".to_string());
    assert_eq!(
        hybrid.get(&42).await?.unwrap().value(),
        "The answer to life, the universe, and everything."
    );

    let e = hybrid
        .get_or_fetch(&20230512, || async {
            // Mock fetching data from remote source
            let now = jiff::Zoned::now();
            if format!("{}{}{}", now.year(), now.month(), now.day()) == "20230512" {
                return Err(anyhow::anyhow!("Hi, time traveler!"));
            }
            Ok("Hello, foyer.".to_string())
        })
        .await?;
    assert_eq!(e.key(), &20230512);
    assert_eq!(e.value(), "Hello, foyer.");

    hybrid.close().await?;
    Ok(())
}

```

--------------------------------

### Get TypeId of Self in Rust

Source: https://docs.rs/foyer/0.22.3/foyer/struct.CacheBuilder.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Returns the `TypeId` of the current type. This is a standard method for trait objects and dynamic typing in Rust.

```rust
fn type_id(&self) -> TypeId

```

--------------------------------

### BlockEngineConfig Build Method

Source: https://docs.rs/foyer/0.22.3/foyer/struct.BlockEngineConfig.html?search=std%3A%3Avec

Provides details on how to build the block-based disk cache engine using the BlockEngineConfig.

```APIDOC
## POST /build

### Description
Build the block-based disk cache engine with the given configurations.

### Method
POST

### Endpoint
/build

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **__arg1** (EngineBuildContext) - Required - The build context for the engine.

### Request Example
```json
{
  "__arg1": { ... } 
}
```

### Response
#### Success Response (200)
- **BlockEngineConfig** (Arc<BlockEngine<K, V, P>>) - A boxed BlockEngineConfig instance.

#### Response Example
```json
{
  "engine": "..."
}
```
```
Tokens:
Raw