obitools4/autodoc/docmd/pkg/obilua/lua_obicontext.md

obilua Module: Lua-Accessible Shared Context with Thread Safety

This Go package exposes a thread-safe, shared key-value context to Lua scripts via the Gopher-Lua interpreter.

Core Features

• Global obicontext Table: Registered in Lua with the following methods:
  • obicontext.item(key [, value]):
    Get or set a context variable. Supports types: bool, number, string, tables (converted via helper), and user data.
  • obicontext.lock(): Acquire exclusive lock on the context (blocking).
  • obicontext.unlock(): Release the global lock.
  • obicontext.trylock(): Attempt to acquire non-blocking lock; returns boolean success.
  • obicontext.inc(key) / dec(key): Atomically increment/decrement numeric values (float64 only), with lock protection.

Thread Safety

• Uses sync.Mutex for serializing write operations (e.g., inc/dec, lock/unlock).
• sync.Map for concurrent-safe read/write of key-value pairs.
• Critical sections (e.g., increment/decrement) are explicitly wrapped with locks to ensure atomicity.

Lua Integration

• Values stored in the context persist across script calls.
• Type coercion is handled explicitly: Lua types map directly to Go equivalents, with fallback logging on unsupported types.
• Errors (e.g., incrementing non-number) trigger fatal logs—suitable for controlled environments.

Use Case

Ideal for embedding Lua logic in Go applications requiring shared state (e.g., config, counters), with explicit locking for race-free updates.