Struct Linker 

pub struct Linker { /* private fields */ }

The Linker is responsible for analyzing the input modules and libraries provided to the assembler, and linking them together.

The core conceptual data structure of the linker is the module graph, which is implemented by a vector of module nodes, and a call graph, which is implemented as an adjacency matrix of item nodes and the outgoing edges from those nodes, representing references from that item to another symbol (typically as the result of procedure invocation, hence “call” graph).

Each item/symbol known to the linker is given a global item index, which is actually a pair of indices: a module index (which indexes into the vector of module nodes), and an item index (which indexes into the items defined by a module). These global item indices function as a unique identifier within the linker, to a specific item, and can be resolved to either the original syntax tree of the item, or to metadata about the item retrieved from previously- assembled MAST.

The process of linking involves two phases:

1. Setting up the linker context, by providing the set of inputs to link together
2. Analyzing and rewriting the symbols known to the linker, as needed, to ensure that all symbol references are resolved to concrete definitions.

The assembler will call Self::link once it has provided all inputs that it wants to link, which will, when successful, return the set of module indices corresponding to the modules that comprise the public interface of the assembled artifact. The assembler then constructs the MAST starting from the exported procedures of those modules, recursively tracing the call graph based on whether or not the callee is statically or dynamically linked. In the static linking case, any procedures referenced in a statically-linked library or module will be included in the assembled artifact. In the dynamic linking case, referenced procedures are instead referenced in the assembled artifact only by their MAST root.

Implementations

impl Linker

Constructors

pub fn new(source_manager: Arc<dyn SourceManager>) -> Self

Instantiate a new Linker, using the provided SourceManager to resolve source info.

pub fn link_library(&mut self, library: LinkLibrary) -> Result<(), LinkerError>

Registers library and all of its modules with the linker, according to its linkage

pub fn link_assembled_modules( &mut self, modules: impl IntoIterator<Item = ModuleInfo>, ) -> Result<(), LinkerError>

Registers a set of MAST modules with the linker.

If called directly, the modules will default to being dynamically linked. You must use Self::link_library if you wish to statically link a set of assembled modules.

pub fn link_assembled_module( &mut self, module: ModuleInfo, ) -> Result<ModuleIndex, LinkerError>

Registers a MAST module with the linker.

If called directly, the module will default to being dynamically linked. You must use Self::link_library if you wish to statically link module.

pub fn link_modules( &mut self, modules: impl IntoIterator<Item = Box<Module>>, ) -> Result<Vec<ModuleIndex>, LinkerError>

Registers a set of AST modules with the linker.

See Self::link_module for more details.

pub fn link_module( &mut self, module: &mut Module, ) -> Result<ModuleIndex, LinkerError>

Registers an AST module with the linker.

A module provided to this method is presumed to be dynamically linked, unless specifically handled otherwise by the assembler. In particular, the assembler will only statically link the set of AST modules provided to Self::link, as they are expected to comprise the public interface of the assembled artifact.

Errors

This operation can fail for the following reasons:

• Module with same Path is in the graph already
• Too many modules in the graph

Panics

This function will panic if the number of modules exceeds the maximum representable ModuleIndex value, u16::MAX.

impl Linker

Kernels

pub fn kernel(&self) -> &Kernel

pub fn has_nonempty_kernel(&self) -> bool

impl Linker

Analysis

pub fn link( &mut self, modules: impl IntoIterator<Item = Box<Module>>, ) -> Result<Vec<ModuleIndex>, LinkerError>

Links modules using the current state of the linker.

Returns the module indices corresponding to the provided modules, which are expected to provide the public interface of the final assembled artifact.

pub fn link_kernel( &mut self, kernel: Box<Module>, ) -> Result<Vec<ModuleIndex>, LinkerError>

Links kernel using the current state of the linker.

Returns the module index of the kernel module, which is expected to provide the public interface of the final assembled kernel.

This differs from link in that we allow all AST modules in the module graph access to kernel features, e.g. caller, as if they are defined by the kernel module itself.

impl Linker

Accessors/Queries

pub fn libraries(&self) -> impl Iterator<Item = &LinkLibrary>

Get an iterator over the external libraries the linker has linked against

pub fn topological_sort_from_root( &self, caller: GlobalItemIndex, ) -> Result<Vec<GlobalItemIndex>, CycleError>

Compute the topological sort of the callgraph rooted at caller

pub fn get_procedure_index_by_digest( &self, procedure_digest: &Word, ) -> Option<GlobalItemIndex>

Returns a procedure index which corresponds to the provided procedure digest.

Note that there can be many procedures with the same digest - due to having the same code, and/or using different decorators which don’t affect the MAST root. This method returns an arbitrary one.

pub fn resolve_invoke_target( &self, caller: &SymbolResolutionContext, target: &InvocationTarget, ) -> Result<SymbolResolution, LinkerError>

Resolves target from the perspective of caller.

pub fn resolve_alias_target( &self, caller: &SymbolResolutionContext, target: &Alias, ) -> Result<SymbolResolution, LinkerError>

Resolves target from the perspective of caller.

pub fn resolve_path( &self, caller: &SymbolResolutionContext, path: &Path, ) -> Result<SymbolResolution, LinkerError>

Resolves path from the perspective of caller.

pub fn find_module_index(&self, path: &Path) -> Option<ModuleIndex>

Resolve a Path to a ModuleIndex in this graph

pub fn find_module(&self, path: &Path) -> Option<&LinkModule>

Resolve a Path to a Module in this graph

Trait Implementations

impl Clone for Linker

fn clone(&self) -> Linker

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Linker

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

Formats the value using the given formatter.

impl Index<GlobalItemIndex> for Linker

type Output = Symbol

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl Index<ModuleIndex> for Linker

type Output = LinkModule

The returned type after indexing.

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

Performs the indexing (container[index]) operation.