hugr_core/extension/
resolution.rs

1//! Utilities for resolving operations and types present in a HUGR, and updating
2//! the list of used extensions. The functionalities of this module can be
3//! called from the type methods [`crate::Hugr::resolve_extension_defs`],
4//! [`crate::ops::OpType::used_extensions`], and
5//! [`crate::types::Signature::used_extensions`].
6//!
7//! When listing "used extensions" we only care about _definitional_ extension
8//! requirements, i.e., the operations and types that are required to define the
9//! HUGR nodes and wire types. This is computed from the union of all extension
10//! required across the HUGR.
11//!
12//! This is distinct from _runtime_ extension requirements, which are defined
13//! more granularly in each function signature by the `runtime_reqs`
14//! field. See the `extension_inference` feature and related modules for that.
15//!
16//! Note: These procedures are only temporary until `hugr-model` is stabilized.
17//! Once that happens, hugrs will no longer be directly deserialized using serde
18//! but instead will be created by the methods in `crate::import`. As these
19//! (will) automatically resolve extensions as the operations are created,
20//! we will no longer require this post-facto resolution step.
21
22mod extension;
23mod ops;
24mod types;
25mod types_mut;
26mod weak_registry;
27
28pub use weak_registry::WeakExtensionRegistry;
29
30pub(crate) use ops::{collect_op_extension, resolve_op_extensions};
31pub(crate) use types::{collect_op_types_extensions, collect_signature_exts};
32pub(crate) use types_mut::resolve_op_types_extensions;
33use types_mut::{
34    resolve_custom_type_exts, resolve_type_exts, resolve_typearg_exts, resolve_value_exts,
35};
36
37use derive_more::{Display, Error, From};
38
39use super::{Extension, ExtensionId, ExtensionRegistry, ExtensionSet};
40use crate::ops::constant::ValueName;
41use crate::ops::custom::OpaqueOpError;
42use crate::ops::{NamedOp, OpName, OpType, Value};
43use crate::types::{CustomType, FuncTypeBase, MaybeRV, TypeArg, TypeBase, TypeName};
44use crate::Node;
45
46/// Update all weak Extension pointers inside a type.
47pub fn resolve_type_extensions<RV: MaybeRV>(
48    typ: &mut TypeBase<RV>,
49    extensions: &WeakExtensionRegistry,
50) -> Result<(), ExtensionResolutionError> {
51    let mut used_extensions = WeakExtensionRegistry::default();
52    resolve_type_exts(None, typ, extensions, &mut used_extensions)
53}
54
55/// Update all weak Extension pointers in a custom type.
56pub fn resolve_custom_type_extensions(
57    typ: &mut CustomType,
58    extensions: &WeakExtensionRegistry,
59) -> Result<(), ExtensionResolutionError> {
60    let mut used_extensions = WeakExtensionRegistry::default();
61    resolve_custom_type_exts(None, typ, extensions, &mut used_extensions)
62}
63
64/// Update all weak Extension pointers inside a type argument.
65pub fn resolve_typearg_extensions(
66    arg: &mut TypeArg,
67    extensions: &WeakExtensionRegistry,
68) -> Result<(), ExtensionResolutionError> {
69    let mut used_extensions = WeakExtensionRegistry::default();
70    resolve_typearg_exts(None, arg, extensions, &mut used_extensions)
71}
72
73/// Update all weak Extension pointers inside a constant value.
74pub fn resolve_value_extensions(
75    value: &mut Value,
76    extensions: &WeakExtensionRegistry,
77) -> Result<(), ExtensionResolutionError> {
78    let mut used_extensions = WeakExtensionRegistry::default();
79    resolve_value_exts(None, value, extensions, &mut used_extensions)
80}
81
82/// Errors that can occur during extension resolution.
83#[derive(Debug, Display, Clone, Error, From, PartialEq)]
84#[non_exhaustive]
85pub enum ExtensionResolutionError {
86    /// Could not resolve an opaque operation to an extension operation.
87    #[display("Error resolving opaque operation: {_0}")]
88    #[from]
89    OpaqueOpError(OpaqueOpError),
90    /// An operation requires an extension that is not in the given registry.
91    #[display(
92        "{op}{} requires extension {missing_extension}, but it could not be found in the extension list used during resolution. The available extensions are: {}",
93        node.map(|n| format!(" in {}", n)).unwrap_or_default(),
94        available_extensions.join(", ")
95    )]
96    MissingOpExtension {
97        /// The node that requires the extension.
98        node: Option<Node>,
99        /// The operation that requires the extension.
100        op: OpName,
101        /// The missing extension
102        missing_extension: ExtensionId,
103        /// A list of available extensions.
104        available_extensions: Vec<ExtensionId>,
105    },
106    /// A type references an extension that is not in the given registry.
107    #[display(
108        "Type {ty}{} requires extension {missing_extension}, but it could not be found in the extension list used during resolution. The available extensions are: {}",
109        node.map(|n| format!(" in {}", n)).unwrap_or_default(),
110        available_extensions.join(", ")
111    )]
112    MissingTypeExtension {
113        /// The node that requires the extension.
114        node: Option<Node>,
115        /// The type that requires the extension.
116        ty: TypeName,
117        /// The missing extension
118        missing_extension: ExtensionId,
119        /// A list of available extensions.
120        available_extensions: Vec<ExtensionId>,
121    },
122    /// A type definition's `extension_id` does not match the extension it is in.
123    #[display(
124        "Type definition {def} in extension {extension} declares it was defined in {wrong_extension} instead."
125    )]
126    WrongTypeDefExtension {
127        /// The extension that defines the type.
128        extension: ExtensionId,
129        /// The type definition name.
130        def: TypeName,
131        /// The extension declared in the type definition's `extension_id`.
132        wrong_extension: ExtensionId,
133    },
134    /// An operation definition's `extension_id` does not match the extension it is in.
135    #[display(
136        "Operation definition {def} in extension {extension} declares it was defined in {wrong_extension} instead."
137    )]
138    WrongOpDefExtension {
139        /// The extension that defines the op.
140        extension: ExtensionId,
141        /// The op definition name.
142        def: OpName,
143        /// The extension declared in the op definition's `extension_id`.
144        wrong_extension: ExtensionId,
145    },
146    /// The type of an `OpaqueValue` has types which do not reference their defining extensions.
147    #[display("The type of the opaque value '{value}' requires extensions {missing_extensions}, but does not reference their definition.")]
148    InvalidConstTypes {
149        /// The value that has invalid types.
150        value: ValueName,
151        /// The missing extension.
152        missing_extensions: ExtensionSet,
153    },
154}
155
156impl ExtensionResolutionError {
157    /// Create a new error for missing operation extensions.
158    pub fn missing_op_extension(
159        node: Option<Node>,
160        op: &OpType,
161        missing_extension: &ExtensionId,
162        extensions: &ExtensionRegistry,
163    ) -> Self {
164        Self::MissingOpExtension {
165            node,
166            op: NamedOp::name(op),
167            missing_extension: missing_extension.clone(),
168            available_extensions: extensions.ids().cloned().collect(),
169        }
170    }
171
172    /// Create a new error for missing type extensions.
173    pub fn missing_type_extension(
174        node: Option<Node>,
175        ty: &TypeName,
176        missing_extension: &ExtensionId,
177        extensions: &WeakExtensionRegistry,
178    ) -> Self {
179        Self::MissingTypeExtension {
180            node,
181            ty: ty.clone(),
182            missing_extension: missing_extension.clone(),
183            available_extensions: extensions.ids().cloned().collect(),
184        }
185    }
186}
187
188/// Errors that can occur when collecting extension requirements.
189#[derive(Debug, Display, Clone, Error, From, PartialEq)]
190#[non_exhaustive]
191pub enum ExtensionCollectionError {
192    /// An operation requires an extension that is not in the given registry.
193    #[display(
194        "{op}{} contains custom types for which have lost the reference to their defining extensions. Dropped extensions: {}",
195        if let Some(node) = node { format!(" ({})", node) } else { "".to_string() },
196        missing_extensions.join(", ")
197    )]
198    DroppedOpExtensions {
199        /// The node that is missing extensions.
200        node: Option<Node>,
201        /// The operation that is missing extensions.
202        op: OpName,
203        /// The missing extensions.
204        missing_extensions: Vec<ExtensionId>,
205    },
206    /// A signature requires an extension that is not in the given registry.
207    #[display(
208        "Signature {signature} contains custom types for which have lost the reference to their defining extensions. Dropped extensions: {}",
209        missing_extensions.join(", ")
210    )]
211    DroppedSignatureExtensions {
212        /// The signature that is missing extensions.
213        signature: String,
214        /// The missing extensions.
215        missing_extensions: Vec<ExtensionId>,
216    },
217}
218
219impl ExtensionCollectionError {
220    /// Create a new error when operation extensions have been dropped.
221    pub fn dropped_op_extension(
222        node: Option<Node>,
223        op: &OpType,
224        missing_extension: impl IntoIterator<Item = ExtensionId>,
225    ) -> Self {
226        Self::DroppedOpExtensions {
227            node,
228            op: NamedOp::name(op),
229            missing_extensions: missing_extension.into_iter().collect(),
230        }
231    }
232
233    /// Create a new error when signature extensions have been dropped.
234    pub fn dropped_signature<RV: MaybeRV>(
235        signature: &FuncTypeBase<RV>,
236        missing_extension: impl IntoIterator<Item = ExtensionId>,
237    ) -> Self {
238        Self::DroppedSignatureExtensions {
239            signature: format!("{signature}"),
240            missing_extensions: missing_extension.into_iter().collect(),
241        }
242    }
243}
244
245#[cfg(test)]
246mod test;
hugr_core/extension/resolution.rs

hugr_core/extension/
resolution.rs
