foyer_common/
properties.rs

1// Copyright 2025 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))]
28pub enum Hint {
29    /// The default hint shared by all cache eviction algorithms.
30    Normal,
31    /// Suggest the priority of the entry is low.
32    ///
33    /// Used by LRU.
34    Low,
35}
36
37impl Default for Hint {
38    fn default() -> Self {
39        Self::Normal
40    }
41}
42
43// TODO(MrCroxx): Is it necessary to make popluated entry still follow the cache location advice?
44/// Advice cache location for the cache entry.
45///
46/// Useful when using hybrid cache.
47///
48/// NOTE: `CacheLocation` only affects the first time the entry is handle.
49/// After it is populated, the entry may not follow the given advice.
50#[derive(Debug, Clone, Copy, PartialEq, Eq)]
51#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
52pub enum Location {
53    /// The default location.
54    ///
55    /// Prefer to store the entry in the in-memory cache with in-memory cache.
56    /// And prefer to store the entry in the hybrid cache with hybrid cache.
57    Default,
58    /// Prefer to store the entry in the in-memory cache.
59    InMem,
60    /// Prefer to store the entry on the disk cache.
61    OnDisk,
62}
63
64impl Default for Location {
65    fn default() -> Self {
66        Self::Default
67    }
68}
69
70/// Entry age in the disk cache. Used by hybrid cache.
71#[derive(Debug, Clone, Copy, PartialEq, Eq)]
72#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
73pub enum Age {
74    /// THe entry is still young and will be reserved in the disk cache for a while.
75    Young,
76    /// The entry is old any will be eviction from the disk cache soon.
77    Old,
78}
79
80/// Source context for populated entry.
81#[derive(Debug, Clone, Copy, PartialEq, Eq)]
82#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
83pub struct Populated {
84    /// The age of the entry.
85    pub age: Age,
86}
87
88/// Entry source used by hybrid cache.
89#[derive(Debug, Clone, Copy, PartialEq, Eq)]
90#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
91pub enum Source {
92    /// Comes from outer system of foyer.
93    Outer,
94    /// Populated from the disk cache.
95    Populated(Populated),
96}
97
98impl Default for Source {
99    fn default() -> Self {
100        Self::Outer
101    }
102}
103
104/// Entry level properties trait.
105///
106/// The in-memory only cache and the hybrid cache may have different properties implementations to minimize the overhead
107/// of necessary properties in different scenarios.
108pub trait Properties: Send + Sync + 'static + Clone + Default + Debug {
109    /// Set disposable.
110    ///
111    /// If an entry is disposable, it will not actually inserted into the cache and removed immediately after the last
112    /// reference drops.
113    ///
114    /// Disposable property is used to simplify the design consistency of the APIs.
115    fn with_disposable(self, disposable: bool) -> Self;
116
117    /// Entry disposable.
118    fn disposable(&self) -> Option<bool>;
119
120    /// Set entry ephemeral.
121    ///
122    /// Ephemeral entries are removed immediately after the last reference drops.
123    ///
124    /// Ephemeral property is used by disk-cache-only cache entries.
125    fn with_ephemeral(self, ephemeral: bool) -> Self;
126
127    /// Entry ephemeral.
128    fn ephemeral(&self) -> Option<bool>;
129
130    /// Set entry hint.
131    fn with_hint(self, hint: Hint) -> Self;
132
133    /// Entry hint.
134    fn hint(&self) -> Option<Hint>;
135
136    /// Set entry location.
137    fn with_location(self, location: Location) -> Self;
138
139    /// Entry location.
140    fn location(&self) -> Option<Location>;
141
142    /// Set entry source.
143    fn with_source(self, source: Source) -> Self;
144
145    /// Entry source.
146    fn source(&self) -> Option<Source>;
147}
foyer_common/properties.rs

foyer_common/
properties.rs
