feat: scalar fast-path codegen

Author: gmelodie

README.md

@@ -114,13 +114,17 @@ The default wire format is `cbor`. Override the library default with
 An `abi = c` proc whose whole signature is scalar — fixed-width integer, float,
 or bool params (a `string` return is fine, a `string` param is not) and no
 structs, handles, or pointers — dispatches through a CBOR-free scalar fast path.
-Foreign-binding codegen for that shape isn't implemented yet, so
-under `-d:ffiGenBindings` such a proc would be omitted from the generated
-bindings — and `genBindings()` fails with an error naming the affected procs.
-Resolve it by switching the proc to `abi = cbor`, adding a non-scalar param so it
-takes the CBOR wire shape, or passing `-d:ffiAllowScalarSkip` to accept the
-omission (the proc still works over the scalar fast path; it's just absent from
-the generated foreign bindings).
+The `-d:targetLang=c_abi` generator emits real bindings for that shape: the
+wrapper passes the scalar args inline (no request struct) and adapts the
+raw-bytes reply into the same typed callback surface the flat-struct methods
+use. The CBOR-speaking targets (`c`, `cpp`, `rust`, `cddl`) have no scalar
+codegen, so under `-d:ffiGenBindings` they would omit such a proc from the
+generated bindings — and `genBindings()` fails with an error naming the
+affected procs. Resolve it by generating with `-d:targetLang=c_abi`, switching
+the proc to `abi = cbor`, adding a non-scalar param so it takes the CBOR wire
+shape, or passing `-d:ffiAllowScalarSkip` to accept the omission (the proc
+still works over the scalar fast path; it's just absent from the generated
+foreign bindings).
 
 ## Placement of `genBindings()`
 

examples/echo/c_abi_bindings/echo.h

@@ -30,14 +30,20 @@ typedef struct {
 } EchoShoutReq;
 
 typedef void (*EchoShoutReplyFn)(int err_code, const ShoutResponse* reply, const char* err_msg, void* user_data);
+typedef void (*EchoVersionReplyFn)(int err_code, const char* reply, const char* err_msg, void* user_data);
 
 typedef void (*EchoCreateRawFn)(int err_code, const char* ctx_addr, const char* err_msg, void* user_data);
+/* Raw reply of a scalar-fast-path export: `msg`/`len` are raw bytes (a
+   string return's UTF-8, or the 8-byte native-endian scalar image), not
+   NUL-terminated and valid only for the duration of the call. */
+typedef void (*EchoScalarRawFn)(int caller_ret, char* msg, size_t len, void* user_data);
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 void* echo_create(const EchoCreateCtorReq* req, EchoCreateRawFn on_created, void* user_data);
 int echo_shout(void* ctx, EchoShoutReplyFn on_reply, void* user_data, const EchoShoutReq* req);
+int echo_version(void* ctx, EchoScalarRawFn callback, void* user_data);
 int echo_destroy(void* ctx);
 
 #ifdef __cplusplus
@@ -107,4 +113,44 @@ static inline int echo_ctx_shout(const EchoCtx* ctx, const ShoutRequest* req, Ec
     return echo_shout(ctx->ptr, on_reply, user_data, &ffi_req);
 }
 
+typedef struct { EchoVersionReplyFn fn; void* user_data; } EchoVersionScalarBox;
+static void echo_version_scalar_reply(int caller_ret, char* msg, size_t len, void* ud) {
+    EchoVersionScalarBox* box = (EchoVersionScalarBox*)ud;
+    if (!box) return;
+    EchoVersionReplyFn fn = box->fn;
+    void* user_data = box->user_data;
+    free(box);
+    if (!fn) return;
+    if (caller_ret != NIMFFI_RET_OK) {
+        char* em = (char*)malloc(len + 1);
+        if (em) {
+            if (len > 0) memcpy(em, msg, len);
+            em[len] = '\0';
+        }
+        fn(caller_ret, "", em ? em : "FFI call failed", user_data);
+        free(em);
+        return;
+    }
+    char* reply = (char*)malloc(len + 1);
+    if (!reply) {
+        fn(NIMFFI_RET_ERR, "", "out of memory", user_data);
+        return;
+    }
+    if (len > 0) memcpy(reply, msg, len);
+    reply[len] = '\0';
+    fn(NIMFFI_RET_OK, reply, "", user_data);
+    free(reply);
+}
+
+static inline int echo_ctx_version(const EchoCtx* ctx, EchoVersionReplyFn on_reply, void* user_data) {
+    EchoVersionScalarBox* box = (EchoVersionScalarBox*)malloc(sizeof(EchoVersionScalarBox));
+    if (!box) {
+        if (on_reply) on_reply(-1, "", "out of memory", user_data);
+        return -1;
+    }
+    box->fn = on_reply;
+    box->user_data = user_data;
+    return echo_version(ctx->ptr, echo_version_scalar_reply, box);
+}
+
 #endif /* NIM_FFI_LIB_ECHO_C_ABI_H_INCLUDED */

ffi.nimble

@@ -259,15 +259,12 @@ task genbindings_c_echo, "Generate C bindings for the echo example":
     " -d:ffiSrcPath=../echo.nim" & " -o:/dev/null examples/echo/echo.nim"
 
 task genbindings_c_abi_echo, "Generate CBOR-free abi=c C bindings for the echo example":
-  # echoVersion is all-scalar under the abi=c default, so it has no foreign
-  # codegen yet and is omitted from the bindings; -d:ffiAllowScalarSkip accepts
-  # that omission instead of failing the build (see genBindings()).
   exec "nim c " & nimFlagsOrc & " --app:lib --noMain --nimMainPrefix:libecho" &
-    " -d:ffiEchoAbiC -d:ffiGenBindings -d:targetLang=c_abi -d:ffiAllowScalarSkip" &
+    " -d:ffiEchoAbiC -d:ffiGenBindings -d:targetLang=c_abi" &
     " -d:ffiOutputDir=examples/echo/c_abi_bindings" & " -d:ffiSrcPath=../echo.nim" &
     " -o:/dev/null examples/echo/echo.nim"
   exec "nim c " & nimFlagsRefc & " --app:lib --noMain --nimMainPrefix:libecho" &
-    " -d:ffiEchoAbiC -d:ffiGenBindings -d:targetLang=c_abi -d:ffiAllowScalarSkip" &
+    " -d:ffiEchoAbiC -d:ffiGenBindings -d:targetLang=c_abi" &
     " -d:ffiOutputDir=examples/echo/c_abi_bindings" & " -d:ffiSrcPath=../echo.nim" &
     " -o:/dev/null examples/echo/echo.nim"
 

ffi/codegen/c_abi.nim

@@ -131,7 +131,9 @@ proc newAbiReg(types: seq[FFITypeMeta], procs: seq[FFIProcMeta]): AbiReg =
   for t in types:
     reg.typeTable[t.name] = t
   for p in procs:
-    if p.kind != FFIKind.DTOR:
+    # A scalar-fast-path proc has no Req envelope: its export takes the scalar
+    # args inline (see emitScalarMethod).
+    if p.kind != FFIKind.DTOR and not p.scalarFastPath:
       let rt = reqTypeMeta(p)
       reg.typeTable[rt.name] = rt
   reg
@@ -200,38 +202,69 @@ proc emitReplyTypedefs(
         " reply, const char* err_msg, void* user_data);"
     )
 
+func scalarRawFnName(libType: string): string =
+  ## The `FFICallBack`-shaped raw callback typedef a scalar-fast-path export
+  ## takes: the dylib replies with raw bytes (no CBOR, no flat struct) that the
+  ## per-method trampoline converts into the typed reply.
+  libType & "ScalarRawFn"
+
+proc scalarArgParams(m: FFIProcMeta): seq[string] =
+  ## C parameters for a scalar method's args — passed inline by value, in both
+  ## the raw export and the high-level wrapper (no Req struct).
+  var params: seq[string] = @[]
+  for ep in m.extraParams:
+    params.add(leafCTypeAbi(ep.typeName.strip()).cType & " " & ep.name)
+  params
+
 proc emitExternDecls(
     lines: var seq[string],
     reg: var AbiReg,
     libName, libType: string,
     procs: seq[FFIProcMeta],
 ) =
   let createRawFn = libType & "CreateRawFn"
-  var haveCtor = false
+  var haveCtor, haveScalar = false
   for p in procs:
     if p.kind == FFIKind.CTOR:
       haveCtor = true
+    if p.scalarFastPath:
+      haveScalar = true
   if haveCtor:
     lines.add(
       "typedef void (*" & createRawFn &
         ")(int err_code, const char* ctx_addr, const char* err_msg, void* user_data);"
     )
+  if haveScalar:
+    lines.add("/* Raw reply of a scalar-fast-path export: `msg`/`len` are raw bytes (a")
+    lines.add(
+      "   string return's UTF-8, or the 8-byte native-endian scalar image), not"
+    )
+    lines.add("   NUL-terminated and valid only for the duration of the call. */")
+    lines.add(
+      "typedef void (*" & scalarRawFnName(libType) &
+        ")(int caller_ret, char* msg, size_t len, void* user_data);"
+    )
   lines.add("#ifdef __cplusplus")
   lines.add("extern \"C\" {")
   lines.add("#endif")
   lines.add("")
   for p in procs:
-    let reqStruct = reqStructName(p)
     case p.kind
     of FFIKind.FFI:
-      let info = methodReplyInfo(reg, libType, p)
-      lines.add(
-        "int " & p.procName & "(void* ctx, " & info.fnType &
-          " on_reply, void* user_data, const " & reqStruct & "* req);"
-      )
+      if p.scalarFastPath:
+        var params =
+          @["void* ctx", scalarRawFnName(libType) & " callback", "void* user_data"]
+        params.add(scalarArgParams(p))
+        lines.add("int " & p.procName & "(" & params.join(", ") & ");")
+      else:
+        let info = methodReplyInfo(reg, libType, p)
+        lines.add(
+          "int " & p.procName & "(void* ctx, " & info.fnType &
+            " on_reply, void* user_data, const " & reqStructName(p) & "* req);"
+        )
     of FFIKind.CTOR:
       lines.add(
-        "void* " & p.procName & "(const " & reqStruct & "* req, " & createRawFn &
+        "void* " & p.procName & "(const " & reqStructName(p) & "* req, " & createRawFn &
           " on_created, void* user_data);"
       )
     of FFIKind.DTOR:
@@ -368,6 +401,130 @@ proc emitMethod(
   lines.add("}")
   lines.add("")
 
+func scalarOkLines(m: FFIProcMeta, fnType: string): seq[string] =
+  ## Trampoline RET_OK branch: convert the raw reply bytes into the typed
+  ## reply. A string return rides as its own UTF-8 bytes (copied and
+  ## NUL-terminated here); every other scalar is the 8-byte native-endian image
+  ## of the Nim-side pack (signed ints sign-extended to 64 bits, floats widened
+  ## to double, bool as 0/1 — see `ffiScalarRetBytes`).
+  let rt = m.returnTypeName.strip()
+  if rt == "string" or rt == "cstring":
+    return @[
+      "    char* reply = (char*)malloc(len + 1);", "    if (!reply) {",
+      "        fn(NIMFFI_RET_ERR, \"\", \"out of memory\", user_data);",
+      "        return;", "    }", "    if (len > 0) memcpy(reply, msg, len);",
+      "    reply[len] = '\\0';", "    fn(NIMFFI_RET_OK, reply, \"\", user_data);",
+      "    free(reply);",
+    ]
+  var lines = @[
+    "    uint64_t slot = 0;", "    if (!msg || len != sizeof(slot)) {",
+    "        fn(NIMFFI_RET_ERR, NULL, \"scalar reply: unexpected payload size\", user_data);",
+    "        return;", "    }", "    memcpy(&slot, msg, sizeof(slot));",
+  ]
+  let cType = leafCTypeAbi(rt).cType
+  case rt
+  of "int", "int64":
+    lines.add("    int64_t reply;")
+    lines.add("    memcpy(&reply, &slot, sizeof(reply));")
+  of "int8", "int16", "int32":
+    lines.add("    int64_t wide;")
+    lines.add("    memcpy(&wide, &slot, sizeof(wide));")
+    lines.add("    " & cType & " reply = (" & cType & ")wide;")
+  of "uint", "uint64":
+    lines.add("    uint64_t reply = slot;")
+  of "uint8", "uint16", "uint32", "byte":
+    lines.add("    " & cType & " reply = (" & cType & ")slot;")
+  of "bool":
+    lines.add("    bool reply = slot != 0;")
+  of "float", "float64":
+    lines.add("    double reply;")
+    lines.add("    memcpy(&reply, &slot, sizeof(reply));")
+  of "float32":
+    lines.add("    double wide;")
+    lines.add("    memcpy(&wide, &slot, sizeof(wide));")
+    lines.add("    float reply = (float)wide;")
+  else:
+    raise newException(
+      ValueError, "abi = c: unexpected scalar-fast-path return type: " & rt
+    )
+  lines.add("    fn(NIMFFI_RET_OK, &reply, \"\", user_data);")
+  lines
+
+proc emitScalarMethod(
+    lines: var seq[string],
+    reg: var AbiReg,
+    ctxType, libName, libType: string,
+    m: FFIProcMeta,
+) =
+  ## A scalar-fast-path method: no Req struct crosses — the wrapper hands the
+  ## scalar args straight to the raw export and a per-method trampoline adapts
+  ## the raw-bytes reply into the same typed `ReplyFn` surface the flat-struct
+  ## methods use. The heap box carrying the caller's callback is freed by the
+  ## trampoline, which the dylib invokes exactly once on every path (the ctx
+  ## guard and enqueue failures reply synchronously; success replies from the
+  ## FFI thread).
+  let stripped = stripLibPrefix(m.procName, m.libName)
+  let pascal = snakeToPascalCase(stripped)
+  let info = methodReplyInfo(reg, libType, m)
+  let boxType = libType & pascal & "ScalarBox"
+  let tramp = m.procName & "_scalar_reply"
+  let isStr = m.returnTypeName.strip() in ["string", "cstring"]
+  let errReply = if isStr: "\"\"" else: "NULL"
+  lines.add(
+    "typedef struct { " & info.fnType & " fn; void* user_data; } " & boxType & ";"
+  )
+  lines.add(
+    "static void " & tramp & "(int caller_ret, char* msg, size_t len, void* ud) {"
+  )
+  lines.add("    " & boxType & "* box = (" & boxType & "*)ud;")
+  lines.add("    if (!box) return;")
+  lines.add("    " & info.fnType & " fn = box->fn;")
+  lines.add("    void* user_data = box->user_data;")
+  lines.add("    free(box);")
+  lines.add("    if (!fn) return;")
+  lines.add("    if (caller_ret != NIMFFI_RET_OK) {")
+  lines.add("        char* em = (char*)malloc(len + 1);")
+  lines.add("        if (em) {")
+  lines.add("            if (len > 0) memcpy(em, msg, len);")
+  lines.add("            em[len] = '\\0';")
+  lines.add("        }")
+  lines.add(
+    "        fn(caller_ret, " & errReply & ", em ? em : \"FFI call failed\", user_data);"
+  )
+  lines.add("        free(em);")
+  lines.add("        return;")
+  lines.add("    }")
+  for l in scalarOkLines(m, info.fnType):
+    lines.add(l)
+  lines.add("}")
+  lines.add("")
+  let params = scalarArgParams(m)
+  let head =
+    "static inline int " & libName & "_ctx_" & stripped & "(const " & ctxType & "* ctx, "
+  let sig =
+    if params.len > 0:
+      head & params.join(", ") & ", " & info.fnType & " on_reply, void* user_data) {"
+    else:
+      head & info.fnType & " on_reply, void* user_data) {"
+  lines.add(sig)
+  lines.add(
+    "    " & boxType & "* box = (" & boxType & "*)malloc(sizeof(" & boxType & "));"
+  )
+  lines.add("    if (!box) {")
+  lines.add(
+    "        if (on_reply) on_reply(-1, " & errReply & ", \"out of memory\", user_data);"
+  )
+  lines.add("        return -1;")
+  lines.add("    }")
+  lines.add("    box->fn = on_reply;")
+  lines.add("    box->user_data = user_data;")
+  var callArgs = @["ctx->ptr", tramp, "box"]
+  for ep in m.extraParams:
+    callArgs.add(ep.name)
+  lines.add("    return " & m.procName & "(" & callArgs.join(", ") & ");")
+  lines.add("}")
+  lines.add("")
+
 proc generateCAbiLibHeader*(
     procs: seq[FFIProcMeta],
     types: seq[FFITypeMeta],
@@ -386,7 +543,7 @@ proc generateCAbiLibHeader*(
   for t in types:
     ensureAbiStruct(reg, t.name)
   for p in procs:
-    if p.kind != FFIKind.DTOR:
+    if p.kind != FFIKind.DTOR and not p.scalarFastPath:
       ensureAbiStruct(reg, reqStructName(p))
 
   let guard = "NIM_FFI_LIB_" & libName.toUpperAscii() & "_C_ABI_H_INCLUDED"
@@ -417,7 +574,10 @@ proc generateCAbiLibHeader*(
   emitCtxAndCtor(lines, reg, libName, libType, ctxType, classified.ctors)
   emitDestructor(lines, ctxType, libName, classified.dtorProcName)
   for m in classified.methods:
-    emitMethod(lines, reg, ctxType, libName, libType, m)
+    if m.scalarFastPath:
+      emitScalarMethod(lines, reg, ctxType, libName, libType, m)
+    else:
+      emitMethod(lines, reg, ctxType, libName, libType, m)
 
   lines.add("#endif /* " & guard & " */")
   lines.join("\n") & "\n"

ffi/codegen/meta.nim

@@ -33,9 +33,10 @@ 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`): dispatches through the CBOR-free scalar fast path and
-      ## is skipped by the foreign-binding generators (their codegen is a
-      ## follow-up).
+      ## `isScalarOnly`): dispatches through the CBOR-free scalar fast path.
+      ## Only the `c_abi` generator emits foreign bindings for it (inline
+      ## scalar args + raw-bytes reply trampoline); the CBOR-speaking
+      ## generators drop it (see `bindableProcs`).
 
   FFIFieldMeta* = object
     name*: string # e.g. "delayMs"