You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
> **Note**: This is an **Lua 5.5** lib through AI-assisted programming.
7
7
8
-
luars is a pure Rust Lua 5.5 runtime and embedding toolkit. This repository contains the core library, derive macros, the interpreter, debugger integration, a WASM target, and several host-facing examples.
8
+
luars is a pure Rust Lua 5.5 runtime and embedding toolkit. This repository contains the core runtime, derive macros, the standalone interpreter, debugger integration, a WASM target, benchmark scripts, and host-facing examples.
9
9
10
-
The repository-level documentation is intentionally focused on the high-level `Lua` API. Lower-level `LuaVM` APIs still exist, but the default examples and guides now use the high-level surface first.
10
+
The project is shaped around three priorities:
11
11
12
-
## Quick Start
12
+
- performance that is measured against native Lua instead of hand-waved
13
+
- safety work that keeps `unsafe` narrowly scoped to representation and truly hot VM paths
14
+
- compatibility validated against the upstream Lua test suite, not only custom examples
15
+
16
+
## Why luars
17
+
18
+
### Performance
19
+
20
+
The repository ships benchmark runners and published benchmark snapshots instead of a single cherry-picked number.
21
+
22
+
Current Windows snapshot on a Ryzen 7 5800X, measured against native Lua 5.5 on the same machine:
23
+
24
+
| Area | Relative throughput vs native Lua |
25
+
|------|-----------------------------------|
26
+
| Arithmetic | 111% |
27
+
| Locals / register-heavy code | 132% |
28
+
| Table library | 118% |
29
+
| Coroutines | 152% |
30
+
| Errors | 103% |
31
+
32
+
There is no repository-maintained Linux snapshot from a dedicated physical Linux machine yet, because the current benchmark process does not have a real Linux box behind it. For Linux runs, use the GitHub Actions benchmark workflow as the best continuous reference point.
33
+
34
+
Observed Linux behavior so far is mixed but fairly consistent: luars is often about 20% to 40% slower than native Lua on broad benchmark coverage, while still beating native Lua in a non-trivial subset of cases.
35
+
36
+
The current broader script-level snapshot is available here:
One important caveat for the Windows numbers: the coroutine result is unusually strong partly because native Lua's coroutine implementation on Windows pays heavily for `longjmp`-based control transfer, which triggers unwind-related overhead. luars does not inherit that exact cost model, so the Windows coroutine gap is real in measurement but should not be over-generalized into a platform-independent "always faster" claim.
48
+
49
+
### Safety And Audit Posture
50
+
51
+
luars is implemented in Rust, but it does not pretend that "written in Rust" automatically means the whole runtime is safe by default. The project keeps `unsafe` under active review and pushes non-critical paths back to safe Rust when that does not cost hot-path performance.
52
+
53
+
Recent cleanup work narrowed the unsafe surface in VM helper and dispatch-adjacent code, including helper, concat, call, and metamethod paths. The remaining `unsafe` usage is concentrated in the places where the runtime actually needs it:
54
+
55
+
- GC/object representation and tagged value layout
56
+
- stack/upvalue pointer fast paths in hot interpreter execution
57
+
- a small number of performance-sensitive VM internals where safe equivalents were measured to be worse
58
+
59
+
There are also Miri smoke tests in the repo for low-level runtime sanity checks.
60
+
61
+
### Compatibility And Test Status
62
+
63
+
The repository includes the official Lua test suite under `lua_tests/testes`, plus the scripts needed to run it directly.
64
+
65
+
Current status from a fresh release-mode run in this workspace:
That means the current tree passes the upstream Lua test suite entrypoint used by this repository, with the expected skips for `testC`-dependent cases that are not active in this environment.
71
+
72
+
## Crate Features
73
+
74
+
Core crate feature flags for `luars`:
75
+
76
+
| Feature | Purpose |
77
+
|---------|---------|
78
+
|`serde`| Enable `serde` / `serde_json` integration for Lua value conversion and host interop |
79
+
|`sandbox`| Enable sandbox-oriented helpers and isolated execution entry points |
80
+
|`shared-proto`| Reuse cached compiled proto/constant-string state across loads/VM instances to reduce duplicate compilation and allocation work |
81
+
82
+
Minimal dependency:
13
83
14
84
```toml
15
85
[dependencies]
16
-
luars = "0.18"
86
+
luars = "0.21"
17
87
```
18
88
89
+
With optional features:
90
+
91
+
```toml
92
+
[dependencies]
93
+
luars = { version = "0.21", features = ["serde", "sandbox", "shared-proto"] }
-[docs/benchmarks/macos.md](docs/benchmarks/macos.md) for the latest macOS benchmark snapshot
38
-
-[docs/benchmarks/windows.md](docs/benchmarks/windows.md) for the latest Windows benchmark snapshot
39
-
- I don't have a physical Linux machine, but you can refer to the GitHub Actions VM CI results: https://github.com/CppCXY/lua-rs/actions. If this repository includes a `benchmarks` workflow, view it directly at https://github.com/CppCXY/lua-rs/actions/workflows/benchmarks.yml
40
-
41
-
## What The High-Level API Covers
113
+
## High-Level API Highlights
42
114
43
115
- Execute chunks with `lua.load(...).exec()`, `eval()`, and `eval_multi()`
44
116
- Execute async chunks with `exec_async()`, `eval_async()`, and `eval_multi_async()`
45
-
- Call Lua globals with `call_global()` / `call_global1()` and their async variants
46
-
- Register Rust functions with `register_function()` and `register_async_function()`
117
+
- Call Lua globals with `call_global()` / `call_global1()` and async variants
118
+
- Register Rust functions with typed and untyped callback APIs
47
119
- Expose Rust types with `register_type()` and `LuaUserData`
48
120
- Work with globals and tables through `globals()`, `create_table()`, and `create_table_from()`
49
121
- Create scoped borrowed callbacks and userdata through `scope(...)`
50
-
- Run isolated chunks through `load_sandboxed()` and `execute_sandboxed()` when the `sandbox` feature is enabled
122
+
- Run isolated chunks through sandbox helpers when the `sandbox` feature is enabled
51
123
52
124
## Repository Layout
53
125
54
126
| Path | Description |
55
127
|------|-------------|
56
-
|`crates/luars`| Core library with the compiler, VM, GC, and high-level `Lua` API |
57
-
|`crates/luars-derive`|`LuaUserData` and `lua_methods`macros |
The Miri profile disables stacked borrows and uses permissive provenance because luars currently relies on tagged-pointer GC/object representations that intentionally compress and reconstruct raw pointers.
171
+
The Miri profile disables stacked borrows and uses permissive provenance because luars relies on tagged-pointer and compact GC/object layouts that intentionally reconstruct raw pointers.
0 commit comments