8000 WebAssembly support in Tarantool via `luawasm` by mandesero · Pull Request #11793 · tarantool/tarantool · GitHub
[go: up one dir, main page]
Skip to content

WebAssembly support in Tarantool via luawasm #11793

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
wants to merge 5 commits into
base: master
Choose a base branch
from
Draft

WebAssembly support in Tarantool via luawasm #11793

wants to merge 5 commits into from

Conversation

mandesero
Copy link
Contributor

This PR introduces a new builtin module luawasm, which integrates WebAssembly components into Tarantool.

At its core, luawasm is a Lua wrapper around the native runtime wasm.
The native library provides a minimal low-level API:

  • load(path[, opts]) -> uid - load a component from a .wasm file.
  • run(uid[, opts]) -> handle - start the component using wasi:cli/run in a background thread.
  • join(handle) - wait for a background run to finish.
  • call(uid, func, ...) -> any - synchronously invoke an exported function.
  • batch(uid, calls) -> table - call multiple exports sequentially.
  • drop(uid) - unload a component.
  • exports(uid) -> table - enumerate available exports.

The luawasm module is designed to make working with WebAssembly inside Tarantool convenient and natural for Lua developers. While the underlying wasm.so library exposes a low-level API, luawasm wraps it into a higher-level, Lua-style interface with easy access to exported functions, component lifecycle helpers, and integration with Tarantool configuration.

luawasm

Public API (high-level)

  • obj:help() - print all available exports with signatures (including interface-scoped).
  • obj:<export>(...) - call a top-level exported function.
  • obj:<export>:help() - print the signature and docstring for <export>.
  • obj.iface.<iface>.<export>(...) - call an export inside interface <iface>.
  • obj.iface.<iface>.<export>:help() - print signature for that interface export.
  • obj:batch({ {obj:<export>, a, b}, {obj.iface.<iface>.<export>, x} }) - run multiple calls in one worker.
  • obj:run() / obj:join() - run wasi:cli/run entry point in background and wait for completion.
  • obj:meta() - return component metadata (paths, world, language, etc.).
  • obj:drop() - unload the component and remove it from the registry.

Integration with Tarantool config

Components can be described under wasm.components in YAML configuration and will be auto-loaded at startup into box.wasm.components. Access is unified via box.wasm.get(name).

Example: Lua usage

local wasm = require('luawasm')

local hello = wasm:new{
    wasm = './hello.wasm',
    config = {
        env   = { vars = { GREETING = 'Tarantool' } },
        stdio = { stdout_path = './hello.log' },
    },
}

-- call an exported function
print(hello:say_hello('Alice'))
-- -> "Hello, Alice! From exported function."

-- run in background via wasi:cli/run
hello:run()
hello:join()

Example: Configuration usage

wasm:
  components:
    hello:
      path: ./hello.wasm
      autorun: true
      env:
        vars:
          GREETING: 'Tarantool'
      stdio:
        stdout_path: ./hello.log

On startup:

tarantool> hello = box.wasm.get('hello')
tarantool> hello:say_hello("Alice")
---
- Hello, Alice! From exported function.
...

@mandesero
cmake: add TARANTOOL_WASM option
bddaf72 
This patch introduces a CMake option `TARANTOOL_WASM` to disable signal
stack setup in fiber. When enabled, the signal stack setup in fiber is
skipped.

The option is disabled by default.

NO_DOC=later
NO_CHANGELOG=later
NO_TEST=later
@mandesero
luawasm: add builtin module to run WASM components
eacbf94 
This patch introduces a new built-in Lua module `luawasm`,
which provides a thin wrapper around Tarantool’s WASM runtime.
It simplifies loading a component, calling its exported
functions, and managing background execution.

```lua
local wasm = require('luawasm')
local m = wasm:new({ dir = "<path-to-wasm-component>" })

-- Call any exported function from the component
m:<some-export-function>(...)

-- Display information about all available exports
m:help()

-- Run the component’s `run()` function in background
m:run()

-- Wait for the background task to complete
m:join()
```

Note: This module requires Tarantool to be built
with `-DTARANTOOL_WASM=ON`.

NO_CHANGELOG=later
NO_TEST=later
NO_DOC=later
@mandesero mandesero force-pushed the mandesero/luawasm branch 2 times, most recently from 310d334 to 3a4111e Compare August 29, 2025 10:58
@mandesero
config: support luawasm module
3b44b9a 
This patch introduces declarative configuration support
for WebAssembly components via the `luawasm` module.

With this change, users can describe wasm components
directly in the Tarantool configuration file. Components
are automatically loaded on instance startup and registered
under `box.wasm.components`.

Access to a component is available through:
```lua
box.wasm.get(<..component-name..>)
```

NO_CHANGELOG=later
NO_TEST=later
NO_DOC=later
@mandesero
doc: provide configuration and component example
5416594 
This patch adds initial documentation for the `luawasm` module and
provides a working component example.

NO_CHANGELOG=later
NO_TEST=later
NO_DOC=later
@mandesero
test: add basic luawasm test suite
33d5ebc 
NO_DOC=later
NO_CHANGELOG=later
@coveralls
7A7A Copy link

Coverage Status

coverage: 87.6% (-0.01%) from 87.614%
when pulling 33d5ebc on mandesero:mandesero/luawasm
into 5177db1
on tarantool:master.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@mandesero @coveralls
0