When no {.ffiCtor.} has stored a library, the FFI thread points `myLib` at a
default-valued fallback so handlers always have something to bind. For an
`object` library that is a usable zero value and callers legitimately depend on
it (tests/unit/test_ffi_handle drives a context that never runs a ctor), but for
a `ref` library the default is `nil`: the user body received a nil ref and
faulted on its first field access. A failing ctor is the common way to get
there, since the C entry point hands back a live context before the ctor body
has run on the FFI thread.
Track whether a ctor actually stored a library and, for `ref` library types
only, reject such requests with a clear error instead of dispatching them. The
check sits in the generated handler rather than the C entry point, so it runs
behind any queued constructor — a host that fires a call without awaiting the
create callback still succeeds, as before.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ULz7Md52AF6PmqZeCmh8b7
When no {.ffiCtor.} has stored a library, the FFI thread points `myLib` at a
default-valued fallback so handlers always have something to bind, and
`myLibOwned` is what distinguishes that fallback from a real one. For an
`object` library the fallback is a usable zero value and callers legitimately
depend on it, but for a `ref` library it is `nil`: the user body received a nil
ref and faulted on its first field access. A failing ctor is the common way to
get there, since the C entry point hands back a live context before the ctor
body has run on the FFI thread.
Guard on `myLibOwned` for `ref` library types only. The check sits in the
generated handler rather than the C entry point, so it runs behind any queued
constructor — a host that fires a call without awaiting the create callback
still succeeds, as before.
Backport of the same fix on master, where the state had to be added rather than
reused.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ULz7Md52AF6PmqZeCmh8b7
{.ffi.}/{.ffiCtor.} cover the async, context-handle, CBOR-marshaled path.
{.ffiExport.} covers the complementary case: a no-argument lifecycle/health
entry point a host loads with dlopen+dlsym and calls synchronously — no
context, no callback, no CBOR, the return value crossing the ABI directly.
Native Nim return types are bridged to the C ABI (int/bool -> int,
uint64 -> unsigned long long, string -> const char* kept alive in shared
memory; no-return -> void), and initializeLibrary() is injected so the Nim
runtime is up on first call — the host never invokes NimMain itself.
Fills the no-argument scalar case of the declared-but-unimplemented abi=c path.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0138fdSv6Xhv2KjhiyYR4SAu
`{.ffiEvent.}` previously accepted exactly one parameter, forcing every
multi-field event to declare a hand-written {.ffi.} payload type. The macro
now bundles two or more parameters into a synthesised, registered envelope
object named `<WireNamePascalCase>Payload`, whose fields are the parameters,
and dispatches an instance of it. A single parameter still rides the wire
directly (scalar or existing {.ffi.} object), so this is backwards
compatible. Because the envelope is registered like any {.ffi.} type, the
foreign bindings gain it as a first-class struct plus a typed handler.
The timer example gains an `on_job_scheduled(jobId, willRunCount)` event to
exercise the path; the C++ and Rust bindings are regenerated accordingly.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Two foreign-host concurrency fixes for refc, both needed so a Go host can
hammer the FFI under load without corrupting Nim's per-thread GC.
1. Compile-time request ids. ffiNewReq / the method + ctor wrappers built
the request id with `$T` at runtime, allocating a Nim GC string on the
foreign caller's (often transient) thread. Emit a `cstring` literal of
the type name instead — no allocation on the caller thread.
2. Recycle pooled contexts instead of destroy/recreate. Restores the
release/v0.1 model that v0.2 dropped: a pool slot's worker + event
threads and signal fds are built once and reused. The ffiDtor now
requests a synchronous recycle (drain in-flight handlers, free the lib,
clear listeners, release the slot) on the FFI thread, keeping the
threads alive; createFFIContext reuses an initialised slot. Without this
every create/destroy churned ~6 signal fds, so fd numbers climbed past
FD_SETSIZE (1024) and ThreadSignalPtr.waitSync's select() failed with
EINVAL under create/destroy load.
Adds CtxLifecycle (Active/RecyclePending/Recycling), ctx-level
inUse/tryClaim/release/markAsActive, requestRecycle (waits on a new
recycleDoneSignal), freeLib (refc GC_unref / orc =destroy of ctor-owned
libs), recycleContext, FFIEventRegistry.clearListeners, and roots the
ctor-stored ref lib under refc (GC_ref, balanced in freeLib).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
sds_add_event_listener / sds_remove_event_listener run on the foreign
caller thread and allocate Nim memory ($eventName, the listener registry
Table+seq), but unlike the ctor/dtor they never called initializeLibrary.
A foreign host (Go) migrates goroutines across OS threads, so the thread
running add_event_listener may not be the one that ran a prior entry
point; without setupForeignThreadGc its per-thread allocator region is
uninitialised and the first Nim allocation faults in the allocator.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
CBOR is the headline 0.2.0 feature, not 0.1.4: at v0.1.4 serial.nim was
still JSON/string-based, so the prior CBOR attribution was wrong. Also
complete the 0.2.0 scope (events, registry, codegen) ahead of tagging.
Date 0.1.4 by its last functional change (#14, 2026-05-13) rather than
the later changelog/version-bump commits, so the version reflects when
its code actually settled.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* rust examples: sync main.rs + tokio main.rs demoing the listener API
Adds two bundled examples to the generated Rust crate:
- examples/main.rs: sync flow using std::sync::mpsc to bridge a typed
on_echo_fired listener into main + a wildcard add_event_listener
that uses decode_event_payload::<EchoEvent>(envelope) for the
matching event id.
- examples/tokio_main.rs: same shape via #[tokio::main] +
tokio::sync::mpsc.
Bumps generateCargoToml to ship `[dev-dependencies]` with tokio's
`rt-multi-thread` + `macros` features so the bundled examples can use
#[tokio::main] without polluting the library's runtime profile.
Run with `cargo run --example main` (set DYLD_LIBRARY_PATH=<repo> on
macOS until build.rs emits an rpath).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* simplify examples
---------
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
