Wire the per-type subscription cache into RclcppyyNode.create_subscription

The startup-JIT lane on cppyy_kit (subscription cache in rclcpp_kit) removes the
~2.8 s cppyy JIT of create_subscription<MsgT>; rclcppyy has to opt in to benefit.

RclcppyyNode.create_subscription previously did two uncacheable JITs per call: a
per-UUID cppyy.cppdef of a <Python.h> lambda trampoline, and the raw
create_subscription[MsgT] template. Both are replaced by:

  * cpp_callback = std::function<void(std::shared_ptr<const MsgT>)>(callback) built
    directly via cppyy -- it delivers the C++ message proxy straight to the Python
    callback and manages the GIL, so the old raw-pointer rebinding trampoline is
    gone; and
  * rclcpp_kit.subscription_cache.make_subscription(node, cpp_type, header, topic,
    qos, cpp_callback), which loads a prebuilt per-type .so (or schedules a
    background build and returns None -> plain-template fallback this run).

The header is derived from the resolved C++ type string (_subscription_header,
rosidl CamelCase->snake) rather than rclcpp_kit.message_header: under acceleration
the message class is already a cppyy C++ type, for which message_header returns
None. subscription_cache is absent on the published suite 0.1.0, so the whole path
is guarded and falls back to the plain create_subscription[MsgT] call there
(pub/sub roundtrip tests still pass in the default env). Correctness first; the
cache is a pure speedup.

Measured on the real `ros2 topic hz` (demo-topic-hz-startup, time to first hz line):
stock 1.7 s; RCLCPPYY_ENABLE_HOOK=1 cold 8.3 s, warm 4.1 s. The subscription cache
cut the warm start ~7.0 s -> 4.1 s (the eliminated create_subscription<Image> JIT);
the residual gap over stock is rclcpp bring-up (cppyy symbol discovery + adapters),
not yet cached. Delivery verified: hooked ros2 topic hz reports exact rates.

pixi run test: 32 passed. pixi run lint: clean. README startup section updated.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: awesomebytes

README.md

@@ -281,21 +281,23 @@ stock rclpy crosses one full core near 200–250 Hz (92–107 %), while the acce
 backend stays around a third of a core, so on a busier machine or at a higher rate
 the stock reader saturates first.
 
-**Startup: the acceleration is a one-time cost.** Time-to-first-hz-line
+**Startup: a one-time cost.** Time to first hz line
 (`pixi run -e heavydemo demo-topic-hz-startup`):
 
 | `ros2 topic hz` first hz line | time |
 |---|---|
 | stock (no acceleration) | ~1.7 s |
-| `RCLCPPYY_ENABLE_HOOK=1`, cold PCH cache | ~8.0 s |
-| `RCLCPPYY_ENABLE_HOOK=1`, warm PCH cache | ~7.0 s |
-
-The suite's zero-config Cling PCH shaves ~1.1 s (the `rclcpp` header parse) off the
-first line, cold→warm; the remaining ~5 s over stock is one-time rclcpp bring-up
-plus first-use JIT of the message type and subscription glue, which the header PCH
-does not cover. So acceleration adds a multi-second startup and **pays off for
-long-running `hz` sessions**, not short invocations. (Needs the newer auto-PCH; see
-the dev-bridge note below.)
+| `RCLCPPYY_ENABLE_HOOK=1`, cold cache | ~8.3 s |
+| `RCLCPPYY_ENABLE_HOOK=1`, warm cache | ~4.1 s |
+
+Two caches cut the warm start: the suite's Cling PCH removes the `rclcpp` header
+parse, and a per-message-type subscription cache removes the ~2.8 s one-time JIT of
+`create_subscription<MsgT>` (both built on the first run and loaded on later ones,
+cold → warm above). The warm figure is still above stock because the rest of the
+rclcpp bring-up — cppyy symbol discovery and the rclpy-compatibility adapters — is
+not yet cached. Acceleration therefore remains a one-time startup cost that pays off
+over a long-running `hz` session rather than a single short call. (Needs the newer
+suite; see the dev-bridge note below.)
 
 ### Large messages under BEST_EFFORT QoS
 

rclcppyy/node.py

@@ -1,4 +1,5 @@
 import inspect
+import re
 import uuid
 from typing import Union, Optional, Callable, Any, List
 import rclpy
@@ -16,6 +17,25 @@
 from rclcppyy import bringup_rclcpp
 from rclcppyy.bringup_rclcpp import _resolve_message_type, _is_msg_python, convert_python_msg_to_cpp
 
+
+def _subscription_header(cpp_type_str):
+    """C++ header path for a resolved message type string (e.g.
+    ``sensor_msgs::msg::Image`` -> ``sensor_msgs/msg/image.hpp``), for the
+    subscription cache's ``#include``. Derived from the type string because under
+    acceleration the message class is already a C++ (cppyy) type, for which
+    rclcpp_kit.message_header returns None. Uses rosidl's CamelCase->snake_case
+    convention (``PointCloud2`` -> ``point_cloud2``, ``TFMessage`` -> ``tf_message``).
+    Returns None if the string isn't a ``pkg::msg::Name`` triple.
+    """
+    parts = cpp_type_str.split("::")
+    if len(parts) != 3:
+        return None
+    package, _, name = parts
+    snake = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2",
+                   re.sub(r"(.)([A-Z][a-z]+)", r"\1_\2", name)).lower()
+    return "%s/msg/%s.hpp" % (package, snake)
+
+
 class RclcppyyNode(Node):
     """
     This node inherits from rclpy Node but it uses rclcpp for publishers/subscribers.
@@ -75,28 +95,7 @@ def __init__(self,
         """
         self._cpp_timers = {}
 
-        # Subscription callback template for dynamic C++ callback generation
-        self._subscription_cpp_template = """
-            #include <Python.h>
-            #include <functional>
-            
-            static std::function<void(const PLACEHOLDER_MSG_TYPE::SharedPtr)> 
-            create_subscription_callback_PLACEHOLDER_UUID(PyObject* self) {
-                return [self](const PLACEHOLDER_MSG_TYPE::SharedPtr msg) {
-                    if (self && PyObject_HasAttrString(self, "_subscription_callback_PLACEHOLDER_UUID")) {
-                        // Acquire the GIL before calling into Python to avoid crashes
-                        PyGILState_STATE gstate = PyGILState_Ensure();
-                        // Pass the raw pointer as a Python int; Python will bind it back to a proxy
-                        PyObject* py_ptr = PyLong_FromVoidPtr(reinterpret_cast<void*>(msg.get()));
-                        PyObject_CallMethod(self, "_subscription_callback_PLACEHOLDER_UUID", "O", py_ptr);
-                        Py_XDECREF(py_ptr);
-                        PyGILState_Release(gstate);
-                    }
-                };
-            }
-        """
         self._cpp_subscriptions = {}
-        self._subscription_callbacks = {}
 
         # Now we create the rclpy node
         super().__init__(node_name,
@@ -310,74 +309,56 @@ def create_subscription(self,
 
         # Convert rclpy message to rclcpp message type
         rclcpp_msg_type, rclcpp_msg_class = _resolve_message_type(msg_type)
-        # We could make this optional for efficiency
-        # add_python_compatibility(cpp_msg, msg_type)
-        
-        # Generate a unique UUID for the subscription
-        uuid_str = str(uuid.uuid4()).replace("-", "_")
-        
-        # Replace placeholders in the C++ template
-        cpp_subscription_template = self._subscription_cpp_template.replace(
-            "PLACEHOLDER_MSG_TYPE", rclcpp_msg_type
-        ).replace("PLACEHOLDER_UUID", uuid_str)
-        
-        # Compile the C++ callback wrapper
-        cppyy.cppdef(cpp_subscription_template)
-        
-        # Store a Python wrapper that translates raw pointer (int) back to C++ proxy and calls user callback
-        def _cpp_bound_subscription_callback(py_ptr):
-            try:
-                # Resolve cpp class for binding
-                # _, cpp_msg_class = _resolve_message_type(msg_type)
-                # Rebind raw pointer (Python int) to a cppyy proxy
-                cpp_msg = cppyy.bind_object(py_ptr, rclcpp_msg_class)
-                callback(cpp_msg)
-            except Exception as e:
-                print(f"Error in subscription callback: {e}")
-                import traceback
-                traceback.print_exc()
-
-        # Store the wrapper on the node instance
-        setattr(self, f"_subscription_callback_{uuid_str}", _cpp_bound_subscription_callback)
-        
-        # Create the C++ callback wrapper
-        cpp_callback = getattr(cppyy.gbl, f"create_subscription_callback_{uuid_str}")(self)
-        
-        # Create subscription options for rclcpp
-        options = self._rclcpp.SubscriptionOptionsWithAllocator["std::allocator<void>"]()
-        if callback_group:
-            # TODO: Convert callback group from rclpy to rclcpp if needed
-            pass
-        if qos_overriding_options:
-            # TODO: Handle QoS overriding options
-            pass
-        
+
+        # Build the C++ callback directly as a std::function. cppyy delivers the C++
+        # message proxy straight to the Python callback and manages the GIL, so no
+        # per-subscription C++ trampoline (the old per-UUID <Python.h> lambda that
+        # rebound a raw pointer) is needed.
+        cpp_callback = cppyy.gbl.std.function[
+            "void(std::shared_ptr<const %s>)" % rclcpp_msg_type
+        ](callback)
+
         # Convert QoS profile to rclcpp QoS
         rclcpp_qos = self._convert_qos_to_rclcpp(qos_profile)
-        
-        # Create the actual rclcpp subscription
-        subscription = self._rclcpp.create_subscription[rclcpp_msg_type](
-            self._rclcpp_node,
-            final_topic,
-            rclcpp_qos,
-            cpp_callback,
-            options
-        )
-        
-        # Store the subscription and callback reference
+
+        # Route through the cached per-type trampoline so the ~2.8 s
+        # create_subscription<MsgT> template instantiation JITs once into a .so
+        # instead of on every process start. Falls back to the plain template call
+        # when no .so is built yet (this run), for callback groups / QoS overrides,
+        # or when the message header can't be derived -- correctness first, the cache
+        # is a pure speedup.
+        subscription = None
+        if callback_group is None and qos_overriding_options is None:
+            try:
+                # subscription_cache postdates rclcpp_kit 0.1.0; on an older suite it
+                # is absent and we simply use the plain path.
+                from rclcpp_kit import subscription_cache
+                header = _subscription_header(rclcpp_msg_type)
+                if header:
+                    subscription = subscription_cache.make_subscription(
+                        self._rclcpp_node, rclcpp_msg_type, header, final_topic,
+                        rclcpp_qos, cpp_callback)
+            except ImportError:
+                subscription = None
+        if subscription is None:
+            options = self._rclcpp.SubscriptionOptionsWithAllocator["std::allocator<void>"]()
+            subscription = self._rclcpp.create_subscription[rclcpp_msg_type](
+                self._rclcpp_node, final_topic, rclcpp_qos, cpp_callback, options)
+
+        # Keep the Python callback and its std::function wrapper alive for the
+        # subscription's lifetime; dropping them would dangle the C++ callback.
         self._cpp_subscriptions[subscription] = {
             'callback': callback,
-            'uuid': uuid_str,
-            'msg_type': rclcpp_msg_type
+            'cpp_callback': cpp_callback,
+            'msg_type': rclcpp_msg_type,
         }
-        self._subscription_callbacks[uuid_str] = callback
-        
+
         # Add to subscriptions list for compatibility
         self._subscriptions.append(subscription)
-        
+
         # Wake executor like rclpy does
         self._wake_executor()
-        
+
         return subscription
 
     def destroy_node(self):

scripts/heavy_hz_demo/run_topic_hz_cli.py

@@ -295,12 +295,18 @@ def startup_story(args):
         log("Building the PCH cache with a clean-exiting helper ...")
         _warm_pch_cache(story_cache, args.echo)
         _wait_pch(story_cache)
+        # The hz path also JIT-instantiates create_subscription<Image> (~2.8 s); build
+        # its cached trampoline .so so the warm run loads it too.
+        log("Building the subscription-trampoline cache ...")
+        _prebuild_subscription(story_cache, "sensor_msgs::msg::Image",
+                               "sensor_msgs/msg/image.hpp", args.echo)
         log("[WARM] PCH cached -> `RCLCPPYY_ENABLE_HOOK=1 ros2 topic hz` ...")
         warm = _run_hz(topic, args.window, True, 2.0, max(args.warmup_timeout, 120.0),
                        story_cache, args.echo)
         log("[WARM] time to first hz line: %ss" % warm["ttfl"])
         log("[PLAIN] stock `ros2 topic hz` (no acceleration) for reference ...")
         plain = _run_hz(topic, args.window, False, 2.0, args.warmup_timeout, None, args.echo)
+        log("[PLAIN] time to first hz line: %ss" % plain["ttfl"])
         print()
         print("  `ros2 topic hz` time-to-first-hz-line")
         print("  " + "=" * 52)
@@ -313,6 +319,21 @@ def startup_story(args):
         shutil.rmtree(story_cache, ignore_errors=True)
 
 
+def _prebuild_subscription(cache_dir, cpp_type, header, echo):
+    """Synchronously build the subscription-trampoline .so into cache_dir so the warm
+    run loads it instead of JIT-instantiating create_subscription<MsgT>."""
+    env = dict(os.environ)
+    env["XDG_CACHE_HOME"] = str(cache_dir)
+    env.pop("CLING_STANDARD_PCH", None)
+    env.pop("_CPPYY_KIT_AUTOPCH_ACTIVE", None)
+    p = Child("subprebuild", [sys.executable, "-u", "-m", "rclcpp_kit._sub_prebuild",
+                              cpp_type, header], env, echo=echo)
+    deadline = time.monotonic() + 180.0
+    while time.monotonic() < deadline and p.alive():
+        time.sleep(0.5)
+    p.stop()
+
+
 def _warm_pch_cache(cache_dir, echo):
     """Bring up acceleration in a throwaway process that exits cleanly, so the
     auto-PCH build (scheduled at interpreter exit) actually runs and populates