Struct CompositionGraph 

pub struct CompositionGraph { /* private fields */ }

Represents a composition graph.

A composition graph is a directed acyclic graph (DAG) that represents a WebAssembly composition.

Types may be defined directly in a composition graph or referenced from packages registered with the graph.

There are four supported node types:

• a type definition node representing the definition of an exported named type.
• an import node representing an imported item.
• an instantiation node representing an instantiation of a package.
• an alias node representing an alias of an exported item from an instance.

There are three supported edge types:

• a type dependency edge from a type definition node to any dependent defined types; type dependency edges are implicitly added to the graph when a type is defined.
• an alias edge from an any node that is an instance to an alias node; alias edges are implicitly added to the graph when an alias node is added.
• an instantiation argument edge from any node to an instantiation node; instantiation argument edges contain a set of instantiation arguments satisfied by the target node; unsatisfied arguments are automatically imported when encoding the composition graph.

Any node in the graph may be marked to be exported from the encoded graph; note that type definition nodes are always exported and may not be unmarked.

Implementations

impl CompositionGraph

pub fn new() -> Self

Creates a new composition graph.

pub fn types(&self) -> &Types

Gets a reference to the type collection of the graph.

pub fn types_mut(&mut self) -> &mut Types

Gets a mutable reference to the type collection of the graph.

This type collection is used to define types directly in the graph.

pub fn nodes(&self) -> impl Iterator<Item = &Node> + '_

Gets the nodes in the graph.

pub fn node_ids(&self) -> impl Iterator<Item = NodeId> + '_

Gets the identifiers for every node in the graph.

pub fn packages(&self) -> impl Iterator<Item = &Package> + '_

Gets the packages currently registered with the graph.

pub fn register_package( &mut self, package: Package, ) -> Result<PackageId, RegisterPackageError>

Registers a package with the graph.

Packages are used to create instantiations, but are not directly a part of the graph.

Panics

Panics if the given package’s type is not contained within the graph’s types collection.

pub fn unregister_package(&mut self, package: PackageId)

Unregisters a package from the graph.

Any edges and nodes associated with the package are also removed.

Panics

Panics if the given package identifier is invalid.

pub fn get_package_by_name( &self, name: &str, version: Option<&Version>, ) -> Option<(PackageId, &Package)>

Gets the registered package of the given package name and version.

Returns None if a package with the specified name and version has not been registered with the graph.

pub fn define_type( &mut self, name: impl Into<String>, ty: Type, ) -> Result<NodeId, DefineTypeError>

Adds a type definition node to the graph.

The graph must not already have a node exported with the same name.

This method will implicitly add dependency edges to other defined types.

If the provided type has already been defined, the previous node will be returned and an additional export name will be associated with the node.

Panics

This method panics if the provided type is not contained within the graph’s types collection.

pub fn import( &mut self, name: impl Into<String>, kind: ItemKind, ) -> Result<NodeId, ImportError>

Adds an import node to the graph.

If the provided import name is invalid or if an import already exists with the same name, an error is returned.

Panics

This method panics if the provided kind is not contained within the graph’s types collection.

pub fn get_import_name(&self, node: NodeId) -> Option<&str>

Gets the name used by an import node.

Returns None if the specified node is not an import node.

Panics

Panics if the specified node id is invalid.

pub fn instantiate(&mut self, package: PackageId) -> NodeId

Adds an instantiation node to the graph.

Initially the instantiation will have no satisfied arguments.

Use set_instantiation_argument to set an argument on an instantiation node.

Panics

This method panics if the provided package id is invalid.

pub fn alias_instance_export( &mut self, instance: NodeId, export: &str, ) -> Result<NodeId, AliasError>

Adds an alias node to the graph.

The provided node must be an instance and the export name must match an export of the instance.

If an alias already exists for the export, the existing alias node will be returned.

An implicit alias edge will be added from the instance to the alias node.

Panics

Panics if the provided node id is invalid.

pub fn get_alias_source(&self, alias: NodeId) -> Option<(NodeId, &str)>

Gets the source node and export name of an alias node.

Returns None if the node is not an alias.

pub fn get_instantiation_arguments( &self, instantiation: NodeId, ) -> impl Iterator<Item = (&str, NodeId)>

Gets the satisfied arguments of an instantiation node.

Returns an iterator over the argument names and the node id used to satisfy the argument.

If the node identifier is invalid or if the node is not an instantiation node, an empty iterator is returned.

pub fn set_node_name(&mut self, node: NodeId, name: impl Into<String>)

Sets the name of a node in the graph.

Node names are recorded in a names custom section when the graph is encoded.

Panics

This method panics if the provided node id is invalid.

pub fn export( &mut self, node: NodeId, name: impl Into<String>, ) -> Result<(), ExportError>

Marks the given node for export when the composition graph is encoded.

Returns an error if the provided export name is invalid.

Panics

This method panics if the provided node id is invalid.

pub fn get_export(&self, name: &str) -> Option<NodeId>

Gets the node being exported by the given name.

Returns None if there is no node exported by that name.

pub fn unexport(&mut self, node: NodeId) -> Result<(), UnexportError>

Unmarks the given node from being exported from an encoding of the graph.

Returns an error if the given node is a type definition, as type definitions must be exported.

Panics

This method panics if the provided node id is invalid.

pub fn remove_node(&mut self, node: NodeId)

Removes a node from the graph.

All incoming and outgoing edges of the node are also removed.

If the node has dependent defined types, the dependent define types are also removed.

If the node has aliases, the aliased nodes are also removed.

Panics

This method panics if the provided node id is invalid.

pub fn set_instantiation_argument( &mut self, instantiation: NodeId, argument_name: &str, argument: NodeId, ) -> Result<(), InstantiationArgumentError>

Sets an argument of an instantiation node to the provided argument node.

This method adds an instantiation argument edge from the argument node to the instantiation node.

The provided instantiation node must be an instantiation.

The argument name must be a valid import on the instantiation node and not already have an incoming edge from a different argument node.

The argument node must be type-compatible with the argument of the instantiation node.

If an edge already exists between the argument and the instantiation node, this method returns Ok(_).

Panics

This method will panic if the provided node ids are invalid.

pub fn unset_instantiation_argument( &mut self, instantiation: NodeId, argument_name: &str, argument: NodeId, ) -> Result<(), InstantiationArgumentError>

Unsets an argument of an instantiation node that was previously set to the provided argument node.

This method removes an instantiation argument edge from the argument node to the instantiation node if the nodes are connected; if they are not connected, this method is a no-op.

The provided instantiation node must be an instantiation.

The argument name must be a valid import on the instantiation node.

Panics

This method will panic if the provided node ids are invalid.

pub fn encode(&self, options: EncodeOptions<'_>) -> Result<Vec<u8>, EncodeError>

Encodes the composition graph as a new WebAssembly component.

An error will be returned if the graph contains a dependency cycle.

pub fn decode(_data: &[u8]) -> Result<CompositionGraph, DecodeError>

Decodes a composition graph from the bytes of a WebAssembly component.

pub fn imports(&self) -> impl Iterator<Item = (&str, ItemKind, Option<NodeId>)>

Yields an iterator over the resolved imports (both implicit and explicit) of the graph.

The iterator returns the name, the ItemKind, and an optional node id for explicit imports.

Trait Implementations

impl Clone for CompositionGraph

fn clone(&self) -> CompositionGraph

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for CompositionGraph

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

Formats the value using the given formatter.

impl Default for CompositionGraph

fn default() -> CompositionGraph

Returns the “default value” for a type.

impl Index<NodeId> for CompositionGraph

type Output = Node

The returned type after indexing.

fn index(&self, index: NodeId) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<PackageId> for CompositionGraph

type Output = Package

The returned type after indexing.

fn index(&self, index: PackageId) -> &Self::Output

Performs the indexing (container[index]) operation.