cqlib_core/compile/resource/
error.rs

1// This code is part of Cqlib.
2//
3// (C) Copyright China Telecom Quantum Group 2025-2026
4//
5// This code is licensed under the Apache License, Version 2.0.
6// You may obtain a copy of this license in the LICENSE.txt file in
7// the root directory of this source tree or at
8// http://www.apache.org/licenses/LICENSE-2.0.
9//
10// Any modifications or derivative works of this code must retain this
11// copyright notice, and modified files need to carry a notice indicating
12// that they have been altered from the originals.
13
14use crate::circuit::Qubit;
15use thiserror::Error;
16
17/// Errors raised while managing compiler-visible logical-qubit resources.
18///
19/// These errors distinguish unsupported requests and capacity limits from stale
20/// planner state and internal consistency failures. Callers may use resource
21/// availability errors to reject an algorithm candidate and try another one;
22/// consistency errors indicate that the compiler state must not be trusted.
23#[derive(Debug, Error, PartialEq, Eq)]
24pub enum ResourceError {
25    /// A resource request violates its input contract.
26    #[error("invalid resource request: {reason}")]
27    InvalidRequest {
28        /// Human-readable description of the violated request contract.
29        reason: String,
30    },
31    /// The requested number of ancillary qubits cannot be made available under
32    /// the active phase and policy.
33    #[error(
34        "insufficient {requirement} ancillary qubits: requested {requested}, available {available}"
35    )]
36    InsufficientResources {
37        /// Stable requirement name used in diagnostics.
38        requirement: &'static str,
39        /// Number of ancillary qubits requested by the caller.
40        requested: usize,
41        /// Number of ancillary qubits available under the active policy.
42        available: usize,
43    },
44    /// A resource operation would exceed the configured total-qubit limit.
45    #[error("resource capacity exceeded: requested total {requested_total}, limit {limit}")]
46    CapacityExceeded {
47        /// Maximum number of logical qubits allowed by the active limits.
48        limit: usize,
49        /// Total logical-qubit count required by the attempted operation.
50        requested_total: usize,
51    },
52    /// A qubit identifier conflicts with an existing resource or circuit qubit.
53    #[error("duplicate resource qubit {qubit}")]
54    DuplicateQubit {
55        /// Conflicting logical qubit.
56        qubit: Qubit,
57    },
58    /// A plan was created against an older resource-manager snapshot.
59    ///
60    /// The caller must preview the candidate again before attempting to commit.
61    #[error(
62        "stale resource plan: plan revision {plan_revision}, current revision {current_revision}"
63    )]
64    StalePlan {
65        /// Revision captured while previewing the plan.
66        plan_revision: u64,
67        /// Current manager revision.
68        current_revision: u64,
69    },
70    /// A plan was created by a different resource manager.
71    #[error("resource plan belongs to another resource manager")]
72    ForeignPlan,
73    /// A lease belongs to another manager, is unknown, has already been
74    /// released, or does not match its active record.
75    #[error("unknown or released resource lease {lease_id}")]
76    UnknownLease {
77        /// Lease identifier supplied by the caller.
78        lease_id: u64,
79    },
80    /// An operation is not valid in the current resource phase.
81    #[error(
82        "resource operation '{operation}' requires phase {expected}, current phase is {actual}"
83    )]
84    InvalidPhase {
85        /// Stable resource-manager operation name.
86        operation: &'static str,
87        /// Required phase name.
88        expected: &'static str,
89        /// Current phase name.
90        actual: &'static str,
91    },
92    /// No fresh logical-qubit identifier can be represented by [`Qubit`].
93    #[error("cannot allocate logical ancillary qubit: qubit identifier overflow")]
94    QubitIdOverflow,
95    /// An internal monotonic identifier can no longer be incremented.
96    #[error("resource {counter} counter overflow")]
97    CounterOverflow {
98        /// Stable name of the exhausted counter.
99        counter: &'static str,
100    },
101    /// The circuit qubit set and manager resource records no longer match.
102    ///
103    /// This reports a compiler-state consistency failure rather than an
104    /// ordinary unavailable-resource condition.
105    #[error("circuit and resource manager are inconsistent: {reason}")]
106    CircuitResourceMismatch {
107        /// Human-readable description of the detected mismatch.
108        reason: String,
109    },
110    /// An idle boundary was reached before all leases were released.
111    #[error("resource manager still has {count} active lease(s)")]
112    ActiveLeaseRemaining {
113        /// Number of active leases that must be released.
114        count: usize,
115    },
116}
cqlib_core/compile/resource/error.rs

cqlib_core/compile/resource/
error.rs
