qubit-codec 0.9.0

Core codec traits and buffer conversion primitives for Rust
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

// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Debug-only lifecycle guard for transcode engines.
//
// qubit-style: allow multiple-public-types
//!
//! [`Transcoder`](crate::Transcoder) documents a lifecycle of
//! `reset → transcode* → finish` and then `reset` again before reusing the
//! instance for another logical stream. The trait itself does not enforce
//! this; engines historically rely on caller discipline. `LifecycleGuard`
//! catches common misuse (calling `transcode` after `finish` without an
//! intervening `reset`, or calling `finish` twice in a row) in debug builds
//! while collapsing to a zero-sized type in release builds so hot paths pay
//! no extra cost.

/// Internal lifecycle phases tracked by [`LifecycleGuard`] in debug builds.
///
/// The variant ordering mirrors the documented call sequence:
///
/// 1. `Fresh` — newly constructed, or just reset; first input may be supplied.
/// 2. `Streaming` — at least one `transcode` call has been observed.
/// 3. `Finished` — `finish` has been called; the only legal next step is
///    `reset` (which returns to `Fresh`).
#[cfg(debug_assertions)]
#[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)]
pub(crate) enum LifecyclePhase {
    /// Fresh or just-reset engine ready to accept the next logical stream.
    #[default]
    Fresh,
    /// At least one `transcode` call has been observed since the last reset.
    Streaming,
    /// `finish` has been called and the logical stream is closed.
    Finished,
}

/// Debug-only lifecycle guard for transcode engines.
///
/// The guard tracks the current [`LifecyclePhase`] in debug builds and runs
/// `debug_assert!` checks on every public entry point. In release builds it
/// is an empty type, so engines pay no runtime cost.
///
/// Lifecycle rules enforced in debug builds:
///
/// - `transcode` is rejected when the engine is `Finished`. Callers must
///   `reset` before starting another logical stream.
/// - `finish` is rejected when the engine is already `Finished`. Repeating
///   `finish` is almost always a bug.
/// - `reset` is always legal and returns the engine to `Fresh`.
///
/// `Fresh → finish` is intentionally allowed: stateless transcoders may
/// finalize an empty stream, and forcing a synthetic `transcode(&[])` call
/// just to satisfy the guard would be noise.
#[cfg(debug_assertions)]
#[derive(Debug, Default)]
pub(crate) struct LifecycleGuard {
    phase: LifecyclePhase,
}

#[cfg(not(debug_assertions))]
#[derive(Debug, Default)]
pub(crate) struct LifecycleGuard;

impl LifecycleGuard {
    /// Creates a guard in the [`LifecyclePhase::Fresh`] phase.
    ///
    /// # Returns
    ///
    /// Returns a guard ready to observe the first lifecycle event.
    #[inline(always)]
    #[must_use]
    pub(crate) const fn new() -> Self {
        #[cfg(debug_assertions)]
        {
            Self {
                phase: LifecyclePhase::Fresh,
            }
        }
        #[cfg(not(debug_assertions))]
        {
            Self
        }
    }

    /// Records a `reset` event. Always legal; returns the guard to
    /// [`LifecyclePhase::Fresh`].
    #[inline(always)]
    pub(crate) fn on_reset(&mut self) {
        #[cfg(debug_assertions)]
        {
            self.phase = LifecyclePhase::Fresh;
        }
    }

    /// Records a `transcode` entry. In debug builds, asserts the guard is
    /// not in [`LifecyclePhase::Finished`].
    ///
    /// # Panics
    ///
    /// In debug builds, panics when `transcode` is called after `finish`
    /// without an intervening `reset`.
    #[inline(always)]
    pub(crate) fn on_transcode(&mut self) {
        #[cfg(debug_assertions)]
        {
            debug_assert_ne!(
                LifecyclePhase::Finished,
                self.phase,
                "Transcoder::transcode called after finish without an \
                 intervening reset; call reset() to start a new logical \
                 stream",
            );
            if self.phase == LifecyclePhase::Fresh {
                self.phase = LifecyclePhase::Streaming;
            }
        }
    }

    /// Asserts the guard is allowed to enter `finish`. Does not change
    /// state, so callers that fail before completing finish (for example,
    /// capacity checks rejecting the supplied output) can retry without
    /// being marked closed.
    ///
    /// # Panics
    ///
    /// In debug builds, panics when `finish` is called twice without an
    /// intervening `reset`.
    #[inline(always)]
    pub(crate) fn on_finish_attempt(&self) {
        #[cfg(debug_assertions)]
        {
            debug_assert_ne!(
                LifecyclePhase::Finished,
                self.phase,
                "Transcoder::finish called twice without an intervening \
                 reset; the logical stream is already closed",
            );
        }
    }

    /// Commits the `Finished` state after `finish` actually completed. Call
    /// only on the success path.
    #[inline(always)]
    pub(crate) fn on_finish_success(&mut self) {
        #[cfg(debug_assertions)]
        {
            self.phase = LifecyclePhase::Finished;
        }
    }
}