Rust runtime 迁移与 kvlang 类型/运行时重构

.cargo/config.toml

@@ -0,0 +1,3 @@
+[build]
+rustflags = ["-L", "/home/peng.li24/github.com/array2d/kvspace-c/build"]
+

.claude/runtime-rust.md

@@ -0,0 +1,116 @@
+# kvlang Rust Runtime 开发原则
+
+## 零、总体原则
+
+**kvlang Rust runtime 是 Go kvlang runtime 的像素级 C ABI 移植。**
+
+Go 负责 toolchain（parse → lower → layout → 写入 kvspace），Rust/C++ 负责 runtime（从 kvspace 读取指令 → kvcpu 执行）。
+
+## 一、零拷贝原则
+
+XValue 的 kind 解析后，body 字节直接 reinterpret_cast，不做任何拷贝或中间类型转换。
+
+```
+SHM sbo_data 指针 → read_tlv() 返回直接指针（无 malloc）
+  ↓
+Rust: *const u8 → *(ptr as *const i64).read_unaligned() → i64
+C++:  const uint8_t* → *reinterpret_cast<const int64_t*>(ptr)
+```
+
+- 禁止 `to_vec()`, `memcpy`, `copy_from_slice`, `malloc` 在 hot path
+- 禁止创建中间 Vec/u8 对象装载 body 字节
+- `display()` 做格式化输出时从 raw pointer 直接读，不拷
+- 只有 kind 字符串（<16 bytes）允许拷贝
+
+## 二、先读 Go 代码原则
+
+实现任何 runtime 功能前，必须先读 Go 对应文件理解逻辑：
+
+| 功能 | Go 文件 |
+|------|--------|
+| 执行循环 | `kvcpu/execute.go` |
+| 控制流 | `kvcpu/controlflow.go` |
+| 算术 | `rwir/builtin/arith.go` |
+| 比较 | `rwir/builtin/cmp.go` |
+| IO | `rwir/builtin/io.go` |
+| 时间 | `rwir/builtin/time.go` |
+| 分发 | `rwir/builtin/ops.go` |
+| 虚线程 | `vthread/vthread.go` |
+| 路径生成 | `keytree/const.go` + `keytree/vthread.go` |
+
+禁止不读 Go 代码直接凭想象写 Rust 实现。
+
+## 三、禁止 hardcode 原则
+
+所有路径常量、kind 字符串、opcode 字符串必须引用模块常量，禁止裸字符串。
+
+- 路径 → `keytree/const.rs`（对齐 `keytree/const.go`）
+- kind → 引用 XValue kind 常量
+- opcode → `rwir/builtin/ops.rs` dispatch table 中定义
+
+禁止在 execute.rs / controlflow.rs 等文件中出现 `"/lib/"`, `"/vthread/"`, `".pc"`, `"main"` 等裸字符串。
+
+## 四、像素级对齐 Go 原则
+
+Rust 项目的文件路径、文件名、函数名、模块名必须与 Go 源码一对一对应：
+
+```
+Go: kvlang/kvcpu/execute.go          → Rust: kvlang/kvcpu/execute.rs
+Go: kvlang/kvcpu/controlflow.go      → Rust: kvlang/kvcpu/controlflow.rs
+Go: kvlang/kvcpu/cpu.go              → Rust: kvlang/kvcpu/cpu.rs
+Go: kvlang/rwir/rwir.go              → Rust: kvlang/rwir/rwir.rs
+Go: kvlang/rwir/builtin/arith.go     → Rust: kvlang/rwir/builtin/arith.rs
+Go: kvlang/rwir/builtin/cmp.go       → Rust: kvlang/rwir/builtin/cmp.rs
+Go: kvlang/rwir/builtin/io.go        → Rust: kvlang/rwir/builtin/io.rs
+Go: kvlang/rwir/builtin/time.go      → Rust: kvlang/rwir/builtin/time.rs
+Go: kvlang/rwir/builtin/ops.go       → Rust: kvlang/rwir/builtin/ops.rs
+Go: kvlang/rwir/builtin/logic.go     → Rust: kvlang/rwir/builtin/logic.rs
+Go: kvlang/rwir/builtin/math.go      → Rust: kvlang/rwir/builtin/math.rs
+Go: kvlang/rwir/builtin/string.go    → Rust: kvlang/rwir/builtin/string.rs
+Go: kvlang/vthread/vthread.go        → Rust: kvlang/vthread/vthread.rs
+Go: kvlang/keytree/const.go          → Rust: kvlang/keytree/const.rs
+Go: kvlang/logx/logx.go              → Rust: kvlang/logx/logx.rs
+```
+
+Go 中的公开函数名在 Rust 中保持一致。例如 Go 的 `handle_goto` → Rust 的 `handle_goto`，Go 的 `exec_add` → Rust 的 `exec_add`。
+
+## 五、模块结构
+
+```rust
+// lib.rs
+pub mod kvcpu;
+pub mod rwir;
+pub mod keytree;
+pub mod logx;
+pub mod vthread;
+
+// kvcpu/mod.rs
+pub mod cpu;
+pub mod execute;
+pub mod controlflow;
+
+// rwir/mod.rs
+pub mod rwir;
+pub mod builtin;
+
+// rwir/builtin/mod.rs
+pub mod ops; pub mod arith; pub mod cmp; pub mod io;
+pub mod time; pub mod logic; pub mod math; pub mod bit;
+pub mod cast; pub mod string; pub mod kvop;
+```
+
+## 六、编译与测试
+
+```bash
+# C 构建
+make -C kvspace-c/build -j4
+
+# Rust 构建
+cargo build --manifest-path kvlang/Cargo.toml
+
+# 单文件测试
+KVSPACE_SHM=/tmp/t kvlang-rust main
+
+# 全量测试
+python3 kvlang/tutorial/test.py --runtime=rust
+```

.gitignore

@@ -49,7 +49,8 @@ appendonly.aof
 # ── Project-specific ─────────────────────────────────
 /tmp/
 /post/
-kvlang
+/kvlang
+/json
 
 # Tool config
 .omc/

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "kvlang"
 version = "0.1.0"
-edition = "2024"
+edition = "2021"
 description = "kvlang VM — Rust runtime (kvcpu executor)"
 license = "MIT"
 
@@ -13,5 +13,4 @@ name = "kvlang"
 path = "cmd/kvlang/main.rs"
 
 [dependencies]
-# kvspace-rdma client (future)
-# serde = { version = "1", features = ["derive"] }
+libc = "0.2"

Makefile

@@ -1,4 +1,4 @@
-.PHONY: build test vet clean kvspace install
+.PHONY: build test vet clean kvspace install rust rust-test
 
 export GOPROXY ?= https://goproxy.cn,direct
 PREFIX   ?= ~/.local
@@ -9,9 +9,16 @@ build:
 	install -d $(PREFIX)/bin
 	install kvlang $(PREFIX)/bin/kvlang
 
+rust:
+	cargo build --manifest-path $(CURDIR)/Cargo.toml
+
+rust-test:
+	python3 tutorial/test.py --runtime=rust
+
 vet:
 	go vet ./...
 
 clean:
 	go clean
+	cargo clean --manifest-path $(CURDIR)/Cargo.toml
 	rm -f kvlang

ast/ast.go

@@ -81,13 +81,6 @@ func (s FuncSig) NumReads() int32 { return int32(len(s.Params)) }
 func (s FuncSig) NumWrites() int32 { return int32(len(s.Returns)) }
 
 // ReturnNames 返回输出参数名列表。
-func (s FuncSig) ReturnNames() []string {
-	names := make([]string, len(s.Returns))
-	for i, p := range s.Returns {
-		names[i] = p.Name
-	}
-	return names
-}
 
 // ── 函数 ──────────────────────────────────────────────────────
 

build.rs

@@ -0,0 +1 @@
+fn main() { println!("cargo:rustc-link-search=native=/home/peng.li24/github.com/array2d/kvspace-c/build"); println!("cargo:rustc-link-lib=kvspace-c"); }

cmd/kvlang/layout.go

@@ -61,6 +61,9 @@ func cmdLayout(args []string) {
 		layout.WriteFunc(kv, fpkg, lower.Func(&df.Funcs[i]))
 		anyCode = true
 	}
+	for i := range df.RwirDecls {
+		layout.WriteRwirDecl(kv, &df.RwirDecls[i])
+	}
 	body := df.InitBody
 	for _, c := range df.TopLevelCalls { body = append(body, c) }
 	if len(body) > 0 {
@@ -121,16 +124,11 @@ func _loadFile(kv kvspace.KVSpace, f string, anyCode *bool, loaded map[string]bo
 		layout.WriteFunc(kv, fpkg, lower.Func(&df.Funcs[i]))
 		*anyCode = true
 	}
+	for i := range df.RwirDecls {
+		layout.WriteRwirDecl(kv, &df.RwirDecls[i])
+	}
 	for _, st := range df.InitBody { *initBody = append(*initBody, st) }
 	for _, c := range df.TopLevelCalls { *initBody = append(*initBody, c) }
 	if len(df.InitBody) > 0 || len(df.TopLevelCalls) > 0 { *anyCode = true }
 }
 
-func makeInitFunc(calls []*ast.Instruction) *ast.Func {
-	body := make([]ast.Stmt, len(calls))
-	for i, inst := range calls {
-		body[i] = inst
-	}
-	initFn := ast.Func{Sig: ast.FuncSig{Name: "init"}, Body: body}
-	return lower.Func(&initFn)
-}

cmd/kvlang/layoutandrun.go

@@ -49,7 +49,7 @@ func findEntryPrefix(kv kvspace.KVSpace, prefix string) string {
 func runFiles(dsn string, paths []string, debug bool) {
 	kv := kvspace.Conn(dsn)
 	defer kv.DisConn()
-	registerDefaultTerm(kv)
+	initDirs(kv)
 
 	var files []string
 	for _, p := range paths {
@@ -59,14 +59,16 @@ func runFiles(dsn string, paths []string, debug bool) {
 	}
 	if len(files) == 0 { logx.Fatal("no .kv files found") }
 
+	layoutAndRunStdlib(kv)
 	if !loadFunctions(kv, files) { return }
 	executeEntry(kv, findEntry(dsn), debug)
 }
 
 func runCode(name string, rc io.Reader, dsn string, debug bool) {
 	kv := kvspace.Conn(dsn)
 	defer kv.DisConn()
-	registerDefaultTerm(kv)
+	initDirs(kv)
+	layoutAndRunStdlib(kv)
 
 	df, diags, err := parser.ParseCode(rc)
 	if err != nil { logx.Fatal("parse: %v", err) }
@@ -78,6 +80,9 @@ func runCode(name string, rc io.Reader, dsn string, debug bool) {
 		if fpkg == "" { fpkg = df.Package }
 		layout.WriteFunc(kv, fpkg, lower.Func(&df.Funcs[i]))
 	}
+	for i := range df.RwirDecls {
+		layout.WriteRwirDecl(kv, &df.RwirDecls[i])
+	}
 	body := df.InitBody
 	for _, c := range df.TopLevelCalls { body = append(body, c) }
 	if len(body) > 0 {

cmd/kvlang/main.go

@@ -17,7 +17,7 @@ import (
 	// 注册 KVSpace 实现；--kvspace DSN 的 scheme 选择后端（默认 shm://）。
 	_ "github.com/array2d/kvspace-go/redis"
 	_ "github.com/array2d/kvspace-go/goheap"
-	_ "github.com/array2d/kvspace-go/shm"
+	// _ "github.com/array2d/kvspace-go/shm" // requires libkvspace-c.so
 )
 
 func main() {

cmd/kvlang/main.rs

@@ -0,0 +1,15 @@
+use std::env;
+use kvlang::kvcpu::cpu::KVCpu;
+use kvlang::kvcpu::execute;
+
+fn main() {
+    let func = env::args().nth(1).unwrap_or_else(|| "main".into());
+    let shm = env::var("KVSPACE_SHM").expect("KVSPACE_SHM not set");
+    let kv_ptr = KVCpu::open(&shm).expect("open shm");
+    let cpu = KVCpu::new(kv_ptr, "rust");
+    if let Err(e) = execute::execute(&cpu, &func) {
+        kvlang::logx::logx::error(format_args!("{}", e));
+        std::process::exit(1);
+    }
+    KVCpu::close(kv_ptr);
+}

cmd/kvlang/run.go

@@ -5,9 +5,11 @@ import (
 	"flag"
 	"fmt"
 	"os"
+	"path/filepath"
 	"strings"
 	"time"
 
+	"kvlang/rwirext/term"
 	"kvlang/keytree"
 	"kvlang/kvcpu"
 	"github.com/array2d/kvspace-go"
@@ -18,11 +20,14 @@ import (
 )
 
 // cmdRun 解析参数并路由：内联 / {lib}.{func} / 文件 / 管道。
+var noterm bool
+
 func cmdRun(args []string) {
 	fs := flag.NewFlagSet("run", flag.ExitOnError)
 	dsn   := fs.String("kvspace", defaultKVSpace(), kvspaceFlagDesc)
 	code  := fs.String("c", "", "内联代码（直接执行字符串）")
 	debug := fs.Bool("debug", false, "单步调试模式（交互式，每条指令暂停）")
+	fs.BoolVar(&noterm, "noterm", false, "禁用内置终端 daemon（print/input 不再可用）")
 	fs.Usage = func() {
 		fmt.Fprintln(os.Stderr, "usage: kvlang run [--debug] [-c code | {lib}.{func} | <file.kv|dir>]")
 		fs.PrintDefaults()
@@ -56,7 +61,8 @@ func runLib(lib, fn string, debug bool) {
 	if lib == "" { name = fn }
 	kv := kvspace.Conn(defaultKVSpace())
 	defer kv.DisConn()
-	registerDefaultTerm(kv)
+	initDirs(kv)
+	layoutAndRunStdlib(kv)
 	executeEntry(kv, name, debug)
 }
 
@@ -66,28 +72,31 @@ func executeEntry(kv kvspace.KVSpace, entryName string, debug bool) {
 	vtid := vthread.AllocVtid(kv)
 	kv.DelTree(keytree.VThread(vtid))
 	kvspace.MkIndexRecursive(kv, keytree.VThread(vtid)+"/")
-	builtin.WriteSysRwir(kv)
+	builtin.WriteRwir(kv, filepath.Base(os.Args[0]))
+	if !noterm {
+		term.Register(kv)
+		go term.Serve(kv)
+	}
 	firstPC := layout.Bootstrap(ctx, kv, vtid, entryName, nil)
 	if firstPC == "" {
 		logx.Fatal("[single] Bootstrap %s failed", entryName)
 	}
 	vthread.Set(ctx, kv, vtid, firstPC, "init")
 	kv.Set([]kvspace.KVPair{
-		{keytree.VThreadCtime(vtid), kvspace.NewTime(time.Now().UnixNano())},
-		{keytree.VThreadTerm(vtid), kvspace.NewChar("kvlangrun")},
+		{Key: keytree.VThreadCtime(vtid), Val: kvspace.NewTime(time.Now().UnixNano())},
 	})
 
 	if debug {
-		kv.Set([]kvspace.KVPair{{keytree.VThreadDebugger(vtid), kvspace.NewChar("break")}})
+		kv.Set([]kvspace.KVPair{{Key: keytree.VThreadDebugger(vtid), Val: kvspace.NewCharByte([]byte("break")...)}})
 		logx.Info("[single] debug mode: executing %s", firstPC)
-		cpu := kvcpu.New(kv, "single")
+		cpu := kvcpu.New(kv)
 		cpu.Execute(firstPC)
 		logx.Info("[dbg] execution finished")
 		return
 	}
 
 	logx.Info("[single] executing %s", firstPC)
-	cpu := kvcpu.New(kv, "single")
+	cpu := kvcpu.New(kv)
 	cpu.Execute(firstPC)
 	reportRunError(kv, vtid)
 }
@@ -96,7 +105,7 @@ func reportRunError(kv kvspace.KVSpace, vtid string) {
 	msgVal := kvspace.GetOne(kv, keytree.VThreadStatusMsg(vtid, "error"))
 	if !kvspace.IsNone(msgVal) {
 		pcVal := kvspace.GetOne(kv, keytree.VThreadPC(vtid))
-		logx.Error("%s at %s", msgVal.String(), pcVal.String())
+		logx.Error("%s at %s", msgVal.ValueString(), pcVal.ValueString())
 		os.Exit(1)
 	}
 }