Merge pull request #36 from SLNE-Development/optimization/use-hidden-classes

perf: Introduce JVM hidden class dispatch for event and request handlers

Author: twisti-dev

README.md

@@ -322,6 +322,31 @@ These APIs:
 
 ---
 
+## Handler Dispatch (Internals)
+
+Event handlers (`@OnRedisEvent`) and request handlers (`@HandleRedisRequest`) are dispatched
+through **JVM hidden classes** generated at registration time.
+
+Each handler method is resolved into a `MethodHandle`, which is then embedded as a
+`static final` constant in a hidden class implementing `RedisEventInvoker` or
+`RedisRequestHandlerInvoker`. This allows the JIT compiler to constant-fold and inline the
+entire dispatch path — significantly outperforming raw `MethodHandle.invoke()` polymorphic calls.
+
+Hidden classes are:
+
+* **Not discoverable** by name — no classloader pollution
+* **Garbage-collectible** when no longer referenced
+* **JIT-friendly** — the dispatch target is a compile-time constant
+
+This approach combines the flexibility of reflection-based handler discovery with
+near-direct-call performance at runtime.
+
+> [!NOTE]
+> This is an implementation detail. The public API for registering handlers
+> (`@OnRedisEvent`, `@HandleRedisRequest`) remains unchanged.
+
+---
+
 ## Guarantees & Non-Guarantees
 
 Guaranteed:

gradle.properties

@@ -3,4 +3,4 @@ kotlin.stdlib.default.dependency=false
 org.gradle.parallel=true
 #org.gradle.caching=true
 #org.gradle.configureondemand=true
-version=1.21.11-1.4.0
+version=1.21.11-1.4.1

surf-redis-api/src/main/kotlin/dev/slne/surf/redis/event/RedisEventBus.kt

@@ -19,8 +19,10 @@ import java.io.Closeable
  * ## Dispatch
  * Event handlers are invoked synchronously on a Redisson/Reactor thread (see [OnRedisEvent]).
  *
- * For invocation, the implementation uses `MethodHandle`s (via `java.lang.invoke`) rather than
- * JVM-generated lambda factories to avoid classloader-related issues.
+ * For invocation, the implementation generates **JVM hidden classes** at registration time.
+ * Each hidden class wraps a `MethodHandle` as a `static final` constant, enabling the JIT
+ * compiler to constant-fold and inline the dispatch target. This provides near-direct-call
+ * performance while retaining the flexibility of reflection-based handler discovery.
  *
  * ## Lifecycle
  * The owning [RedisApi] initializes the bus during [RedisApi.connect] via [init] and closes it during

surf-redis-core/src/main/java/dev/slne/surf/redis/invoker/InvokerUtils.java

@@ -0,0 +1,29 @@
+package dev.slne.surf.redis.invoker;
+
+/**
+ * Internal utility class providing helper methods for the invoker infrastructure.
+ *
+ * <p>This class is package-private and not intended for external use.
+ */
+final class InvokerUtils {
+    private InvokerUtils() {
+    }
+
+    /**
+     * Re-throws the given {@link Throwable} without requiring a checked exception declaration.
+     *
+     * <p>This leverages Java's type-erasure: the unchecked cast tricks the compiler into
+     * treating any {@code Throwable} as an unchecked exception. This is used by the hidden
+     * class templates to propagate exceptions from {@code MethodHandle.invokeExact()} calls
+     * without wrapping them.
+     *
+     * @param <T> inferred as {@link RuntimeException} by the compiler, but actually the
+     *            original throwable type at runtime
+     * @param t   the throwable to re-throw
+     * @throws T always (the original throwable, unwrapped)
+     */
+    @SuppressWarnings("unchecked")
+    static <T extends Throwable> void sneakyThrow(final Throwable t) throws T {
+        throw (T) t;
+    }
+}

surf-redis-core/src/main/java/dev/slne/surf/redis/invoker/RedisEventInvokerFactory.java

@@ -0,0 +1,116 @@
+package dev.slne.surf.redis.invoker;
+
+import dev.slne.surf.redis.event.RedisEvent;
+import dev.slne.surf.redis.event.RedisEventInvoker;
+import org.jspecify.annotations.NullMarked;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.lang.invoke.MethodHandles;
+import java.lang.invoke.MethodType;
+import java.lang.reflect.Method;
+import java.util.Objects;
+
+/**
+ * Factory for creating {@link RedisEventInvoker} instances backed by JVM hidden classes.
+ *
+ * <p>This factory reads the bytecode of {@link RedisEventInvokerTemplate} at class-load time
+ * and uses it as a template for
+ * {@link MethodHandles.Lookup#defineHiddenClassWithClassData(byte[], Object, boolean, MethodHandles.Lookup.ClassOption...)}
+ * calls. Each invocation of {@link #create(Object, Method, Class)} produces a new hidden class
+ * instance whose {@code static final} fields (MethodHandle, Method, event class) are initialized
+ * from the supplied class data.
+ *
+ * <h2>Why hidden classes?</h2>
+ * <p>Raw {@link java.lang.invoke.MethodHandle#invoke(Object...)} goes through a polymorphic
+ * signature that the JIT cannot inline across. By embedding the {@code MethodHandle} as a
+ * {@code static final} constant in a hidden class, the JIT treats the target as a compile-time
+ * constant and can inline the entire dispatch chain.
+ *
+ * <h2>Thread safety</h2>
+ * <p>This class is stateless after initialization and safe for concurrent use.
+ * The template bytecode is loaded once in a static initializer.
+ *
+ * @see RedisEventInvoker
+ * @see RedisEventInvokerTemplate
+ * @see RedisHiddenInvokerUtil
+ */
+@NullMarked
+public final class RedisEventInvokerFactory {
+
+    /** Pre-loaded bytecode of {@link RedisEventInvokerTemplate} used as the hidden class template. */
+    private static final byte[] TEMPLATE_CLASS_BYTES;
+
+    /** Lookup used for defining hidden classes. */
+    private static final MethodHandles.Lookup LOOKUP = MethodHandles.lookup();
+
+    static {
+        try (final InputStream is = RedisEventInvokerFactory.class.getResourceAsStream(RedisEventInvokerTemplate.class.getSimpleName() + ".class")) {
+            Objects.requireNonNull(is, "RedisEventInvokerTemplate.class not found");
+            TEMPLATE_CLASS_BYTES = is.readAllBytes();
+        } catch (IOException e) {
+            throw new AssertionError("Failed to load RedisEventInvokerTemplate.class", e);
+        }
+    }
+
+    private RedisEventInvokerFactory() {
+        throw new UnsupportedOperationException("RedisEventInvokerFactory is a utility class and cannot be instantiated");
+    }
+
+    /**
+     * Checks whether a hidden class invoker can be created for the given listener and method.
+     * Validates that privateLookupIn succeeds and the method can be unreflected.
+     *
+     * @return true if {@link #create} will succeed, false if the module does not open the package
+     */
+    public static boolean canAccess(final Object listener, final Method method) {
+        try {
+            MethodHandles.privateLookupIn(listener.getClass(), LOOKUP).unreflect(method);
+            return true;
+        } catch (IllegalAccessException e) {
+            return false;
+        }
+    }
+
+    /**
+     * Creates a new {@link RedisEventInvoker} for the given listener and handler method.
+     *
+     * <p>A new hidden class is defined from the pre-loaded template bytecode. The hidden class
+     * receives the listener instance, event class, method, and a private lookup as class data.
+     * Its static initializer resolves these into a bound {@code MethodHandle} stored as a
+     * {@code static final} field.
+     *
+     * @param listener        the listener object that owns the handler method
+     * @param method          the handler method annotated with {@code @OnRedisEvent}
+     * @param redisEventClass the concrete {@link RedisEvent} subclass accepted by the handler
+     * @return a hidden-class-backed invoker ready for dispatch
+     * @throws AssertionError if hidden class creation fails
+     */
+    public static RedisEventInvoker create(final Object listener, final Method method, final Class<? extends RedisEvent> redisEventClass) {
+        try {
+            return RedisHiddenInvokerUtil.createInvoker(LOOKUP, TEMPLATE_CLASS_BYTES, RedisEventInvoker.class, listener, method, redisEventClass);
+        } catch (ReflectiveOperationException e) {
+            throw new AssertionError("Failed to create RedisEventInvoker for " + method, e);
+        }
+    }
+
+    /**
+     * Loads and assembles the class data for a hidden event invoker class.
+     *
+     * <p>This method is called from the static initializer of the hidden class
+     * (via {@link RedisEventInvokerTemplate}) to extract the class data that was
+     * passed during {@link MethodHandles.Lookup#defineHiddenClassWithClassData}.
+     *
+     * @param lookup the lookup of the hidden class requesting its class data
+     * @return a {@link RedisHiddenInvokerUtil.ClassData} containing the resolved MethodHandle,
+     *         the original Method, and the event payload class
+     * @throws AssertionError if class data retrieval or MethodHandle resolution fails
+     */
+    static RedisHiddenInvokerUtil.ClassData<RedisEvent> classData(MethodHandles.Lookup lookup) {
+        try {
+            return RedisHiddenInvokerUtil.loadClassData(lookup, MethodType.methodType(void.class, RedisEvent.class), RedisEvent.class);
+        } catch (ReflectiveOperationException e) {
+            throw new AssertionError("Failed to retrieve class data for RedisEventInvoker", e);
+        }
+    }
+}

surf-redis-core/src/main/java/dev/slne/surf/redis/invoker/RedisEventInvokerTemplate.java

@@ -0,0 +1,59 @@
+package dev.slne.surf.redis.invoker;
+
+import dev.slne.surf.redis.event.RedisEvent;
+import dev.slne.surf.redis.event.RedisEventInvoker;
+import org.jetbrains.annotations.NotNull;
+
+import java.lang.invoke.MethodHandle;
+import java.lang.invoke.MethodHandles;
+import java.lang.reflect.Method;
+
+/**
+ * Hidden class template for Redis event handler invocation.
+ *
+ * <p>This class is designed to be used with
+ * {@link MethodHandles.Lookup#defineHiddenClassWithClassData(byte[], Object, boolean, MethodHandles.Lookup.ClassOption...)}.
+ * Initializing it directly will fail due to missing {@code classData}.
+ *
+ * <p>The {@code classData} must be a {@link java.util.List} containing:
+ * <ol>
+ *     <li>The listener instance ({@link Object})</li>
+ *     <li>The Redis event class ({@link Class})</li>
+ *     <li>The handler {@link Method}</li>
+ *     <li>A {@link MethodHandles.Lookup} with access to the listener's class (via {@code privateLookupIn})</li>
+ * </ol>
+ *
+ * <p>The MethodHandle is resolved in the static initializer and stored as a
+ * {@code static final} field, allowing the JIT compiler to treat it as a
+ * compile-time constant and fully inline the call.
+ */
+final class RedisEventInvokerTemplate implements RedisEventInvoker {
+    private static final Method METHOD;
+    private static final MethodHandle HANDLE;
+    private static final Class<? extends RedisEvent> REDIS_EVENT_CLASS;
+
+    static {
+        final MethodHandles.Lookup lookup = MethodHandles.lookup();
+        final RedisHiddenInvokerUtil.ClassData<RedisEvent> classData = RedisEventInvokerFactory.classData(lookup);
+
+        METHOD = classData.method();
+        HANDLE = classData.methodHandle();
+        REDIS_EVENT_CLASS = classData.payloadClass();
+    }
+
+
+    @Override
+    public void invoke(@NotNull RedisEvent event) {
+        if (!REDIS_EVENT_CLASS.isInstance(event)) return;
+        try {
+            HANDLE.invokeExact(event);
+        } catch (Throwable t) {
+            InvokerUtils.sneakyThrow(t);
+        }
+    }
+
+    @Override
+    public String toString() {
+        return "RedisEventInvokerTemplate{" + METHOD + "}";
+    }
+}

surf-redis-core/src/main/java/dev/slne/surf/redis/invoker/RedisHiddenInvokerUtil.java

@@ -0,0 +1,109 @@
+package dev.slne.surf.redis.invoker;
+
+import org.jspecify.annotations.NullMarked;
+
+import java.lang.constant.ConstantDescs;
+import java.lang.invoke.MethodHandle;
+import java.lang.invoke.MethodHandles;
+import java.lang.invoke.MethodType;
+import java.lang.reflect.Method;
+import java.util.List;
+
+/**
+ * Shared utility for creating and initializing hidden class–based invokers.
+ *
+ * <p>This class encapsulates the low-level JVM hidden class machinery used by
+ * {@link RedisEventInvokerFactory} and {@link RedisRequestHandlerInvokerFactory}.
+ *
+ * <h2>Hidden class lifecycle</h2>
+ * <ol>
+ *   <li>{@link #createInvoker} packs the target instance, payload class, method, and a private
+ *       lookup into a {@link List} and passes it as class data to
+ *       {@link MethodHandles.Lookup#defineHiddenClassWithClassData(byte[], Object, boolean, MethodHandles.Lookup.ClassOption...)}.</li>
+ *   <li>The hidden class's static initializer calls back to the factory's {@code classData()} method,
+ *       which delegates to {@link #loadClassData} to unpack the class data.</li>
+ *   <li>{@link #loadClassData} extracts the individual components via
+ *       {@link MethodHandles#classDataAt}, resolves the method into a bound {@link MethodHandle},
+ *       and returns them as a {@link ClassData} record.</li>
+ * </ol>
+ *
+ * <p>This class is package-private and not intended for external use.
+ */
+@NullMarked
+final class RedisHiddenInvokerUtil {
+
+    private RedisHiddenInvokerUtil() {
+        throw new UnsupportedOperationException();
+    }
+
+    /**
+     * Defines a new hidden class from the given template bytecode and returns a new instance
+     * of the specified invoker interface.
+     *
+     * <p>The class data passed to the hidden class consists of:
+     * <ol>
+     *   <li>The target handler/listener instance</li>
+     *   <li>The payload class (event or request type)</li>
+     *   <li>The handler {@link Method}</li>
+     *   <li>A {@link MethodHandles.Lookup} with private access to the target's class</li>
+     * </ol>
+     *
+     * @param <I>              the invoker interface type (e.g. {@code RedisEventInvoker})
+     * @param lookup           the lookup used to define the hidden class
+     * @param templateBytes    the bytecode of the template class
+     * @param invokerInterface the interface the hidden class implements
+     * @param target           the handler/listener instance to bind the MethodHandle to
+     * @param method           the handler method to invoke
+     * @param payloadClass     the concrete event or request class the handler accepts
+     * @return a new instance of the hidden class, cast to {@code I}
+     * @throws ReflectiveOperationException if hidden class definition or instantiation fails
+     */
+    static <I> I createInvoker(MethodHandles.Lookup lookup, byte[] templateBytes, Class<I> invokerInterface, Object target, Method method, Class<?> payloadClass) throws ReflectiveOperationException {
+        final MethodHandles.Lookup privateLookupIn = MethodHandles.privateLookupIn(target.getClass(), lookup);
+        final List<Object> classData = List.of(target, payloadClass, method, privateLookupIn);
+        final MethodHandles.Lookup hiddenClassLookup = lookup.defineHiddenClassWithClassData(templateBytes, classData, true);
+
+        return hiddenClassLookup.lookupClass()
+                .asSubclass(invokerInterface)
+                .getDeclaredConstructor()
+                .newInstance();
+    }
+
+    /**
+     * Immutable carrier for the resolved class data of a hidden invoker class.
+     *
+     * @param <P>          the payload supertype ({@link dev.slne.surf.redis.event.RedisEvent}
+     *                     or {@link dev.slne.surf.redis.request.RedisRequest})
+     * @param method       the original handler method
+     * @param methodHandle the resolved and bound {@link MethodHandle} for the handler
+     * @param payloadClass the concrete payload class the handler accepts
+     */
+    record ClassData<P>(Method method, MethodHandle methodHandle, Class<? extends P> payloadClass) {
+    }
+
+    /**
+     * Extracts and resolves the class data that was passed to
+     * {@link MethodHandles.Lookup#defineHiddenClassWithClassData}.
+     *
+     * <p>This method is called from within the static initializer of the hidden class to
+     * unpack the target, payload class, method, and private lookup. The method is then
+     * unreflected and bound to the target, producing a type-erased {@link MethodHandle}
+     * matching the given {@code methodType}.
+     *
+     * @param <P>              the payload supertype
+     * @param lookup           the hidden class's own lookup (provides access to its class data)
+     * @param methodType       the expected method type for the resolved MethodHandle
+     * @param payloadSuperType the expected supertype of the payload class
+     * @return a {@link ClassData} record containing the method, bound handle, and payload class
+     * @throws ReflectiveOperationException if class data extraction or handle resolution fails
+     */
+    static <P> ClassData<P> loadClassData(MethodHandles.Lookup lookup, MethodType methodType, Class<P> payloadSuperType) throws ReflectiveOperationException {
+        final Object target = MethodHandles.classDataAt(lookup, ConstantDescs.DEFAULT_NAME, Object.class, 0);
+        final Class<?> payload = MethodHandles.classDataAt(lookup, ConstantDescs.DEFAULT_NAME, Class.class, 1);
+        final Method method = MethodHandles.classDataAt(lookup, ConstantDescs.DEFAULT_NAME, Method.class, 2);
+        final MethodHandles.Lookup privateLookupIn = MethodHandles.classDataAt(lookup, ConstantDescs.DEFAULT_NAME, MethodHandles.Lookup.class, 3);
+
+        final MethodHandle handle = privateLookupIn.unreflect(method).bindTo(target).asType(methodType);
+        return new ClassData<P>(method, handle, payload.asSubclass(payloadSuperType));
+    }
+}