Struct Extension

pub struct Extension {
    pub version: Version,
    pub name: ExtensionId,
    pub runtime_reqs: ExtensionSet,
    /* private fields */
}

A extension is a set of capabilities required to execute a graph.

These are normally defined once and shared across multiple graphs and operations wrapped in Arcs inside ExtensionRegistry.

Example

The following example demonstrates how to define a new extension with a custom operation and a custom type.

When using arcs, the extension can only be modified at creation time. The defined operations and types keep a Weak reference to their extension. We provide a helper method Extension::new_arc to aid their definition.

Extension::new_arc(
    ExtensionId::new_unchecked("my.extension"),
    Version::new(0, 1, 0),
    |ext, extension_ref| {
        // Add a custom type definition
        ext.add_type(
            "MyType".into(),
            vec![], // No type parameters
            "Some type".into(),
            TypeDefBound::any(),
            extension_ref,
        );
        // Add a custom operation
        ext.add_op(
            "MyOp".into(),
            "Some operation".into(),
            Signature::new_endo(vec![]),
            extension_ref,
        );
    },
);

Fields

version: Version

Extension version, follows semver.

name: ExtensionId

Unique identifier for the extension.

runtime_reqs: ExtensionSet

Runtime dependencies this extension has on other extensions.

Implementations

impl Extension

pub fn add_op( &mut self, name: OpName, description: String, signature_func: impl Into<SignatureFunc>, extension_ref: &Weak<Extension>, ) -> Result<&mut OpDef, ExtensionBuildError>

Add an operation definition to the extension. Must be a type scheme (defined by a PolyFuncTypeRV), a type scheme along with binary validation for type arguments (CustomValidator), or a custom binary function for computing the signature given type arguments (implementing [CustomSignatureFunc]).

This method requires a Weak reference to the Arc containing the extension being defined. The intended way to call this method is inside the closure passed to Extension::new_arc when defining the extension.

Example

Extension::new_arc(
    ExtensionId::new_unchecked("my.extension"),
    Version::new(0, 1, 0),
    |ext, extension_ref| {
        ext.add_op(
            "MyOp".into(),
            "Some operation".into(),
            Signature::new_endo(vec![]),
            extension_ref,
        );
    },
);

impl Extension

pub fn add_type( &mut self, name: TypeName, params: Vec<TypeParam>, description: String, bound: TypeDefBound, extension_ref: &Weak<Extension>, ) -> Result<&TypeDef, ExtensionBuildError>

Add an exported type to the extension.

This method requires a Weak reference to the std::sync::Arc containing the extension being defined. The intended way to call this method is inside the closure passed to Extension::new_arc when defining the extension.

Example

Extension::new_arc(
    ExtensionId::new_unchecked("my.extension"),
    Version::new(0, 1, 0),
    |ext, extension_ref| {
        ext.add_type(
            "MyType".into(),
            vec![], // No type parameters
            "Some type".into(),
            TypeDefBound::any(),
            extension_ref,
        );
    },
);

impl Extension

pub fn new(name: ExtensionId, version: Version) -> Self

Creates a new extension with the given name.

In most cases extensions are contained inside an Arc so that they can be shared across hugr instances and operation definitions.

See Extension::new_arc for a more ergonomic way to create boxed extensions.

pub fn new_arc( name: ExtensionId, version: Version, init: impl FnOnce(&mut Extension, &Weak<Extension>), ) -> Arc<Self>

Creates a new extension wrapped in an Arc.

The closure lets us use a weak reference to the arc while the extension is being built. This is necessary for calling Extension::add_op and Extension::add_type.

pub fn try_new_arc<E>( name: ExtensionId, version: Version, init: impl FnOnce(&mut Extension, &Weak<Extension>) -> Result<(), E>, ) -> Result<Arc<Self>, E>

Creates a new extension wrapped in an Arc, using a fallible initialization function.

The closure lets us use a weak reference to the arc while the extension is being built. This is necessary for calling Extension::add_op and Extension::add_type.

pub fn add_requirements(&mut self, runtime_reqs: impl Into<ExtensionSet>)

Extend the runtime requirements of this extension with another set of extensions.

pub fn get_op(&self, name: &OpNameRef) -> Option<&Arc<OpDef>>

Allows read-only access to the operations in this Extension

pub fn get_type(&self, type_name: &TypeNameRef) -> Option<&TypeDef>

Allows read-only access to the types in this Extension

pub fn get_value(&self, value_name: &ValueNameRef) -> Option<&ExtensionValue>

Allows read-only access to the values in this Extension

pub fn name(&self) -> &ExtensionId

Returns the name of the extension.

pub fn version(&self) -> &Version

Returns the version of the extension.

pub fn operations(&self) -> impl Iterator<Item = (&OpName, &Arc<OpDef>)>

Iterator over the operations of this Extension.

pub fn types(&self) -> impl Iterator<Item = (&TypeName, &TypeDef)>

Iterator over the types of this Extension.

pub fn add_value( &mut self, name: impl Into<ValueName>, typed_value: Value, ) -> Result<&mut ExtensionValue, ExtensionBuildError>

Add a named static value to the extension.

pub fn instantiate_extension_op( &self, name: &OpNameRef, args: impl Into<Vec<TypeArg>>, ) -> Result<ExtensionOp, SignatureError>

Instantiate an ExtensionOp which references an OpDef in this extension.

Trait Implementations

impl Clone for Extension

fn clone(&self) -> Extension

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Extension

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Extension

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for Extension

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Extension

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.