foyer_storage/io/device/
mod.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
15pub mod statistics;
16pub mod throttle;
17
18use std::{any::Any, fmt::Debug, sync::Arc};
19
20use foyer_common::error::Result;
21
22use crate::io::device::statistics::Statistics;
23
24pub type PartitionId = u32;
25
26/// Raw os file resource.
27///
28/// Use `fd` with unix and wasm, use `handle` with windows.
29#[cfg(any(target_family = "unix", target_family = "wasm"))]
30pub struct RawFile(pub std::os::fd::RawFd);
31
32/// Raw os file resource.
33///
34/// Use `fd` with unix and wasm, use `handle` with windows.
35#[cfg(target_family = "windows")]
36pub struct RawFile(pub std::os::windows::io::RawHandle);
37
38unsafe impl Send for RawFile {}
39unsafe impl Sync for RawFile {}
40
41/// Device builder trait.
42pub trait DeviceBuilder: Send + Sync + 'static + Debug {
43    /// Build a device from the given configuration.
44    fn build(self) -> Result<Arc<dyn Device>>;
45}
46
47/// Partition is a logical segment of a device.
48pub trait Partition: Send + Sync + 'static + Debug + Any {
49    /// Get the id of the partition.
50    fn id(&self) -> PartitionId;
51
52    /// Get the capacity of the partition.
53    ///
54    /// NOTE: `size` must be 4K aligned.
55    fn size(&self) -> usize;
56
57    /// Translate an address to a raw file descriptor and address.
58    fn translate(&self, address: u64) -> (RawFile, u64);
59
60    /// Get the statistics of the device this partition belongs to.
61    fn statistics(&self) -> &Arc<Statistics>;
62}
63
64/// Device trait.
65pub trait Device: Send + Sync + 'static + Debug + Any {
66    /// Get the capacity of the device.
67    ///
68    /// NOTE: `capacity` must be 4K aligned.
69    fn capacity(&self) -> usize;
70
71    /// Get the allocated space in the device.
72    fn allocated(&self) -> usize;
73
74    /// Get the free space in the device.
75    fn free(&self) -> usize {
76        self.capacity() - self.allocated()
77    }
78
79    /// Create a new partition with the given size.
80    ///
81    /// NOTE:
82    ///
83    /// - Allocating partition may consume more space than requested.
84    /// - `size` must be 4K aligned.
85    fn create_partition(&self, size: usize) -> Result<Arc<dyn Partition>>;
86
87    /// Get the number of partitions in the device.
88    fn partitions(&self) -> usize;
89
90    /// Get the partition with given id in the device.
91    fn partition(&self, id: PartitionId) -> Arc<dyn Partition>;
92
93    /// Get the statistics of the device this partition belongs to.
94    fn statistics(&self) -> &Arc<Statistics>;
95}
96
97pub mod file;
98pub mod fs;
99pub mod noop;
100
101pub mod combined;
102pub mod partial;
foyer_storage/io/device/mod.rs

foyer_storage/io/device/
mod.rs
