ffi: foreign-callable — receive callbacks from C

jolt could call C (foreign-fn -> foreign-procedure) but C could not call back
into jolt, which GTK signals (and any callback-taking C API) require. Add the
inverse: jolt.ffi/foreign-callable wraps a jolt fn as a C-callable function
pointer, mirroring the foreign-fn pipeline.

A new jolt.ffi/__ccallable special form carries the fn as a child expression
(analyzed + walked by the passes; ir.clj gains an :ffi-callable arm in both
child walks) plus literal arg/ret type keywords. The back end lowers it to a
locked Chez foreign-callable and returns its entry-point address as a jolt
pointer; host/chez/ffi.ss registers the code object so the collector keeps it,
and free-callable unlocks it. :collect-safe emits the convention that
reactivates the thread on entry, for callbacks fired while it is parked in a
:blocking call (a GTK main loop).

Test: ffi-binding-test.ss sorts an int array through libc qsort with a jolt
comparator (C -> jolt -> C). Re-minted seed.

jolt-core/jolt/analyzer.clj

@@ -424,6 +424,28 @@
    :rettype (name (nth items 3))
    :blocking (and (= 5 (count items)) (= "blocking" (name (nth items 4))))})
 
+;; jolt.ffi/__ccallable: the foreign-CALLBACK form (via the jolt.ffi/foreign-callable
+;; macro) — the inverse of __cfn. It wraps a jolt fn as a C-callable function
+;; pointer so C can call back INTO jolt (GTK signal handlers, qsort comparators).
+;; Shape:
+;;   (jolt.ffi/__ccallable f [:argtype ...] :rettype)                ; thread stays active
+;;   (jolt.ffi/__ccallable f [:argtype ...] :rettype :collect-safe)  ; may be invoked
+;;                                                                   ; while the thread is
+;;                                                                   ; parked in a :blocking call
+;; Unlike __cfn, the fn is a CHILD expression (analyzed + walked by the passes);
+;; the types are literal keywords read at compile time. The Chez back end lowers
+;; it to a locked `foreign-callable` and returns its entry-point address (a jolt
+;; pointer). :collect-safe is required when C invokes the callback from a thread
+;; that is deactivated inside a :blocking foreign call (e.g. a GTK main loop).
+(defn- analyze-ffi-callable [ctx items env]
+  (when-not (<= 4 (count items) 5)
+    (throw (str "jolt.ffi/foreign-callable expects (foreign-callable f [argtypes] rettype [:collect-safe])")))
+  {:op :ffi-callable
+   :fn (analyze ctx (nth items 1) env)
+   :argtypes (mapv name (form-vec-items (nth items 2)))
+   :rettype (name (nth items 3))
+   :collect-safe (and (= 5 (count items)) (= "collect-safe" (name (nth items 4))))})
+
 ;; The `.` special form: `(. target member arg*)` — member access / method call.
 ;; A symbol member whose name starts with "-" is a field read; otherwise it is a
 ;; method (call with the trailing args). Both lower to a :host-call carrying the
@@ -506,6 +528,11 @@
           (and (form-sym? head) (= "jolt.ffi" (form-sym-ns head))
                (= "__cfn" (form-sym-name head)))
             (analyze-ffi-fn ctx items env)
+          ;; jolt.ffi/__ccallable — the foreign-callback special form (the fn is a
+          ;; child expression, analyzed here).
+          (and (form-sym? head) (= "jolt.ffi" (form-sym-ns head))
+               (= "__ccallable" (form-sym-name head)))
+            (analyze-ffi-callable ctx items env)
           ;; special-form heads are NOT shadowable (unlike macros): a local named
           ;; `if` does not change the meaning of (if …) in operator position, per
           ;; spec §3 and the reference. No (not shadowed) guard here.

jolt-core/jolt/backend_scheme.clj

@@ -287,6 +287,19 @@
        " (" (str/join " " (map ffi-type->chez (:argtypes node))) ") "
        (ffi-type->chez (:rettype node)) ")"))
 
+;; jolt.ffi/__ccallable -> a Chez foreign-callable wrapping the emitted jolt fn,
+;; locked + registered (jolt-ffi-register-callable!, host/chez/ffi.ss) so the
+;; collector neither moves nor reclaims it while C may still call through it. The
+;; expression evaluates to the entry-point address — a jolt pointer the caller
+;; hands to C. :collect-safe emits the convention that reactivates the thread on
+;; entry, for callbacks invoked while it is parked in a :blocking foreign call.
+(defn- emit-ffi-callable [node]
+  (str "(jolt-ffi-register-callable! (foreign-callable "
+       (when (:collect-safe node) "__collect_safe ")
+       (emit (:fn node))
+       " (" (str/join " " (map ffi-type->chez (:argtypes node))) ") "
+       (ffi-type->chez (:rettype node)) "))"))
+
 (defn- emit-recur [node]
   (when-not *recur-target* (throw (ex-info "emit: recur outside a loop/fn target" {})))
   (let [arg-nodes (:args node)]
@@ -500,6 +513,7 @@
     :loop (emit-loop node)
     :recur (emit-recur node)
     :ffi-fn (emit-ffi-fn node)
+    :ffi-callable (emit-ffi-callable node)
     :fn (emit-fn node)
     ;; (def name) with no init (declare): reserve the cell. A def with non-empty
     ;; reader metadata lowers to def-var-with-meta! (ported in a later increment).

jolt-core/jolt/ir.clj

@@ -94,6 +94,7 @@
       (= op :set-var) (assoc node :val (f (get node :val)))
       (= op :set-field) (assoc node :obj (f (get node :obj)) :val (f (get node :val)))
       (= op :defmacro) (assoc node :fn (f (get node :fn)))
+      (= op :ffi-callable) (assoc node :fn (f (get node :fn)))
       (= op :invoke) (assoc node :fn (f (get node :fn))
                                  :args (mapv f (get node :args)))
       (= op :vector) (assoc node :items (mapv f (get node :items)))
@@ -140,6 +141,7 @@
       (= op :set-var) (f acc (get node :val))
       (= op :set-field) (f (f acc (get node :obj)) (get node :val))
       (= op :defmacro) (f acc (get node :fn))
+      (= op :ffi-callable) (f acc (get node :fn))
       (= op :invoke) (reduce f (f acc (get node :fn)) (get node :args))
       (= op :vector) (reduce f acc (get node :items))
       (= op :set) (reduce f acc (get node :items))