qubit_fs/write/writer_state.rs
1// =============================================================================
2// Copyright (c) 2026 Haixing Hu.
3//
4// SPDX-License-Identifier: Apache-2.0
5//
6// Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! File writer lifecycle states.
9
10use super::WriteFailureState;
11
12/// Observable lifecycle state of a synchronous or asynchronous file writer.
13///
14/// # Examples
15///
16/// ```rust
17/// use qubit_fs::write::WriterState;
18///
19/// assert!(matches!(WriterState::Open, WriterState::Open));
20/// ```
21#[derive(Clone, Copy, Debug, Eq, PartialEq)]
22pub enum WriterState {
23 /// The session accepts bytes and may be committed or aborted.
24 Open,
25 /// Publication completed successfully.
26 Committed,
27 /// Publication definitely did not occur and only cleanup remains possible.
28 NotPublished,
29 /// Publication occurred, but provider cleanup remains possible.
30 Published,
31 /// The session was explicitly cancelled and cleaned up.
32 Aborted,
33 /// Publication or lifecycle cleanup may have occurred, but the provider
34 /// cannot confirm the final state.
35 Indeterminate,
36}
37
38impl WriterState {
39 /// Returns the publication state to report when a commit is attempted
40 /// after this writer has left the open state.
41 ///
42 /// This describes the destination's known historical state, rather than
43 /// the validity of the repeated operation itself.
44 #[inline]
45 #[must_use]
46 pub(crate) const fn publication_failure_state(self) -> WriteFailureState {
47 match self {
48 Self::Open => WriteFailureState::RetryableNotPublished,
49 Self::Committed | Self::Published => WriteFailureState::Published,
50 Self::NotPublished | Self::Aborted => WriteFailureState::NotPublished,
51 Self::Indeterminate => WriteFailureState::Indeterminate,
52 }
53 }
54}