chore: scalar fast path

Author: gmelodie

ffi/codegen/meta.nim

@@ -31,6 +31,11 @@ type
     returnIsPtr*: bool # true if return type is ptr T
     returnIsHandle*: bool # true if return type is an {.ffiHandle.} type
     abiFormat*: ABIFormat # wire format for this interaction (default Cbor)
+    scalarFastPath*: bool
+      ## True for an `abi = c` proc whose whole signature is scalar (see
+      ## `isScalarOnly`): it dispatches through the CBOR-free scalar fast path
+      ## and is skipped by the foreign-binding generators (no dispatch codegen
+      ## yet — the request rides inline POD args, no `_CWire`, no CBOR).
 
   FFIFieldMeta* = object
     name*: string # e.g. "delayMs"
@@ -62,6 +67,53 @@ var libraryDeclared* {.compileTime.}: bool = false
 # Library-wide default ABI, inherited by each annotation unless it overrides.
 var currentDefaultABIFormat* {.compileTime.}: ABIFormat = ABIFormat.Cbor
 
+const scalarPodTypeNames = [
+  "int", "int8", "int16", "int32", "int64", "uint", "uint8", "uint16", "uint32",
+  "uint64", "byte", "float", "float32", "float64", "bool",
+]
+  ## Fixed-width POD scalars that fit a single `uint64` slot and survive the
+  ## async hop by value — the payload the scalar fast path inlines into the
+  ## request (no heap copy). `cstring`/`string` are intentionally absent as
+  ## *params*: they are pointers to caller memory the FFI thread reads later,
+  ## so they'd need a copy, defeating the zero-alloc promise.
+
+func isScalarParamTypeName*(name: string): bool =
+  ## A param type eligible for the CBOR-free scalar fast path.
+  name in scalarPodTypeNames
+
+func isScalarReturnTypeName*(name: string): bool =
+  ## A return type eligible for the scalar fast path. Unlike params, a
+  ## `string`/`cstring` return is fine: the handler produces the bytes and they
+  ## ride back raw (like the error path), so no caller memory is aliased.
+  name in scalarPodTypeNames or name == "string" or name == "cstring"
+
+func isScalarOnly*(p: FFIProcMeta): bool =
+  ## True iff `p` is a plain `{.ffi.}` method whose every wire param and return
+  ## is scalar — the whole signature crosses without CBOR or `_CWire`. Handles
+  ## and raw pointers are excluded (a handle needs a ctx-registry round-trip;
+  ## a pointer never crosses). Pure over the compile-time metadata.
+  if p.kind != FFIKind.FFI:
+    return false
+  if p.returnIsPtr or p.returnIsHandle:
+    return false
+  if not isScalarReturnTypeName(p.returnTypeName):
+    return false
+  for ep in p.extraParams:
+    if ep.isPtr or ep.isHandle or not isScalarParamTypeName(ep.typeName):
+      return false
+  true
+
+func bindableProcs*(procs: seq[FFIProcMeta]): seq[FFIProcMeta] =
+  ## The procs the foreign-binding generators emit for. Scalar-fast-path procs
+  ## are dropped: their C export takes inline scalar args, not the CBOR
+  ## `(reqCbor, reqCborLen)` shape the current codegen assumes, so emitting a
+  ## CBOR caller for them would be wrong. Foreign codegen is a follow-up.
+  var kept: seq[FFIProcMeta] = @[]
+  for p in procs:
+    if not p.scalarFastPath:
+      kept.add(p)
+  kept
+
 proc abiCodegenImplemented*(fmt: ABIFormat): bool =
   ## Whether `fmt` has a working proc-dispatch path. Only `Cbor` does today; the
   ## seam a future PR flips once the `c` dispatch path is wired.

ffi/ffi_thread_request.nim

@@ -20,17 +20,53 @@ const EmptyErrorMarker = "unknown error"
   ## the callback's msg ptr non-nil and gives the foreign side a recognizable
   ## fallback to log.
 
+const MaxScalarArgs* = 8
+  ## Inline capacity for the scalar fast path. A `.ffi.` method with more than
+  ## this many scalar params can't use the fast path (checked at compile time).
+
 type FFIThreadRequest* = object
   callback*: FFICallBack
   userData*: pointer
   reqId*: cstring ## Per-proc Req type name used to look up the handler.
   data*: ptr UncheckedArray[byte] ## Owned CBOR-encoded request payload.
   dataLen*: int
+  isScalar*: bool
+    ## Set by `initScalar`: the payload rode inline in `scalarArgs` (no CBOR,
+    ## no `data` buffer), so `deleteRequest` has nothing extra to free.
+  scalarArgs*: array[MaxScalarArgs, uint64]
+    ## Scalar-fast-path args inlined in the envelope (one `ffiPackScalar` value
+    ## per slot) so there's no per-call `c_malloc`. A plain array rather than a
+    ## `union` with `data`: costs a fixed 64 bytes per request but keeps the
+    ## `next` link and `deleteRequest` unaliased and branch-free.
   next*: ptr FFIThreadRequest
     ## Intrusive ingress-queue link (see `ffi_request_queue.nim`). Touched only
     ## under the queue's lock; the request doubles as its own node, so no
     ## separate node alloc lands on the per-thread ORC MemRegion.
 
+func ffiPackScalar*[T](x: T): uint64 =
+  ## Bit-cast one scalar into a `uint64` request slot. Signed ints sign-extend
+  ## to 64 bits; `float32` widens to `float64` (exactly representable, so the
+  ## value round-trips); `bool` becomes 0/1. Reverse with `ffiUnpackScalar`.
+  when T is SomeFloat:
+    cast[uint64](float64(x))
+  elif T is bool:
+    uint64(ord(x))
+  elif T is SomeSignedInt:
+    cast[uint64](int64(x))
+  else:
+    uint64(x)
+
+func ffiUnpackScalar*[T](u: uint64, _: typedesc[T]): T =
+  ## Inverse of `ffiPackScalar`: reinterpret a request slot back into `T`.
+  when T is SomeFloat:
+    T(cast[float64](u))
+  elif T is bool:
+    u != 0'u64
+  elif T is SomeSignedInt:
+    T(cast[int64](u))
+  else:
+    T(u)
+
 proc allocBaseRequest(
     callback: FFICallBack, userData: pointer, reqId: cstring
 ): ptr FFIThreadRequest =
@@ -43,6 +79,7 @@ proc allocBaseRequest(
   ret[].reqId = reqId.alloc()
   ret[].data = nil
   ret[].dataLen = 0
+  ret[].isScalar = false
   ret[].next = nil
   return ret
 
@@ -118,6 +155,49 @@ proc initFromOwnedShared*(
   adoptOwnedSharedPayload(ret, data, dataLen)
   return ret
 
+proc initScalar*(
+    T: typedesc[FFIThreadRequest],
+    callback: FFICallBack,
+    userData: pointer,
+    reqId: cstring,
+    args: varargs[uint64],
+): ptr type T =
+  ## Builds a scalar-fast-path request: the packed scalar args ride inline in
+  ## `scalarArgs` with no payload `c_malloc`. `args` come from `ffiPackScalar`.
+  ## Only the routing `reqId` cstring is heap-allocated, same as the CBOR path.
+  doAssert args.len <= MaxScalarArgs,
+    "initScalar: " & $args.len & " scalar args exceed MaxScalarArgs (" & $MaxScalarArgs &
+      ")"
+  var ret = allocBaseRequest(callback, userData, reqId)
+  ret[].isScalar = true
+  for i in 0 ..< args.len:
+    ret[].scalarArgs[i] = args[i]
+  ret
+
+func ffiScalarRetBytes*[T](x: T): seq[byte] =
+  ## Serializes a scalar handler result into the raw response payload the
+  ## callback carries — no CBOR envelope. A `string`/`cstring` rides as its
+  ## own UTF-8 bytes (like the error path); every other scalar rides as the
+  ## 8-byte native-endian image of `ffiPackScalar(x)`. Note: an empty string
+  ## yields a 0-length payload, which `handleRes` sends as the CBOR-null
+  ## sentinel — the foreign scalar reader (a follow-up) must special-case it.
+  when T is string:
+    var b = newSeq[byte](x.len)
+    if x.len > 0:
+      copyMem(addr b[0], unsafeAddr x[0], x.len)
+    b
+  elif T is cstring:
+    let n = x.len
+    var b = newSeq[byte](n)
+    if n > 0:
+      copyMem(addr b[0], cast[pointer](x), n)
+    b
+  else:
+    let u = ffiPackScalar(x)
+    var b = newSeq[byte](sizeof(uint64))
+    copyMem(addr b[0], unsafeAddr u, sizeof(uint64))
+    b
+
 proc deleteRequest*(request: ptr FFIThreadRequest) =
   if not request[].data.isNil:
     c_free(request[].data)