[ihrfv]

Runs on the core and rayforce-q already pinned on master (core v2.11.0 dc9b12a, rayforce-q 2.2.0 139e4fd); no submodule moves. The branch is three commits behind master (the table column validation fix) and merges cleanly.

What

Subscriptions and the Q wire

• QConnection::attach hands a connection to the runtime's event loop and returns a Subscription that receives frames the peer pushes unsolicited
• Poll is a borrow of the loop the runtime owns; Poll::serve_q(port) registers rayforce-q's listener on it, so a runtime that defines upd is rayforce -q embedded
• env::bind_vary / env::bind_unary bind a Rust handler type under the name a publisher calls; the generated trampoline borrows the arguments and catches panics
• q::encode is the mirror of q::decode_response, so a process can publish over a transport it owns
• rayforce-sys compiles q_server.c beside q.c and binds the poll and env symbols from the core's own headers

Serving the native IPC

• Poll::serve_ipc(port) returns a ServeIpc builder with budget and clock. Its start listens through .sys.listen, installs a guard over every request, and returns an IpcServer
• A request is cancelled through the core's interrupt when it runs past the budget, or when its client closes the connection. A client's own cancel, the urgent byte, works as before
• IpcServer::drain hands back each request's end: the whole text, how long it was evaluated, and Answered, Failed(ErrorCode) or Cancelled(Budget | Hangup | Client)

Build

• The vendored submodules are addressed over https. With git@github.com: in .gitmodules, every git = "https://..." consumer of this crate fails to fetch: Cargo checks submodules out through libgit2 and offers it no SSH key

Why

q.c's client is blocking request/response: a frame a publisher pushes between two requests is consumed by the next q_send as its own reply, and every response after it is one frame out of step. The only fix is for the poll to own the reads and route frames by message type, which is what rayforce-q 2.1.0's q_server.c does — hence the floor on that version.

The native server evaluates one request at a time, and the core stops a request only when its own client cancels it. In an RDB built on this crate, queries that ran 120 to 214 s held every other client, and the writer on the Q wire, for that long. A client-side timeout does not help: the client drops the connection and the query runs on.

How the IPC guard works

• When .ipc.on.sync or .ipc.on.async is set, the core passes it each request's payload in place of evaluating it, but only if the hook is a Rayfall lambda (hook_lookup, src/core/ipc.c). So the hook is a one-line lambda over a native function bound with env::bind_unary
• A watcher thread calls ray_request_interrupt when a request passes the budget, or when a non-blocking peek on the request's socket reads zero bytes. The socket comes from .ipc.handle and ray_poll_get
• The watcher and the guard share a lock, and the guard clears the core's interrupt flag under it when a request ends, so an interrupt never lands on whatever the loop evaluates next
• No change to the core

Limits

• The Q wire never reads the hooks, so a writer there is never cancelled. It can still wait for every request queued ahead of it: when the running request ends, the core takes what is ready on the two wires in an order of its own, and took a queued query before the push in about one run in four. The writer test pins that bound
• One IPC server per process, because the hooks are globals. A client can redefine them, so a server that has to hold its budget should serve clients in restricted mode
• Dropping IpcServer or QListener stops the guard, not the serving: the public header has no ray_poll_deregister, so the socket closes with the runtime
• A cancel that lands while the core interns symbols in bulk can corrupt the shared symbol table (Cancelling a symbol-domain batch intern can corrupt the shared domain rayforce#715). This change makes cancels routine, so that fix matters more
• Hangup detection has been run on macOS only; CI covers Linux

Verification

At this branch's HEAD, on macOS:

• cargo fmt --all -- --check and cargo clippy --workspace --all-targets -- -D warnings: clean
• cargo test --workspace: 168 passed, 0 failed, including 12 in q_subscribe.rs, 3 in q_serve.rs and 8 in ipc_serve.rs
• cargo package -p rayforce-sys --list carries q_server.c / q_server.h
• Poll, Subscription and QListener are !Send/!Sync, each pinned by a compile_fail doctest paired with a control. IpcServer carries the same marker but no doctest yet

🤖 Generated with Claude Code