Class: Wasmtime::Component::LinkerInstance

Inherits:

Object

• Object
• Wasmtime::Component::LinkerInstance

Defined in:

ext/src/ruby_api/component/linker.rs

Overview

LinkerInstances are builder-style, ephemeral objects that can only be used within the block to which they get yielded. Calling methods outside of the block will raise.

See Also:

• Wasmtime's Rust doc

Instance Method Summary

• #func_new(name) {|*args| ... } ⇒ LinkerInstance

  Define a host function in this linker instance.

• #instance(name) {|instance| ... } ⇒ LinkerInstance

  Defines a nested instance within the instance.

• #module(name, mod) ⇒ Object

Instance Method Details

#func_new(name) {|*args| ... } ⇒ LinkerInstance

Define a host function in this linker instance.

Host functions return plain Ruby values which are automatically validated and converted based on the function's type signature from the component.

Examples:

Simple scalar return

root.func_new("add") do |a, b|
  a + b  # Returns u32
end

Returning a list

root.func_new("get-numbers") do
  [1, 2, 3]  # Returns list<s32>
end

Returning a tuple

root.func_new("make-tuple") do |n, s, b|
  [n, s, b]  # Returns tuple<u32, string, bool>
end

Complex types (records, results, etc.)

root.func_new("make-point") do |x, y|
  {"x" => x, "y" => y}  # Returns record with x and y fields
end

Parameters:

• name (String) —

  The function name

Yields:

• (*args) —

  The block implementing the host function

Yield Parameters:

• args (Array<Object>) —

  The function arguments, converted from component values

Yield Returns:

• (Object) —

  Result value matching the function's return type. Use arrays for lists and tuples, hashes for records.

Returns:

• (LinkerInstance) —

  self

# File 'ext/src/ruby_api/component/linker.rs', line 315

fn func_new(_ruby: &Ruby, rb_self: Obj<Self>, args: &[Value]) -> Result<Obj<Self>, Error> {
    let args = scan_args::<(RString,), (), (), (), (), Proc>(args)?;
    let (name,) = args.required;
    let callable = args.block;

    let name_str = unsafe { name.as_str() }?;

    // Get parent Linker - we'll store the callable there to prevent GC
    // (rb_self is ephemeral and won't keep references alive after the block ends)
    let parent_linker: Obj<Linker> = Obj::try_convert(rb_self.parent_linker)?;
    parent_linker.refs.borrow_mut().push(callable.as_value());

    // Create the closure that will be called from Wasm
    let func_closure = make_component_func_closure(callable.into());

    let Ok(mut maybe_instance) = rb_self.inner.try_borrow_mut() else {
        return err!("LinkerInstance is not reentrant");
    };

    let inner = maybe_instance.get_mut()?;
    inner
        .func_new(name_str, func_closure)
        .map_err(|e| error!("failed to define host function: {}", e))?;

    Ok(rb_self)
}

#instance(name) {|instance| ... } ⇒ LinkerInstance

Defines a nested instance within the instance.

Parameters:

• name (String)

Yields:

• (instance) —

  The block allows configuring the Wasmtime::Component::LinkerInstance; outside of this scope the instance becomes unusable.

Yield Parameters:

• instance (LinkerInstance)

Returns:

• (LinkerInstance) —

  self

# File 'ext/src/ruby_api/component/linker.rs', line 253

fn instance(ruby: &Ruby, rb_self: Obj<Self>, name: RString) -> Result<Obj<Self>, Error> {
    let Ok(mut maybe_instance) = rb_self.inner.try_borrow_mut() else {
        return err!("LinkerInstance is not reentrant");
    };

    let name_str = unsafe { name.as_str() }?;
    let inner = maybe_instance.get_mut()?;
    let nested_inner = inner.instance(name_str).map_err(|e| error!("{}", e))?;

    // Build nested path: if parent is "", use name; otherwise "parent/name"
    let nested_path = if rb_self.path.is_empty() {
        name_str.to_string()
    } else {
        format!("{}/{}", rb_self.path, name_str)
    };

    let nested_instance = ruby.obj_wrap(LinkerInstance::from_inner(
        nested_inner,
        nested_path,
        rb_self.parent_linker,
    ));
    let block_result: Result<Value, _> = ruby.yield_value(nested_instance);
    nested_instance.take_inner();

    match block_result {
        Ok(_) => Ok(rb_self),
        Err(e) => Err(e),
    }
}

#module(name, mod) ⇒ Object

Parameters:

• name (String)
• mod (Module)

# File 'ext/src/ruby_api/component/linker.rs', line 232

fn module(rb_self: Obj<Self>, name: RString, module: &Module) -> Result<Obj<Self>, Error> {
    let Ok(mut maybe_instance) = rb_self.inner.try_borrow_mut() else {
        return err!("LinkerInstance is not reentrant");
    };

    let inner = maybe_instance.get_mut()?;
    inner
        .module(unsafe { name.as_str()? }, module.get())
        .map_err(|e| error!("{}", e))?;

    Ok(rb_self)
}