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

foyer_storage/io/device/
mod.rs
