lua rtd fixes and simplify plus missing test

Author: AlexJReid

docs/lua-functions.md

@@ -87,6 +87,7 @@ function my_func(x, y) ... end
 |---|---|
 | `---` line | Function description (first `---` line) |
 | `@param name [type] [description]` | Parameter. Type is `number` (default), `string`, or `boolean`. |
+| `@rtd` | RTD subscription function. Return values are `prog_id, topic1, topic2, ...`. Automatically non-thread-safe. |
 | `@async` | Run on worker thread with result caching via RTD |
 | `@thread_safe false` | Disable multi-threaded recalculation (default: thread-safe) |
 | `@category name` | Excel function category (default: `"Lua Functions"`) |
@@ -323,41 +324,39 @@ end
 
 ## RTD subscriptions from Lua
 
-Lua functions can subscribe to an RTD server and return a live-updating cell value, just like Zig wrapper functions do. Use `xllify.rtd_subscribe`:
+Lua functions can subscribe to an RTD server and return a live-updating cell value, just like Zig wrapper functions do. Add `@rtd` to the annotation — the function returns the prog_id and topic strings, and the framework handles the `xlfRtd` call:
 
 ```lua
 --- Live price for a symbol
 -- @param symbol string Ticker symbol
--- @thread_safe false
+-- @rtd
 function price(symbol)
-    return xllify.rtd_subscribe("myprog.rtd", symbol)
+    return "myprog.rtd", symbol
 end
 ```
 
-`xllify.rtd_subscribe(prog_id, topic1, ...)` accepts a prog ID and up to 28 topic strings. It calls Excel's `xlfRtd` and returns the live cell value. Excel handles the subscription — the cell updates automatically whenever the RTD server pushes a new value.
-
-The return value is forwarded directly to Excel as an RTD subscription; the cell will update live exactly as if the user had typed `=RTD("myprog.rtd", , symbol)`.
-
-**Thread safety is mandatory.** Functions that call `xllify.rtd_subscribe` must be declared `@thread_safe false` (or `.thread_safe = false` in hand-written Zig). The underlying `xlfRtd` call must run on Excel's main thread. Without this, the call will fail or crash.
+The function's return values are interpreted as: first = prog_id, rest = topic strings. The framework calls `xlfRtd` with these values and returns the live cell value to Excel. The cell updates automatically whenever the RTD server pushes a new value.
 
-If `xllify.rtd_subscribe` fails (e.g. the RTD server is not registered), it returns `nil`, which Excel renders as an empty cell.
+`@rtd` automatically sets `thread_safe = false` (the underlying `xlfRtd` call must run on Excel's main thread). You don't need to add `@thread_safe false` separately.
 
-Multiple topic strings are supported:
+Multiple topic strings are just more return values:
 
 ```lua
 --- Price on a specific exchange
 -- @param exchange string Exchange code
 -- @param symbol string Ticker symbol
--- @thread_safe false
+-- @rtd
 function price_on_exchange(exchange, symbol)
-    return xllify.rtd_subscribe("myprog.rtd", exchange, symbol)
+    return "myprog.rtd", exchange, symbol
 end
 ```
 
+If the Lua function errors or returns no values, the cell shows `#VALUE!`.
+
 ## Limitations
 
 - Maximum 8 parameters per function (same as `ExcelFunction`)
 - No matrix/table parameter or return type support yet
 - Pool states are independent — global variable mutations don't propagate between states (use `xll.get`/`xll.set` for shared state)
 - `is_async = true` automatically forces `thread_safe = false` (async functions use `xlfRtd` which must run on Excel's main thread)
-- Functions using `xllify.rtd_subscribe` must be `@thread_safe false` — `xlfRtd` must run on Excel's main thread
+- `@rtd` functions are always non-thread-safe (`xlfRtd` must run on Excel's main thread)

docs/rtd-servers.md

@@ -208,20 +208,18 @@ return rtd_call.subscribe("myprog.rtd", &.{ exchange, symbol });
 
 ## Using RTD from Lua
 
-Lua functions can subscribe to an RTD server using `xllify.rtd_subscribe`. This is the Lua equivalent of calling `rtd_call.subscribe()` from Zig:
+Add `@rtd` to a Lua function annotation. The function returns the prog_id and topic strings; the framework handles the `xlfRtd` call:
 
 ```lua
 --- Subscribe to a live NATS subject
 -- @param subject string NATS subject
--- @thread_safe false
+-- @rtd
 function nats_sub(subject)
-    return xllify.rtd_subscribe("zigxll.connectors.nats", subject)
+    return "zigxll.connectors.nats", subject
 end
 ```
 
-`xllify.rtd_subscribe(prog_id, topic1, ...)` accepts a prog ID string and up to 28 topic strings. The cell updates live whenever the RTD server pushes a new value.
-
-**Thread safety is mandatory.** Functions calling `xllify.rtd_subscribe` must be `@thread_safe false` — `xlfRtd` must run on Excel's main thread. See [Lua Functions — RTD subscriptions](lua-functions.md#rtd-subscriptions-from-lua) for full details.
+The function's return values are: first = prog_id, rest = topic strings. `@rtd` automatically sets `thread_safe = false`. The cell updates live whenever the RTD server pushes a new value. See [Lua Functions — RTD subscriptions](lua-functions.md#rtd-subscriptions-from-lua) for full details.
 
 ## Limitations
 

example/src/lua/functions.lua

@@ -151,17 +151,16 @@ end
 
 --- Subscribe to a timer tick via the demo RTD server.
 -- Returns a live-updating counter that increments every 2 seconds.
--- Demonstrates xllify.rtd_subscribe from Lua.
 -- @name Lua.TimerTick
--- @thread_safe false
+-- @rtd
 function timer_tick()
-    return xllify.rtd_subscribe("zigxll.example.timer")
+    return "zigxll.rtd", "tick"
 end
 
 --- Subscribe to a timer tick with a named topic.
 -- @name Lua.TimerTickLabeled
 -- @param label string Topic label (ignored by the server, illustrates multi-topic)
--- @thread_safe false
+-- @rtd
 function timer_tick_labeled(label)
-    return xllify.rtd_subscribe("zigxll.example.timer", label)
+    return "zigxll.rtd", label
 end

src/async_cache_tests.zig

@@ -0,0 +1,140 @@
+const std = @import("std");
+const async_cache = @import("async_cache.zig");
+const xl_imports = @import("xl_imports.zig");
+const xl = xl_imports.xl;
+
+const allocator = std.heap.c_allocator;
+
+fn makeNumericXloper(val: f64) *xl.XLOPER12 {
+    const ptr = allocator.create(xl.XLOPER12) catch unreachable;
+    ptr.* = .{
+        .xltype = xl.xltypeNum | xl.xlbitDLLFree,
+        .val = .{ .num = val },
+    };
+    return ptr;
+}
+
+fn freeXloper(ptr: *xl.XLOPER12) void {
+    allocator.destroy(ptr);
+}
+
+test "cache miss returns null" {
+    var cache = async_cache.AsyncCache.init();
+    defer cache.clear();
+
+    try std.testing.expect(cache.get("nonexistent") == null);
+}
+
+test "put and get" {
+    var cache = async_cache.AsyncCache.init();
+    defer cache.clear();
+
+    const xloper = makeNumericXloper(42.0);
+    defer freeXloper(xloper);
+
+    cache.put("key1", .{ .xloper = xloper, .completed = true });
+
+    const result = cache.get("key1");
+    try std.testing.expect(result != null);
+    try std.testing.expect(result.?.completed);
+    try std.testing.expectEqual(42.0, result.?.xloper.val.num);
+}
+
+test "put overwrites existing key" {
+    var cache = async_cache.AsyncCache.init();
+    defer cache.clear();
+
+    const xloper1 = makeNumericXloper(1.0);
+    defer freeXloper(xloper1);
+    const xloper2 = makeNumericXloper(2.0);
+    defer freeXloper(xloper2);
+
+    cache.put("key", .{ .xloper = xloper1, .completed = false });
+    cache.put("key", .{ .xloper = xloper2, .completed = true });
+
+    const result = cache.get("key");
+    try std.testing.expect(result != null);
+    try std.testing.expect(result.?.completed);
+    try std.testing.expectEqual(2.0, result.?.xloper.val.num);
+}
+
+test "contains" {
+    var cache = async_cache.AsyncCache.init();
+    defer cache.clear();
+
+    const xloper = makeNumericXloper(0.0);
+    defer freeXloper(xloper);
+
+    try std.testing.expect(!cache.contains("key"));
+    cache.put("key", .{ .xloper = xloper, .completed = false });
+    try std.testing.expect(cache.contains("key"));
+}
+
+test "clear removes all entries" {
+    var cache = async_cache.AsyncCache.init();
+
+    const xloper1 = makeNumericXloper(1.0);
+    defer freeXloper(xloper1);
+    const xloper2 = makeNumericXloper(2.0);
+    defer freeXloper(xloper2);
+
+    cache.put("a", .{ .xloper = xloper1, .completed = true });
+    cache.put("b", .{ .xloper = xloper2, .completed = true });
+
+    cache.clear();
+
+    try std.testing.expect(cache.get("a") == null);
+    try std.testing.expect(cache.get("b") == null);
+}
+
+test "in-progress then completed" {
+    var cache = async_cache.AsyncCache.init();
+    defer cache.clear();
+
+    const pending = makeNumericXloper(0.0);
+    defer freeXloper(pending);
+    const done = makeNumericXloper(99.0);
+    defer freeXloper(done);
+
+    // Mark in-progress
+    cache.put("calc|5", .{ .xloper = pending, .completed = false });
+    const r1 = cache.get("calc|5");
+    try std.testing.expect(!r1.?.completed);
+
+    // Complete
+    cache.put("calc|5", .{ .xloper = done, .completed = true });
+    const r2 = cache.get("calc|5");
+    try std.testing.expect(r2.?.completed);
+    try std.testing.expectEqual(99.0, r2.?.xloper.val.num);
+}
+
+test "concurrent reads and writes" {
+    var cache = async_cache.AsyncCache.init();
+    defer cache.clear();
+
+    const xloper = makeNumericXloper(42.0);
+    defer freeXloper(xloper);
+    cache.put("shared", .{ .xloper = xloper, .completed = true });
+
+    const Reader = struct {
+        fn run(c: *async_cache.AsyncCache) void {
+            for (0..1000) |_| {
+                if (c.get("shared")) |r| {
+                    std.debug.assert(r.xloper.val.num == 42.0);
+                }
+            }
+        }
+    };
+
+    var threads: [4]std.Thread = undefined;
+    for (&threads) |*t| {
+        t.* = std.Thread.spawn(.{}, Reader.run, .{&cache}) catch unreachable;
+    }
+    for (&threads) |t| t.join();
+}
+
+test "global cache singleton" {
+    const c1 = async_cache.getGlobalCache();
+    const c2 = async_cache.getGlobalCache();
+    try std.testing.expectEqual(c1, c2);
+}

src/lua_builtins.zig

@@ -6,11 +6,9 @@
 //   xllify.json_stringify(value) -> string
 //   xllify.regex_match(text, pattern, occurrence?) -> string
 //   xllify.regex_replace(text, pattern, replacement) -> string
-//   xllify.rtd_subscribe(prog_id, topic1, ...) -> lightuserdata (*XLOPER12) | nil
 
 const std = @import("std");
 const c = @import("lua_c.zig").c;
-const rtd_call = @import("rtd_call.zig");
 
 const allocator = std.heap.c_allocator;
 
@@ -191,57 +189,6 @@ fn writeJsonString(writer: anytype, s: []const u8) !void {
     try writer.writeByte('"');
 }
 
-// ============================================================================
-// RTD
-// ============================================================================
-
-/// xllify.rtd_subscribe(prog_id, topic1, topic2, ...) -> lightuserdata | nil
-///
-/// Calls xlfRtd and returns the resulting *XLOPER12 as a Lua light userdata.
-/// The Lua function wrapper (pullResult) recognises light userdata and forwards
-/// it directly to Excel as an RTD subscription cell value.
-///
-/// IMPORTANT: Functions that call this MUST be declared @thread_safe false (or
-/// .thread_safe = false in hand-written Zig), because xlfRtd must run on
-/// Excel's main thread. Calling from a worker thread will crash or silently
-/// fail.
-fn luaRtdSubscribe(L: ?*c.lua_State) callconv(.c) c_int {
-    const state = L orelse return 0;
-    const n = c.lua_gettop(state);
-    if (n < 1) {
-        c.lua_pushnil(state);
-        return 1;
-    }
-
-    // First arg: prog_id (string)
-    var prog_id_len: usize = 0;
-    const prog_id_ptr = c.lua_tolstring(state, 1, &prog_id_len) orelse {
-        c.lua_pushnil(state);
-        return 1;
-    };
-    const prog_id = prog_id_ptr[0..prog_id_len];
-
-    // Remaining args: topic strings (up to 28)
-    const max_topics = 28;
-    var topics_buf: [max_topics][]const u8 = undefined;
-    var topic_count: usize = 0;
-    var i: c_int = 2;
-    while (i <= n and topic_count < max_topics) : (i += 1) {
-        var tlen: usize = 0;
-        const tptr = c.lua_tolstring(state, i, &tlen) orelse continue;
-        topics_buf[topic_count] = tptr[0..tlen];
-        topic_count += 1;
-    }
-
-    const result = rtd_call.subscribeDynamic(prog_id, topics_buf[0..topic_count]) catch {
-        c.lua_pushnil(state);
-        return 1;
-    };
-
-    c.lua_pushlightuserdata(state, result);
-    return 1;
-}
-
 // ============================================================================
 // Registration
 // ============================================================================
@@ -266,8 +213,5 @@ pub fn register(L: *c.lua_State) void {
     c.lua_pushcclosure(L, luaJsonStringify, 0);
     c.lua_setfield(L, -2, "json_stringify");
 
-    c.lua_pushcclosure(L, luaRtdSubscribe, 0);
-    c.lua_setfield(L, -2, "rtd_subscribe");
-
     c.lua_settop(L, c.lua_gettop(L) - 1); // pop xllify table
 }

src/lua_function.zig

@@ -176,14 +176,6 @@ pub fn LuaFunction(comptime meta: anytype) type {
                         .val = undefined,
                     });
                 },
-                lua.LUA_TLIGHTUSERDATA => {
-                    // xllify.rtd_subscribe() pushes the *XLOPER12 from rtd_call.subscribeDynamic
-                    // as a light userdata. Forward it directly — Excel frees it via xlAutoFree12.
-                    const ptr = lua.lua_touserdata(L, -1);
-                    lua.lua_pop(L, 1);
-                    if (ptr == null) return makeErrorValue();
-                    return @ptrCast(@alignCast(ptr.?));
-                },
                 else => {
                     lua.lua_pop(L, 1);
                     return makeErrorValue();