pi_block_device 0.1.0

Asynchronous copy-on-write block storage abstractions
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
//! 文件系统块存储的初始化、恢复、读取与公共 trait 实现。

mod format;
mod io;
mod layout;
mod read;
mod snapshot;
mod state;
mod transaction;

use std::collections::{HashMap, VecDeque};
use std::fs::File;
use std::io as std_io;
use std::ops::{Deref, DerefMut};
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicBool, AtomicU8, AtomicU64, AtomicUsize};
use std::sync::{Arc, Condvar, Mutex, Weak};

use pi_append_log::file::{DefaultFileLayout, FileAppendLog, FileAppendLogBuilder, FileClosed};
use pi_append_log::{
    AppendLog, AppendLogBuilder, AppendLogVisitor, AppendOptions, BlockEncoder, BlockVisitContext,
    DefaultBlockCodec, Layout, ReadOrder,
};

use crate::{
    AsyncBlockDevice, BlockDeviceCapabilities, BlockDeviceInfo, BlockDeviceMetrics,
    BlockDeviceMetricsSnapshot, BlockId, BlockStore, BlockStoreError, DeviceId,
};
use read::{FileReadBuf, ReadLease};
use snapshot::FileSnapshot;
use state::State;
use transaction::FileTransaction;

/// 初始化同步故障注入所区分的阶段。
enum InitStage {
    /// 某一级别初始 Active 数据文件已经创建,需同步文件内容。
    ActiveFile(
        /// 正在同步的普通块级别,范围为 `0..=14`。
        u8,
    ),
    /// 初始数据文件目录项已经创建,需同步 data 目录。
    DataDirectory,
    /// data 与 log 子目录已经创建,需同步存储根目录。
    RootDirectory,
    /// 初始日志文件已经创建,需同步日志文件。
    LogFile,
    /// 日志目录项已经创建,需同步 log 目录。
    LogDirectory,
    /// 初始检查点正在以 durable 方式追加。
    CheckpointAppend,
}

/// 初始化文件、目录和检查点操作接缝。
trait InitHooks {
    /// 填充新设备的 16 字节随机身份;失败必须在创建持久内容前向上传播。
    fn fill_device_id(&self, device_id: &mut [u8; 16]) -> std_io::Result<()>;
    /// 按初始化阶段同步已创建文件,使后续目录同步建立持久顺序。
    fn sync_file(&self, file: &File, stage: InitStage) -> std_io::Result<()>;
    /// 同步指定目录的目录项;Windows 对不支持目录同步的特定错误采用 best effort。
    fn sync_directory(&self, path: &Path, stage: InitStage) -> std_io::Result<()>;
    /// 以 durable 选项追加编码后的初始检查点。
    async fn append_checkpoint<S>(
        &self,
        storage: &S,
        block: Vec<u8>,
        stage: InitStage,
    ) -> std_io::Result<()>
    where
        S: AppendLog<Block = Vec<u8>>;
}

/// 生产初始化操作实现。
struct RealHooks;

impl InitHooks for RealHooks {
    /// 填充新设备的 16 字节随机身份;失败必须在创建持久内容前向上传播。
    fn fill_device_id(&self, device_id: &mut [u8; 16]) -> std_io::Result<()> {
        getrandom::getrandom(device_id).map_err(|error| std_io::Error::other(error.to_string()))
    }

    /// 按初始化阶段同步已创建文件,使后续目录同步建立持久顺序。
    fn sync_file(&self, file: &File, stage: InitStage) -> std_io::Result<()> {
        if let InitStage::ActiveFile(level) = stage {
            let _ = level;
        }
        file.sync_all()
    }

    /// 同步指定目录的目录项;Windows 对不支持目录同步的特定错误采用 best effort。
    fn sync_directory(&self, path: &Path, _stage: InitStage) -> std_io::Result<()> {
        io::sync_directory(path)
    }

    /// 以 durable 选项追加编码后的初始检查点。
    async fn append_checkpoint<S>(
        &self,
        storage: &S,
        block: Vec<u8>,
        stage: InitStage,
    ) -> std_io::Result<()>
    where
        S: AppendLog<Block = Vec<u8>>,
    {
        let InitStage::CheckpointAppend = stage else {
            return Err(std_io::Error::new(
                std_io::ErrorKind::InvalidInput,
                "invalid checkpoint append stage",
            ));
        };
        storage
            .append(block, AppendOptions { durable: true })
            .await
            .map(|_| ())
    }
}

/// 文件实现支持的普通块槽位字节数。
const SUPPORTED_BLOCK_SIZES: [u64; 15] = [
    4 * 1024,
    6 * 1024,
    8 * 1024,
    12 * 1024,
    16 * 1024,
    24 * 1024,
    32 * 1024,
    48 * 1024,
    64 * 1024,
    96 * 1024,
    128 * 1024,
    192 * 1024,
    256 * 1024,
    384 * 1024,
    512 * 1024,
];

/// 文件追加日志的具体类型。
type FileLog = FileAppendLog<DefaultFileLayout>;

/// 存储可正常服务的运行状态码。
const STORE_READY: u8 = 0;
/// 存储必须恢复的运行状态码。
const STORE_RECOVERY_REQUIRED: u8 = 1;

/// 唤醒标准线程退休 worker 的共享信号。
pub(super) struct RetirementNotifier {
    /// 递增事件序号;worker 用它区分超时与新 enqueue/guard drop 通知。
    generation: Mutex<u64>,
    /// 等待 enqueue、lease drop、snapshot drop 或关闭通知的条件变量。
    wake: Condvar,
    /// true 表示最后一个可发布业务 owner 已释放,worker 应停止重试并退出。
    stopped: AtomicBool,
    /// FileBlockStore 与可 durable 发布事务/后台上下文的业务 owner 数。
    owners: AtomicUsize,
}

impl RetirementNotifier {
    /// 创建初始未停止且事件序号为零的通知器。
    fn new() -> Self {
        Self {
            generation: Mutex::new(0),
            wake: Condvar::new(),
            stopped: AtomicBool::new(false),
            owners: AtomicUsize::new(0),
        }
    }

    /// 非阻塞递增事件序号并唤醒 worker;锁中毒时仍执行条件变量通知。
    pub(super) fn notify(&self) {
        if let Ok(mut generation) = self.generation.lock() {
            *generation = generation.wrapping_add(1);
        }
        self.wake.notify_one();
    }

    /// 最后一个业务 owner 释放后标记关闭并唤醒 worker。
    fn stop(&self) {
        self.stopped
            .store(true, std::sync::atomic::Ordering::Release);
        self.notify();
    }

    /// 返回当前通知代次;测试可保存它以确定性验证 notify-before-wait 不丢失。
    pub(super) fn generation_for_test(&self) -> u64 {
        self.generation.lock().map_or(0, |generation| *generation)
    }

    /// 仅在代次未变化且尚未停止时等待;notify 发生在 drain 后、wait 前时会立即返回。
    pub(super) fn wait_for_change(
        &self,
        last_seen: u64,
        timeout: std::time::Duration,
    ) -> (u64, bool) {
        let mut generation = match self.generation.lock() {
            Ok(generation) => generation,
            Err(poisoned) => poisoned.into_inner(),
        };
        if *generation == last_seen && !self.stopped.load(std::sync::atomic::Ordering::Acquire) {
            match self.wake.wait_timeout(generation, timeout) {
                Ok((next, _)) => generation = next,
                Err(poisoned) => generation = poisoned.into_inner().0,
            }
        }
        (
            *generation,
            self.stopped.load(std::sync::atomic::Ordering::Acquire),
        )
    }
}

/// 唤醒标准线程日志维护 worker 的独立代次信号。
pub(super) struct MaintenanceNotifier {
    /// 递增通知代次,防止 notify-before-wait 丢失。
    generation: Mutex<u64>,
    /// worker 空闲和有限退避期间使用的条件变量。
    wake: Condvar,
    /// 最后一个可提交 owner 释放后请求 worker 排空并退出。
    stopped: AtomicBool,
    /// 可继续产生 durable 提交的业务 owner 数量。
    owners: AtomicUsize,
}

impl MaintenanceNotifier {
    /// 创建未停止且代次为零的维护通知器。
    fn new() -> Self {
        Self {
            generation: Mutex::new(0),
            wake: Condvar::new(),
            stopped: AtomicBool::new(false),
            owners: AtomicUsize::new(0),
        }
    }

    /// 递增代次并唤醒维护 worker。
    pub(super) fn notify(&self) {
        if let Ok(mut generation) = self.generation.lock() {
            *generation = generation.wrapping_add(1);
        }
        self.wake.notify_one();
    }

    /// 标记停止并唤醒 worker 执行最后排空。
    fn stop(&self) {
        self.stopped
            .store(true, std::sync::atomic::Ordering::Release);
        self.notify();
    }

    /// 代次未变化且未停止时等待通知或超时。
    pub(super) fn wait_for_change(
        &self,
        last_seen: u64,
        timeout: std::time::Duration,
    ) -> (u64, bool) {
        let mut generation = match self.generation.lock() {
            Ok(value) => value,
            Err(poisoned) => poisoned.into_inner(),
        };
        if *generation == last_seen && !self.stopped.load(std::sync::atomic::Ordering::Acquire) {
            generation = match self.wake.wait_timeout(generation, timeout) {
                Ok((value, _)) => value,
                Err(poisoned) => poisoned.into_inner().0,
            };
        }
        (
            *generation,
            self.stopped.load(std::sync::atomic::Ordering::Acquire),
        )
    }
}

#[cfg(test)]
/// 真实维护 worker 的无 sleep 确定性阶段屏障。
pub(super) struct MaintenanceWorkerBarriers {
    /// 屏障阶段及释放状态。
    state: Mutex<[bool; 10]>,
    /// 最近一轮 worker 完成结果。
    outcome: Mutex<Option<transaction::MaintenanceOutcome>>,
    /// 测试与 worker 的阶段通知。
    wake: Condvar,
}

#[cfg(test)]
impl MaintenanceWorkerBarriers {
    /// 创建未武装屏障。
    fn new() -> Self {
        Self {
            state: Mutex::new([false; 10]),
            outcome: Mutex::new(None),
            wake: Condvar::new(),
        }
    }
}

/// 保持退休 worker 可接受未来 durable enqueue 的业务所有权令牌。
///
/// 只有 FileBlockStore、FileTransaction 和 detached OwnedCommitContext 持有令牌;快照
/// 与 ReadBuf 不算可发布 owner。最后一个令牌释放时仅 stop+notify,不执行同步 I/O。
pub(super) struct WorkerOwner {
    /// 独立于 StoreInner 的控制对象,避免 worker 与 store 形成 Arc 环。
    control: Arc<RetirementNotifier>,
    /// 与退休 owner 同寿命的日志维护 worker 控制器。
    maintenance_control: Arc<MaintenanceNotifier>,
}

impl WorkerOwner {
    /// 登记一个新的可发布业务 owner。
    fn new(
        control: Arc<RetirementNotifier>,
        maintenance_control: Arc<MaintenanceNotifier>,
    ) -> Self {
        control
            .owners
            .fetch_add(1, std::sync::atomic::Ordering::AcqRel);
        maintenance_control
            .owners
            .fetch_add(1, std::sync::atomic::Ordering::AcqRel);
        Self {
            control,
            maintenance_control,
        }
    }
}

impl Clone for WorkerOwner {
    /// 克隆事务或移交后台上下文时增加业务 owner 计数。
    fn clone(&self) -> Self {
        Self::new(self.control.clone(), self.maintenance_control.clone())
    }
}

impl Drop for WorkerOwner {
    /// 最后一个业务 owner 释放时停止并唤醒 worker;不会在 Drop 中等待线程或删除文件。
    fn drop(&mut self) {
        if self
            .control
            .owners
            .fetch_sub(1, std::sync::atomic::Ordering::AcqRel)
            == 1
        {
            self.control.stop();
        }
        if self
            .maintenance_control
            .owners
            .fetch_sub(1, std::sync::atomic::Ordering::AcqRel)
            == 1
        {
            self.maintenance_control.stop();
        }
    }
}

/// 已发布状态、快照状态、精确读取 lease 与退休队列的统一同步域。
pub(super) struct RuntimeState {
    /// 最近 durable 发布的完整固定状态;提交仅在本锁内替换此 Arc。
    pub(super) current: Arc<State>,
    /// 固定快照状态的弱引用注册表;旧块首次定位仅查询此表。
    pub(super) snapshot_states: Vec<Weak<State>>,
    /// 按精确物理路径登记的 ReadBuf lease 弱引用;不把整个 State 作为删除保护。
    pub(super) read_leases: HashMap<PathBuf, Vec<Weak<ReadLease>>>,
    /// durable 发布后等待 guard 解除并删除的进程内路径队列;不写入日志或检查点。
    pub(super) retired: Vec<PathBuf>,
}

impl RuntimeState {
    /// 用初始或恢复所得的已验证状态建立统一运行时同步域。
    fn new(state: State) -> Self {
        Self {
            current: Arc::new(state),
            snapshot_states: Vec::new(),
            read_leases: HashMap::new(),
            retired: Vec::new(),
        }
    }

    /// 注册固定快照状态;清理失效引用并按 Arc 身份去重。
    fn register_snapshot(&mut self, state: &Arc<State>) {
        self.snapshot_states
            .retain(|snapshot| snapshot.strong_count() != 0);
        if !self
            .snapshot_states
            .iter()
            .any(|snapshot| snapshot.ptr_eq(&Arc::downgrade(state)))
        {
            self.snapshot_states.push(Arc::downgrade(state));
        }
    }

    /// 在统一锁内从 current 或旧快照状态选择声明块存活的来源。
    fn select_read_source(&mut self, block: BlockId) -> Result<Arc<State>, BlockStoreError> {
        self.snapshot_states
            .retain(|snapshot| snapshot.strong_count() != 0);
        if state_block_is_live(&self.current, block)? {
            return Ok(self.current.clone());
        }
        for snapshot in &self.snapshot_states {
            let Some(state) = snapshot.upgrade() else {
                continue;
            };
            if state_block_is_live(&state, block)? {
                return Ok(state);
            }
        }
        Err(BlockStoreError::BlockNotFound)
    }

    /// 为即将返回的 ReadBuf 注册精确路径 lease,并在离锁前返回强 lease。
    fn register_read_lease(
        &mut self,
        path: PathBuf,
        notifier: Arc<RetirementNotifier>,
    ) -> Arc<ReadLease> {
        let leases = self.read_leases.entry(path.clone()).or_default();
        leases.retain(|lease| lease.strong_count() != 0);
        let lease = Arc::new(ReadLease::new(path, notifier));
        leases.push(Arc::downgrade(&lease));
        lease
    }

    /// 在 durable append 成功后原子替换 current,并按确定顺序登记本次退休路径。
    pub(super) fn publish(&mut self, state: State, retired: Vec<PathBuf>) {
        self.snapshot_states
            .retain(|snapshot| snapshot.strong_count() != 0);
        self.read_leases.retain(|_, leases| {
            leases.retain(|lease| lease.strong_count() != 0);
            !leases.is_empty()
        });
        self.current = Arc::new(state);
        for path in retired {
            if !self.retired.contains(&path) {
                self.retired.push(path);
            }
        }
    }

    /// 返回进程内退休队列当前项数。
    #[allow(dead_code)]
    pub(super) fn retired_queue_len(&self) -> usize {
        self.retired.len()
    }

    /// 判断固定 State 是否精确引用给定 data 文件路径。
    pub(super) fn state_references_path(root: &Path, state: &State, path: &Path) -> bool {
        state.segments.keys().any(|&(level, version)| {
            layout::data_dir(root).join(format!("{level:x}.{version:07x}")) == path
        }) || state
            .large_blocks
            .keys()
            .any(|id| layout::data_dir(root).join(format!("l{id:015x}")) == path)
    }
}

impl Deref for RuntimeState {
    type Target = State;

    /// 为内部故障测试和只读调用兼容地借用 current State。
    fn deref(&self) -> &Self::Target {
        &self.current
    }
}

impl DerefMut for RuntimeState {
    /// 仅内部故障测试直接构造状态时使用;共享 current 时执行 copy-on-write,仍保持既有 guard 固定。
    fn deref_mut(&mut self) -> &mut Self::Target {
        Arc::make_mut(&mut self.current)
    }
}

/// 活动日志结构可以接受业务 Delta。
const LOG_PHASE_ACTIVE: u8 = 0;
/// 日志已轮转,新活动结构必须先写入 durable 完整检查点。
#[cfg_attr(not(test), allow(dead_code))]
const LOG_PHASE_NEEDS_CHECKPOINT: u8 = 1;
/// 生产日志活动结构达到此字节数后合并一次后台维护建议。
#[cfg_attr(test, allow(dead_code))]
pub(super) const MAINTENANCE_ROTATION_THRESHOLD: u64 = 4 * 1024 * 1024;

/// 真实日志维护的进程内状态;关闭句柄不进入持久格式。
#[cfg_attr(not(test), allow(dead_code))]
pub(super) struct MaintenanceState {
    /// 尚未被维护轮次消费的阈值请求数;归档期间到达的新请求不会丢失。
    pub(super) requests: u64,
    /// 已成功完成 rotate、checkpoint 和 archive 的轮次数。
    pub(super) completed_count: u64,
    /// durable 检查点完成但归档尚未成功的具体关闭结构队列。
    pub(super) archive_queue: VecDeque<FileClosed>,
}

impl MaintenanceState {
    /// 使用恢复发现的关闭结构创建归档重试状态。
    fn with_archive_queue(archive_queue: VecDeque<FileClosed>) -> Self {
        Self {
            requests: 0,
            completed_count: 0,
            archive_queue,
        }
    }
}

/// 文件存储实例共享的运行时状态。
pub(super) struct StoreInner {
    /// 调用方提供的存储根路径副本;实现未做 canonicalize,`data/` 与 `log/` 路径由它词法派生。基于路径的后续访问仍受并发目录换名竞态限制。
    root: PathBuf,
    /// current、旧状态 guard 注册表及未来退休队列的唯一同步边界;锁中毒会使实例进入 RecoveryRequired。
    state: Mutex<RuntimeState>,
    /// BlockId 原始值到事务身份的未提交分配表,用于读取返回 BlockNotCommitted。
    pending_allocations: Mutex<HashMap<u64, u64>>,
    /// 持有恢复后继续追加所需的文件日志存储。
    log: FileLog,
    /// 单写者门禁;true 表示某事务或后台提交仍占有写权。
    writer_active: AtomicBool,
    /// 实例内下一事务身份,单调递增且禁止回绕,用作 pending owner token。
    transaction_identity: AtomicU64,
    /// 下一日志块序号;明确 append 失败允许留下序号空洞。
    next_log_sequence: AtomicU64,
    /// 当前日志结构阶段;NeedsCheckpoint 时任何业务 Delta 都必须被拒绝并围栏。
    log_phase: AtomicU8,
    /// 真实维护 pending 与待重试关闭结构队列。
    #[cfg_attr(not(test), allow(dead_code))]
    maintenance: Mutex<MaintenanceState>,
    /// 实例内下一固定快照身份,用于限制 SegmentId 的作用域。
    next_snapshot_identity: AtomicU64,
    /// 进程内唯一存储实例身份,避免 SegmentId 跨重新打开的实例复用。
    identity: u64,
    /// STORE_READY 或 STORE_RECOVERY_REQUIRED 运行状态码。
    status: AtomicU8,
    /// enqueue 与 guard drop 用于唤醒标准线程退休 worker 的共享通知器。
    retirement_notifier: Arc<RetirementNotifier>,
    /// 独立维护 worker 的代次、停止和等待控制器。
    #[cfg_attr(not(test), allow(dead_code))]
    maintenance_notifier: Arc<MaintenanceNotifier>,
    #[cfg(test)]
    /// 新确定性测试控制的真实维护 worker 阶段屏障。
    maintenance_barriers: Arc<MaintenanceWorkerBarriers>,
    #[cfg(test)]
    /// 泛型故障注入维护状态;与真实 FileClosed 状态机分离。
    test_maintenance: Mutex<transaction::TestMaintenanceState>,
}

impl StoreInner {
    /// 以 Acquire 顺序读取运行状态,判断是否已被安全围栏。
    pub(super) fn recovery_required(&self) -> bool {
        self.status.load(std::sync::atomic::Ordering::Acquire) == STORE_RECOVERY_REQUIRED
    }

    /// 以 Release 顺序单向将实例标记为 RecoveryRequired;当前进程内不会恢复为 Ready。
    pub(super) fn require_recovery(&self) {
        self.status.store(
            STORE_RECOVERY_REQUIRED,
            std::sync::atomic::Ordering::Release,
        );
    }

    /// 原子分配一个不回绕的日志记录序号;耗尽时保持计数不变并围栏实例。
    /// 在真实 append 大小达到生产阈值时合并 pending 并唤醒维护 worker。
    #[cfg_attr(test, allow(dead_code))]
    pub(super) fn schedule_maintenance_for_active_size(
        &self,
        active_size: u64,
    ) -> Result<(), BlockStoreError> {
        if active_size < MAINTENANCE_ROTATION_THRESHOLD {
            return Ok(());
        }
        let notify = match self.maintenance.lock() {
            Ok(mut state) => {
                let notify = state.requests == 0;
                state.requests = state.requests.saturating_add(1);
                notify
            }
            Err(_) => {
                self.require_recovery();
                return Err(BlockStoreError::RecoveryRequired);
            }
        };
        if notify {
            self.maintenance_notifier.notify();
        }
        Ok(())
    }

    pub(super) fn allocate_log_sequence(&self) -> Result<u64, BlockStoreError> {
        loop {
            let current = self
                .next_log_sequence
                .load(std::sync::atomic::Ordering::Acquire);
            let Some(next) = current.checked_add(1) else {
                self.require_recovery();
                return Err(BlockStoreError::RecoveryRequired);
            };
            if self
                .next_log_sequence
                .compare_exchange_weak(
                    current,
                    next,
                    std::sync::atomic::Ordering::AcqRel,
                    std::sync::atomic::Ordering::Acquire,
                )
                .is_ok()
            {
                return Ok(current);
            }
        }
    }
}

/// 使用 data/ 与 log/ 目录持久化状态的文件块存储。
///
/// 同一实例只允许一个写事务;恢复要求失败后会拒绝继续服务。
pub struct FileBlockStore {
    /// 共享 StoreInner,使快照、事务和后台提交引用同一运行状态。
    inner: Arc<StoreInner>,
    /// 表示外层 store 仍可能创建并提交事务的 worker 业务 owner。
    worker_owner: WorkerOwner,
}

/// 用进程静态 CAS 计数器分配非零且不回绕的实例身份;耗尽返回 RecoveryRequired。
fn allocate_store_identity() -> Result<u64, BlockStoreError> {
    static NEXT_STORE_ID: AtomicU64 = AtomicU64::new(1);
    loop {
        let current = NEXT_STORE_ID.load(std::sync::atomic::Ordering::Acquire);
        if current == 0 || current == u64::MAX {
            return Err(BlockStoreError::RecoveryRequired);
        }
        if NEXT_STORE_ID
            .compare_exchange_weak(
                current,
                current + 1,
                std::sync::atomic::Ordering::AcqRel,
                std::sync::atomic::Ordering::Acquire,
            )
            .is_ok()
        {
            return Ok(current);
        }
    }
}

impl FileBlockStore {
    /// 打开、初始化或恢复指定根目录中的文件块存储。
    ///
    /// 路径不存在或为严格空目录时会创建 `data/`、`log/`、15 个初始 Active
    /// 文件及 durable 初始检查点;初始化失败会尽力删除本次创建的路径。已有布局
    /// 会回放日志、验证引用文件,截断 Active 段由完整槽位构成的冗余尾部,并
    /// **删除所有最终 State 未引用的普通 data 文件**,因此恢复具有破坏性副作用。
    ///
    /// # Errors
    ///
    /// 非法根布局、日志损坏、数据文件缺失或类型/长度不符、孤儿清理或目录同步
    /// 失败会返回恢复相关错误;更高格式版本返回 UnsupportedFormat;初始化 I/O
    /// 失败保留为 Io。
    ///
    /// # Panics
    ///
    /// 本方法没有设计上的 panic 条件;底层依赖若违反自身契约而 panic 不在保证内。
    pub async fn open(path: impl AsRef<Path>) -> Result<Self, BlockStoreError> {
        Self::open_with_hooks(path.as_ref(), &RealHooks).await
    }

    /// 分类根路径并选择初始化缺失/空目录或恢复已有布局;hooks 仅用于内部故障测试。
    async fn open_with_hooks<H: InitHooks>(
        root: &Path,
        hooks: &H,
    ) -> Result<Self, BlockStoreError> {
        match io::classify_root(root).map_err(BlockStoreError::Io)? {
            io::RootKind::Missing => Self::initialize(root, true, hooks).await,
            io::RootKind::Empty => Self::initialize(root, false, hooks).await,
            io::RootKind::Existing => Self::recover(root).await,
        }
    }

    /// 生成设备身份并创建新布局;任一步失败都会逆序清理本次创建的路径。
    async fn initialize<H: InitHooks>(
        root: &Path,
        create_root: bool,
        hooks: &H,
    ) -> Result<Self, BlockStoreError> {
        let mut device_id = [0_u8; 16];
        hooks
            .fill_device_id(&mut device_id)
            .map_err(BlockStoreError::Io)?;

        if create_root {
            io::create_root(root).map_err(BlockStoreError::Io)?;
        }
        let mut created = io::CreatedPaths::new(root, create_root);
        let result = Self::initialize_created(root, device_id, &mut created, hooks).await;
        if result.is_err() {
            created.cleanup();
        }
        result
    }

    /// 创建 data/log 初始文件,构建日志并 durable 追加首个检查点。
    async fn initialize_created<H: InitHooks>(
        root: &Path,
        device_id: [u8; 16],
        created: &mut io::CreatedPaths,
        hooks: &H,
    ) -> Result<Self, BlockStoreError> {
        io::create_initial_files(root, created, hooks).map_err(BlockStoreError::Io)?;
        io::create_initial_log_file(root, created, hooks).map_err(BlockStoreError::Io)?;
        let codec = DefaultBlockCodec::default();
        let mut visitor = RecoveryVisitor::default();
        let build = FileAppendLogBuilder::new(
            layout::log_dir(root),
            DefaultFileLayout::new(layout::log_dir(root)),
        )
        .build(&codec, ReadOrder::Forward, &mut visitor)
        .await
        .map_err(BlockStoreError::Io)?;
        let payload = format::encode_initial_checkpoint(device_id);
        let block = codec.encode(1, 0, &payload).map_err(BlockStoreError::Io)?;
        hooks
            .append_checkpoint(&build.storage, block, InitStage::CheckpointAppend)
            .await
            .map_err(BlockStoreError::Io)?;
        Self::from_parts(
            root,
            State::initial(device_id),
            build.storage,
            2,
            VecDeque::new(),
        )
    }

    /// 把已验证 State、日志存储和下一序号组装为 Ready 实例。
    fn from_parts(
        root: &Path,
        state: State,
        log: FileLog,
        next_sequence: u64,
        archive_queue: VecDeque<FileClosed>,
    ) -> Result<Self, BlockStoreError> {
        let identity = allocate_store_identity()?;
        let notifier = Arc::new(RetirementNotifier::new());
        let maintenance_notifier = Arc::new(MaintenanceNotifier::new());
        let inner = Arc::new(StoreInner {
            root: root.to_path_buf(),
            state: Mutex::new(RuntimeState::new(state)),
            pending_allocations: Mutex::new(HashMap::new()),
            log,
            writer_active: AtomicBool::new(false),
            transaction_identity: AtomicU64::new(1),
            next_log_sequence: AtomicU64::new(next_sequence),
            log_phase: AtomicU8::new(LOG_PHASE_ACTIVE),
            maintenance: Mutex::new(MaintenanceState::with_archive_queue(archive_queue)),
            next_snapshot_identity: AtomicU64::new(1),
            identity,
            status: AtomicU8::new(STORE_READY),
            retirement_notifier: notifier.clone(),
            maintenance_notifier: maintenance_notifier.clone(),
            #[cfg(test)]
            maintenance_barriers: Arc::new(MaintenanceWorkerBarriers::new()),
            #[cfg(test)]
            test_maintenance: Mutex::new(transaction::TestMaintenanceState::new()),
        });
        let worker_owner = WorkerOwner::new(notifier.clone(), maintenance_notifier.clone());
        #[cfg(not(test))]
        {
            let worker_inner = inner.clone();
            let worker_notifier = notifier.clone();
            std::thread::Builder::new()
                .name(String::from("pi-block-device-retirement"))
                .spawn(move || transaction::retirement_worker_loop(worker_inner, worker_notifier))
                .map_err(BlockStoreError::Io)?;
        }
        {
            let worker_inner = inner.clone();
            let worker_notifier = maintenance_notifier.clone();
            std::thread::Builder::new()
                .name(String::from("pi-block-device-maintenance"))
                .spawn(move || transaction::maintenance_worker_loop(worker_inner, worker_notifier))
                .map_err(BlockStoreError::Io)?;
        }
        Ok(Self {
            worker_owner,
            inner,
        })
    }

    /// 回放日志、验证状态文件、截断 Active 冗余完整槽并删除孤儿后构造实例。
    async fn recover(root: &Path) -> Result<Self, BlockStoreError> {
        if !io::validate_root_layout(root).map_err(BlockStoreError::Io)? {
            return Err(BlockStoreError::RecoveryFailed);
        }
        let codec = DefaultBlockCodec::default();
        let mut visitor = RecoveryVisitor::default();
        let build_result = FileAppendLogBuilder::new(
            layout::log_dir(root),
            DefaultFileLayout::new(layout::log_dir(root)),
        )
        .build(&codec, ReadOrder::Forward, &mut visitor)
        .await;
        if visitor.unsupported_format {
            return Err(BlockStoreError::UnsupportedFormat);
        }
        let build = build_result.map_err(|_| BlockStoreError::RecoveryFailed)?;
        let state = visitor.state.ok_or(BlockStoreError::RecoveryFailed)?;
        if visitor.max_sequence == u64::MAX {
            return Err(BlockStoreError::RecoveryFailed);
        }
        io::validate_segment_files(root, &state).map_err(|_| BlockStoreError::RecoveryFailed)?;
        io::remove_orphan_data_files(root, &state).map_err(|_| BlockStoreError::RecoveryFailed)?;
        let log_root = layout::log_dir(root);
        let log_layout = DefaultFileLayout::new(&log_root);
        let mut active_path = None;
        for entry in std::fs::read_dir(&log_root).map_err(|_| BlockStoreError::RecoveryFailed)? {
            let path = entry.map_err(|_| BlockStoreError::RecoveryFailed)?.path();
            if log_layout.parse_active_name(&path).is_some() && active_path.replace(path).is_some()
            {
                return Err(BlockStoreError::RecoveryFailed);
            }
        }
        let active_path = active_path.ok_or(BlockStoreError::RecoveryFailed)?;
        let active_is_empty = std::fs::metadata(active_path)
            .map_err(|_| BlockStoreError::RecoveryFailed)?
            .len()
            == 0;
        let mut next_sequence = visitor.max_sequence + 1;
        if active_is_empty && !build.recovered_closed.is_empty() {
            let sequence = next_sequence;
            next_sequence = sequence
                .checked_add(1)
                .ok_or(BlockStoreError::RecoveryFailed)?;
            let block = format::encode_checkpoint(&state, sequence)
                .map_err(|_| BlockStoreError::RecoveryFailed)?;
            build
                .storage
                .append(block, AppendOptions { durable: true })
                .await
                .map_err(|_| BlockStoreError::RecoveryFailed)?;
        }
        Self::from_parts(
            root,
            state,
            build.storage,
            next_sequence,
            build.recovered_closed.into(),
        )
    }
}

#[derive(Default)]
/// 按日志顺序重建 State 的访问器。
struct RecoveryVisitor {
    /// 从最近一个检查点开始、按已访问 Delta 更新的恢复候选 `State`;尚未见检查点时为 `None`。
    state: Option<State>,
    /// 整条恢复日志链首次检查点的设备身份;跨 append-log structures 的后续检查点也必须保持一致。
    chain_device_id: Option<[u8; 16]>,
    /// 当前 append-log structure 是否已有成功解码记录;structure 首记录必须是 Checkpoint。
    structure_has_record: bool,
    /// visitor 因更高格式版本停止的标志,使外层覆盖 append-log 的一般构建错误并返回 `UnsupportedFormat`。
    unsupported_format: bool,
    /// 所有成功解码记录的最大 envelope sequence。
    max_sequence: u64,
    /// 按物理访问顺序最近成功记录的 sequence,用于拒绝相等或回退。
    last_sequence: Option<u64>,
}

impl AppendLogVisitor for RecoveryVisitor {
    /// 按整条 Forward 物理链解码记录,严格检查 sequence、检查点链与高水位单调性,并应用 Delta。
    fn visit(&mut self, block: &[u8], context: BlockVisitContext) -> std_io::Result<bool> {
        let record = match format::decode_record_block(block) {
            Ok(record) => record,
            Err(format::DecodeError::UnsupportedFormat) => {
                self.unsupported_format = true;
                return Err(std_io::Error::new(
                    std_io::ErrorKind::InvalidData,
                    "unsupported record format",
                ));
            }
            Err(format::DecodeError::Recovery(error)) => return Err(error),
        };
        if context.is_first_in_structure {
            self.structure_has_record = false;
        }
        let sequence = match &record {
            format::Record::Checkpoint { sequence, .. }
            | format::Record::Delta { sequence, .. } => *sequence,
        };
        if self
            .last_sequence
            .is_some_and(|last_sequence| sequence <= last_sequence)
        {
            return Err(std_io::Error::new(
                std_io::ErrorKind::InvalidData,
                "log record sequence is not strictly increasing",
            ));
        }
        self.last_sequence = Some(sequence);
        self.max_sequence = self.max_sequence.max(sequence);
        match record {
            format::Record::Checkpoint { state, .. } => {
                if self.structure_has_record || !context.is_first_in_structure {
                    return Err(std_io::Error::new(
                        std_io::ErrorKind::InvalidData,
                        "checkpoint is not first in structure",
                    ));
                }
                if let Some(device_id) = self.chain_device_id {
                    if state.device_id != device_id {
                        return Err(std_io::Error::new(
                            std_io::ErrorKind::InvalidData,
                            "checkpoint DeviceId changed across structures",
                        ));
                    }
                } else {
                    self.chain_device_id = Some(state.device_id);
                }
                if let Some(current) = &self.state
                    && (state.next_segment_version < current.next_segment_version
                        || state.next_large_block_id < current.next_large_block_id)
                {
                    return Err(std_io::Error::new(
                        std_io::ErrorKind::InvalidData,
                        "checkpoint allocation high water mark regressed",
                    ));
                }
                self.state = Some(state);
            }
            format::Record::Delta { delta, .. } => {
                if !self.structure_has_record || context.is_first_in_structure {
                    return Err(std_io::Error::new(
                        std_io::ErrorKind::InvalidData,
                        "DeltaRecord cannot start a structure",
                    ));
                }
                self.state
                    .as_mut()
                    .ok_or_else(|| {
                        std_io::Error::new(
                            std_io::ErrorKind::InvalidData,
                            "DeltaRecord precedes checkpoint",
                        )
                    })?
                    .apply(delta)?;
            }
        }
        self.structure_has_record = true;
        Ok(false)
    }
}

/// 判断已验证固定状态是否仍声明给定块存活;编码字段不可解释时返回 InvalidBlockId。
fn state_block_is_live(state: &State, block: BlockId) -> Result<bool, BlockStoreError> {
    if block.level() == 15 {
        let id = block
            .large_block_id()
            .ok_or(BlockStoreError::InvalidBlockId)?;
        return Ok(state.large_blocks.contains_key(&id));
    }
    let level = block.level();
    let version = block
        .segment_version()
        .ok_or(BlockStoreError::InvalidBlockId)?;
    let index = u64::from(block.block_index().ok_or(BlockStoreError::InvalidBlockId)?);
    let Some(record) = state.segments.get(&(level, version)) else {
        return Ok(false);
    };
    if index >= record.frontier {
        return Ok(false);
    }
    let word = usize::try_from(index / 64).map_err(|_| BlockStoreError::InvalidBlockId)?;
    Ok(record
        .bitmap
        .get(word)
        .is_some_and(|bits| bits & (1_u64 << (index % 64)) != 0))
}

impl AsyncBlockDevice for FileBlockStore {
    /// 读取结果使用 FileReadBuf:Active 段为拥有缓冲,Sealed/large 可为只读映射;两者都保留来源状态和路径 guard。
    type ReadBuf = FileReadBuf;

    /// 先拒绝 `RecoveryRequired` 和 pending 块;当前 State 不含目标时,在快照弱引用目录锁内升级并选择仍声明目标存活的旧固定状态。
    ///
    /// # Errors
    ///
    /// 分别可能返回 `RecoveryRequired`、`BlockNotCommitted`、`BlockNotFound`、
    /// `BlockCorrupted`、`InvalidBlockId` 或保留底层原因的 `Io`。
    async fn read(&self, block: BlockId) -> Result<Self::ReadBuf, BlockStoreError> {
        use std::io::{Read, Seek, SeekFrom};

        if self.inner.recovery_required() {
            return Err(BlockStoreError::RecoveryRequired);
        }
        let raw = u64::from(block);
        if self
            .inner
            .pending_allocations
            .lock()
            .map_err(|_| {
                self.inner.require_recovery();
                BlockStoreError::RecoveryRequired
            })?
            .contains_key(&raw)
        {
            return Err(BlockStoreError::BlockNotCommitted);
        }
        let path = if block.level() == 15 {
            let id = block
                .large_block_id()
                .ok_or(BlockStoreError::InvalidBlockId)?;
            layout::data_dir(&self.inner.root).join(format!("l{id:015x}"))
        } else {
            let level = block.level();
            let version = block
                .segment_version()
                .ok_or(BlockStoreError::InvalidBlockId)?;
            layout::data_dir(&self.inner.root).join(format!("{level:x}.{version:07x}"))
        };
        let (source, lease) = {
            let mut runtime = self.inner.state.lock().map_err(|_| {
                self.inner.require_recovery();
                BlockStoreError::RecoveryRequired
            })?;
            let source = runtime.select_read_source(block)?;
            let lease =
                runtime.register_read_lease(path.clone(), self.inner.retirement_notifier.clone());
            (source, lease)
        };
        if self.inner.recovery_required() {
            return Err(BlockStoreError::RecoveryRequired);
        }

        if block.level() == 15 {
            let id = block
                .large_block_id()
                .ok_or(BlockStoreError::InvalidBlockId)?;
            let logical_len = *source
                .large_blocks
                .get(&id)
                .ok_or(BlockStoreError::BlockNotFound)?;
            let file = File::open(&path).map_err(BlockStoreError::Io)?;
            if file.metadata().map_err(BlockStoreError::Io)?.len() != logical_len {
                return Err(BlockStoreError::BlockCorrupted);
            }
            let length =
                usize::try_from(logical_len).map_err(|_| BlockStoreError::InvalidBlockId)?;
            // SAFETY:已提交的大块文件不会原地修改;映射与来源 guard 共同覆盖返回缓冲生命周期。
            let map =
                unsafe { memmap2::MmapOptions::new().map(&file) }.map_err(BlockStoreError::Io)?;
            return Ok(FileReadBuf::mapped(map, 0..length, lease));
        }
        let level = block.level();
        let version = block
            .segment_version()
            .ok_or(BlockStoreError::InvalidBlockId)?;
        let index = u64::from(block.block_index().ok_or(BlockStoreError::InvalidBlockId)?);
        let record = source
            .segments
            .get(&(level, version))
            .ok_or(BlockStoreError::BlockNotFound)?;
        let slot = SUPPORTED_BLOCK_SIZES[usize::from(level)];
        let offset = index
            .checked_mul(slot)
            .ok_or(BlockStoreError::InvalidBlockId)?;
        let end = offset
            .checked_add(slot)
            .ok_or(BlockStoreError::InvalidBlockId)?;
        let mut file = File::open(&path).map_err(BlockStoreError::Io)?;
        if file.metadata().map_err(BlockStoreError::Io)?.len() < end {
            return Err(BlockStoreError::BlockCorrupted);
        }
        let slot_len = usize::try_from(slot).map_err(|_| BlockStoreError::InvalidBlockId)?;
        match record.state {
            state::SegmentState::Active => {
                let mut data = vec![0_u8; slot_len];
                file.seek(SeekFrom::Start(offset))
                    .map_err(BlockStoreError::Io)?;
                file.read_exact(&mut data).map_err(|error| {
                    if error.kind() == std::io::ErrorKind::UnexpectedEof {
                        BlockStoreError::BlockCorrupted
                    } else {
                        BlockStoreError::Io(error)
                    }
                })?;
                Ok(FileReadBuf::owned(data, lease))
            }
            state::SegmentState::Sealed => {
                let start = usize::try_from(offset).map_err(|_| BlockStoreError::InvalidBlockId)?;
                let end = usize::try_from(end).map_err(|_| BlockStoreError::InvalidBlockId)?;
                // SAFETY:Sealed 段提交后不再原地修改;映射与来源 guard 共同覆盖返回缓冲生命周期。
                let map = unsafe { memmap2::MmapOptions::new().map(&file) }
                    .map_err(BlockStoreError::Io)?;
                Ok(FileReadBuf::mapped(map, start..end, lease))
            }
        }
    }
}

impl BlockStore for FileBlockStore {
    /// 固定快照由 FileSnapshot 实现。
    type Snapshot = FileSnapshot;
    /// 独占写事务由 FileTransaction 实现。
    type Transaction = FileTransaction;

    /// 克隆当前已发布 `State` 并分配不回绕快照身份;结果固定且后续提交不可见。
    ///
    /// # Errors
    ///
    /// store 已围栏、状态锁中毒或身份计数耗尽时返回 `RecoveryRequired`,后两者还会
    /// 主动调用 `require_recovery`。
    fn open_snapshot(&self) -> Result<Self::Snapshot, BlockStoreError> {
        if self.inner.recovery_required() {
            return Err(BlockStoreError::RecoveryRequired);
        }
        let identity = loop {
            let current = self
                .inner
                .next_snapshot_identity
                .load(std::sync::atomic::Ordering::Acquire);
            let Some(next) = current.checked_add(1) else {
                self.inner.require_recovery();
                return Err(BlockStoreError::RecoveryRequired);
            };
            if self
                .inner
                .next_snapshot_identity
                .compare_exchange_weak(
                    current,
                    next,
                    std::sync::atomic::Ordering::AcqRel,
                    std::sync::atomic::Ordering::Acquire,
                )
                .is_ok()
            {
                break current;
            }
        };
        let state = {
            let mut runtime = self.inner.state.lock().map_err(|_| {
                self.inner.require_recovery();
                BlockStoreError::RecoveryRequired
            })?;
            let state = runtime.current.clone();
            runtime.register_snapshot(&state);
            state
        };
        if self.inner.recovery_required() {
            return Err(BlockStoreError::RecoveryRequired);
        }
        Ok(FileSnapshot::new(
            state,
            self.inner.identity,
            identity,
            self.inner.retirement_notifier.clone(),
        ))
    }

    /// 原子获取单写者门禁,分配不回绕事务身份并克隆基础 `State`;所有取得门禁后的失败路径都会回滚门禁。
    ///
    /// # Errors
    ///
    /// 已有写者返回 `WriteTransactionBusy`;store 已围栏、身份耗尽或状态锁中毒返回
    /// `RecoveryRequired`,后两者会主动围栏 store。
    async fn begin_write(&self) -> Result<Self::Transaction, BlockStoreError> {
        if self.inner.recovery_required() {
            return Err(BlockStoreError::RecoveryRequired);
        }
        if self
            .inner
            .writer_active
            .compare_exchange(
                false,
                true,
                std::sync::atomic::Ordering::AcqRel,
                std::sync::atomic::Ordering::Acquire,
            )
            .is_err()
        {
            return Err(BlockStoreError::WriteTransactionBusy);
        }
        if self.inner.recovery_required() {
            self.inner
                .writer_active
                .store(false, std::sync::atomic::Ordering::Release);
            return Err(BlockStoreError::RecoveryRequired);
        }
        if self
            .inner
            .log_phase
            .load(std::sync::atomic::Ordering::Acquire)
            != LOG_PHASE_ACTIVE
        {
            self.inner.require_recovery();
            self.inner
                .writer_active
                .store(false, std::sync::atomic::Ordering::Release);
            return Err(BlockStoreError::RecoveryRequired);
        }
        let identity = loop {
            let current = self
                .inner
                .transaction_identity
                .load(std::sync::atomic::Ordering::Acquire);
            if current == 0 || current == u64::MAX {
                self.inner.require_recovery();
                self.inner
                    .writer_active
                    .store(false, std::sync::atomic::Ordering::Release);
                return Err(BlockStoreError::RecoveryRequired);
            }
            if self
                .inner
                .transaction_identity
                .compare_exchange_weak(
                    current,
                    current + 1,
                    std::sync::atomic::Ordering::AcqRel,
                    std::sync::atomic::Ordering::Acquire,
                )
                .is_ok()
            {
                break current;
            }
        };
        let state = match self.inner.state.lock() {
            Ok(state) => state.current.as_ref().clone(),
            Err(_) => {
                self.inner.require_recovery();
                self.inner
                    .writer_active
                    .store(false, std::sync::atomic::Ordering::Release);
                return Err(BlockStoreError::RecoveryRequired);
            }
        };
        Ok(FileTransaction::new(
            self.inner.clone(),
            self.worker_owner.clone(),
            identity,
            state,
        ))
    }
}

impl BlockDeviceInfo for FileBlockStore {
    /// 从已发布 `State` 返回持久设备身份。
    ///
    /// # Panics
    ///
    /// `state` 互斥锁已经中毒时会 panic;与可失败操作不同,此冻结信息接口没有
    /// `Result` 返回通道。
    fn device_id(&self) -> DeviceId {
        DeviceId(
            self.inner
                .state
                .lock()
                .expect("store state lock poisoned")
                .current
                .device_id,
        )
    }

    /// 返回 4096 字节基础对齐;它同时是支持列表中的最小普通槽位尺寸。
    fn base_block_size(&self) -> u64 {
        4096
    }

    /// 返回 15 个固定普通槽位尺寸的静态切片。
    fn supported_block_sizes(&self) -> &'static [u64] {
        &SUPPORTED_BLOCK_SIZES
    }

    /// 返回当前均为 false 的压缩、加密和校验和能力。
    fn capabilities(&self) -> BlockDeviceCapabilities {
        BlockDeviceCapabilities {
            compression: false,
            encryption: false,
            data_checksums: false,
        }
    }
}

impl BlockDeviceMetrics for FileBlockStore {
    /// 返回零值占位指标;当前尚未连接实际计数器。
    fn metrics(&self) -> BlockDeviceMetricsSnapshot {
        BlockDeviceMetricsSnapshot {
            used_bytes: 0,
            free_bytes: 0,
            available_bytes: None,
            read_ops: 0,
            read_bytes: 0,
            write_ops: 0,
            write_bytes: 0,
            commit_ok: 0,
            commit_failed: 0,
            recovery_count: 0,
            reclaimed_bytes: 0,
        }
    }
}

#[cfg(test)]
#[path = "../../tests/unit/file_initialization_fault_test.rs"]
mod fault_tests;