foyer_common/
properties.rs

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
15use std::fmt::Debug;
16
17/// Hint for the cache eviction algorithm to decide the priority of the specific entry if needed.
18///
19/// The meaning of the hint differs in each cache eviction algorithm, and some of them can be ignore by specific
20/// algorithm.
21///
22/// If the given cache hint does not suitable for the cache eviction algorithm that is active, the algorithm may modify
23/// it to a proper one.
24///
25/// For more details, please refer to the document of each enum options.
26#[derive(Debug, Clone, Copy, PartialEq, Eq)]
27#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
28#[derive(Default)]
29pub enum Hint {
30    /// The default hint shared by all cache eviction algorithms.
31    #[default]
32    Normal,
33    /// Suggest the priority of the entry is low.
34    ///
35    /// Used by LRU.
36    Low,
37}
38
39// TODO(MrCroxx): Is it necessary to make popluated entry still follow the cache location advice?
40/// Advice cache location for the cache entry.
41///
42/// Useful when using hybrid cache.
43///
44/// NOTE: `CacheLocation` only affects the first time the entry is handle.
45/// After it is populated, the entry may not follow the given advice.
46#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
47#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
48pub enum Location {
49    /// The default location.
50    ///
51    /// Prefer to store the entry in the in-memory cache with in-memory cache.
52    /// And prefer to store the entry in the hybrid cache with hybrid cache.
53    #[default]
54    Default,
55    /// Prefer to store the entry in the in-memory cache.
56    InMem,
57    /// Prefer to store the entry on the disk cache.
58    OnDisk,
59}
60
61/// Entry age in the disk cache. Used by hybrid cache.
62#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
63#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
64pub enum Age {
65    /// The entry is fresh and not yet or just inserted to disk cache.
66    #[default]
67    Fresh,
68    /// The entry is still young and will be reserved in the disk cache for a while.
69    Young,
70    /// The entry is old any will be eviction from the disk cache soon.
71    Old,
72}
73
74/// Entry level properties trait.
75///
76/// The in-memory only cache and the hybrid cache may have different properties implementations to minimize the overhead
77/// of necessary properties in different scenarios.
78pub trait Properties: Send + Sync + 'static + Clone + Default + Debug {
79    /// Set entry as a phantom entry.
80    ///
81    /// A phantom entry will not be actually inserted into the in-memory cache.
82    /// It is only used to keep the APIs consistent.
83    ///
84    /// NOTE: This API is for internal usage only. It MUST NOT be exported publicly.
85    fn with_phantom(self, phantom: bool) -> Self;
86
87    /// If the entry is a phantom entry.
88    fn phantom(&self) -> Option<bool>;
89
90    /// Set entry hint.
91    fn with_hint(self, hint: Hint) -> Self;
92
93    /// Entry hint.
94    fn hint(&self) -> Option<Hint>;
95
96    /// Set entry location.
97    fn with_location(self, location: Location) -> Self;
98
99    /// Entry location.
100    fn location(&self) -> Option<Location>;
101
102    /// Set entry age.
103    fn with_age(self, age: Age) -> Self;
104
105    /// Entry age.
106    fn age(&self) -> Option<Age>;
107}
108
109/// Source of the cache entry.
110#[derive(Debug, Clone, Copy, PartialEq, Eq)]
111#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
112pub enum Source {
113    /// The cache entry comes from outer source.
114    Outer,
115    /// The cache entry comes from memory cache.
116    Memory,
117    /// The cache entry comes from disk cache.
118    Disk,
119}
foyer_common/properties.rs

foyer_common/
properties.rs
