feat: add session lock request, acquire, release events (#24498)

caalador · web-flow · commit 0e5c8ed1a46b · 2026-06-03T10:00:41.000Z
Enable listening to session lock request/acquire/release
diff --git a/flow-server/src/main/java/com/vaadin/flow/server/InstrumentedReentrantLock.java b/flow-server/src/main/java/com/vaadin/flow/server/InstrumentedReentrantLock.java
@@ -0,0 +1,114 @@
+/*
+ * Copyright 2000-2026 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.vaadin.flow.server;
+
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.locks.ReentrantLock;
+
+/**
+ * {@link ReentrantLock} used for Vaadin session locking that notifies the
+ * owning {@link VaadinService}'s {@link SessionLockListener}s around the
+ * outermost lock acquisition and release.
+ * <p>
+ * Both the request-handling lock path
+ * ({@link VaadinService#lockSession(WrappedSession)}) and
+ * {@link VaadinSession#lock()} / {@link VaadinSession#unlock()} (used by
+ * {@link com.vaadin.flow.component.UI#access(Command)}) operate on the same
+ * lock instance, so instrumenting the lock captures every acquisition exactly
+ * once at the true acquire/release moment.
+ * <p>
+ * Only the outermost acquisition is reported: reentrant re-locks
+ * ({@link #getHoldCount()} {@code > 0}) acquire without waiting and are not
+ * signalled. The reference to the service is {@code transient}; after session
+ * passivation/activation it behaves as a plain {@link ReentrantLock} until a
+ * fresh instance is created.
+ * <p>
+ * Every acquisition path is instrumented so events stay balanced regardless of
+ * how the lock was taken: {@link #lock()} and {@link #lockInterruptibly()}
+ * block and so report {@code lockRequested} before the attempt to capture the
+ * real wait time, while the non-blocking {@link #tryLock()} /
+ * {@link #tryLock(long, TimeUnit)} report {@code lockRequested} and
+ * {@code lockAcquired} together only on a successful outermost acquisition
+ * (their wait time is effectively zero). This matters because
+ * {@link VaadinService#ensureAccessQueuePurged(VaadinSession)} acquires the
+ * lock with {@code tryLock} and then {@link #unlock() unlocks}; instrumenting
+ * only {@code lock()} would leave that path firing {@code lockReleased} with no
+ * matching acquire.
+ */
+class InstrumentedReentrantLock extends ReentrantLock {
+
+    private final transient VaadinService service;
+
+    InstrumentedReentrantLock(VaadinService service) {
+        this.service = service;
+    }
+
+    @Override
+    public void lock() {
+        boolean outermost = getHoldCount() == 0;
+        if (outermost && service != null) {
+            service.fireSessionLockRequested();
+        }
+        super.lock();
+        if (outermost && service != null) {
+            service.fireSessionLockAcquired();
+        }
+    }
+
+    @Override
+    public void lockInterruptibly() throws InterruptedException {
+        boolean outermost = getHoldCount() == 0;
+        // Report after a confirmed acquisition: lockInterruptibly may abort
+        // with InterruptedException without taking the lock.
+        super.lockInterruptibly();
+        if (outermost && service != null) {
+            service.fireSessionLockRequested();
+            service.fireSessionLockAcquired();
+        }
+    }
+
+    @Override
+    public boolean tryLock() {
+        boolean outermost = getHoldCount() == 0;
+        boolean acquired = super.tryLock();
+        if (outermost && acquired && service != null) {
+            service.fireSessionLockRequested();
+            service.fireSessionLockAcquired();
+        }
+        return acquired;
+    }
+
+    @Override
+    public boolean tryLock(long timeout, TimeUnit unit)
+            throws InterruptedException {
+        boolean outermost = getHoldCount() == 0;
+        boolean acquired = super.tryLock(timeout, unit);
+        if (outermost && acquired && service != null) {
+            service.fireSessionLockRequested();
+            service.fireSessionLockAcquired();
+        }
+        return acquired;
+    }
+
+    @Override
+    public void unlock() {
+        boolean ultimateRelease = getHoldCount() == 1;
+        super.unlock();
+        if (ultimateRelease && service != null) {
+            service.fireSessionLockReleased();
+        }
+    }
+}
diff --git a/flow-server/src/main/java/com/vaadin/flow/server/SessionLockEvent.java b/flow-server/src/main/java/com/vaadin/flow/server/SessionLockEvent.java
@@ -0,0 +1,65 @@
+/*
+ * Copyright 2000-2026 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.vaadin.flow.server;
+
+import java.util.EventObject;
+
+/**
+ * Event fired to {@link SessionLockListener}s around acquisition and release of
+ * a Vaadin session lock.
+ * <p>
+ * The same lock instance protects a session whether it is acquired by the
+ * framework while handling a request or via {@link VaadinSession#lock()} (for
+ * example from {@link com.vaadin.flow.component.UI#access(Command)}). A
+ * listener receives {@link SessionLockListener#lockRequested},
+ * {@link SessionLockListener#lockAcquired} and
+ * {@link SessionLockListener#lockReleased} on the same thread for a given
+ * outermost lock-hold, so timing state can be kept in a thread local.
+ *
+ * @see SessionLockListener
+ */
+public class SessionLockEvent extends EventObject {
+
+    /**
+     * Creates a new session lock event.
+     *
+     * @param service
+     *            the Vaadin service whose session lock is being acquired or
+     *            released, not {@code null}
+     */
+    public SessionLockEvent(VaadinService service) {
+        super(service);
+    }
+
+    /**
+     * Gets the Vaadin service from which this event originates.
+     *
+     * @return the Vaadin service instance
+     */
+    @Override
+    public VaadinService getSource() {
+        return (VaadinService) super.getSource();
+    }
+
+    /**
+     * Gets the Vaadin service from which this event originates.
+     *
+     * @return the Vaadin service instance
+     */
+    public VaadinService getService() {
+        return getSource();
+    }
+}
diff --git a/flow-server/src/main/java/com/vaadin/flow/server/SessionLockListener.java b/flow-server/src/main/java/com/vaadin/flow/server/SessionLockListener.java
@@ -0,0 +1,92 @@
+/*
+ * Copyright 2000-2026 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.vaadin.flow.server;
+
+import java.io.Serializable;
+
+/**
+ * Listener that is notified when a Vaadin session lock is acquired and
+ * released, enabling observation of session-lock contention (for example to
+ * publish lock wait and hold-time metrics).
+ * <p>
+ * All Vaadin server-side work for a single session is serialized behind one
+ * lock, so the time a thread blocks acquiring it and the time it holds it are
+ * key performance signals. Callbacks are delivered for the <em>outermost</em>
+ * acquisition only (reentrant re-locks are not reported), and the three
+ * callbacks for a single hold are delivered on the same thread in the order
+ * {@link #lockRequested}, {@link #lockAcquired}, {@link #lockReleased}, so a
+ * listener can record the start time in a {@link ThreadLocal} on
+ * {@code lockRequested}, derive the wait time on {@code lockAcquired}, and the
+ * hold time on {@code lockReleased}.
+ * <p>
+ * When several listeners are registered, {@link #lockRequested} and
+ * {@link #lockAcquired} are delivered in registration order while
+ * {@link #lockReleased} is delivered in reverse registration order, so the
+ * callbacks nest like {@code try}/{@code finally} blocks: a listener registered
+ * later sees its {@code lockReleased} run before that of a listener registered
+ * earlier.
+ * <p>
+ * Implementations must be fast and non-blocking: callbacks run on the
+ * request/access thread directly around the lock operation. Exceptions thrown
+ * from a callback are logged and suppressed so they cannot disrupt session
+ * locking.
+ * <p>
+ * Register via
+ * {@link VaadinService#addSessionLockListener(SessionLockListener)}, typically
+ * from a {@link VaadinServiceInitListener}. Listeners registered after a
+ * session's lock has already been created are still honoured.
+ *
+ * @see VaadinService#addSessionLockListener(SessionLockListener)
+ * @see SessionLockEvent
+ */
+public interface SessionLockListener extends Serializable {
+
+    /**
+     * Invoked on the locking thread immediately before it attempts to acquire
+     * the session lock for an outermost (non-reentrant) acquisition. The thread
+     * may block between this callback and {@link #lockAcquired}; the elapsed
+     * time is the lock wait time. For a non-blocking acquisition
+     * ({@code tryLock}) this is delivered together with {@link #lockAcquired}
+     * only when the lock was actually taken, so the reported wait time is
+     * effectively zero.
+     *
+     * @param event
+     *            the session lock event
+     */
+    default void lockRequested(SessionLockEvent event) {
+    }
+
+    /**
+     * Invoked on the locking thread immediately after it has acquired the
+     * session lock for an outermost acquisition.
+     *
+     * @param event
+     *            the session lock event
+     */
+    default void lockAcquired(SessionLockEvent event) {
+    }
+
+    /**
+     * Invoked on the locking thread immediately after the outermost lock hold
+     * has been released (the lock's hold count reached zero). The time since
+     * {@link #lockAcquired} is the lock hold time.
+     *
+     * @param event
+     *            the session lock event
+     */
+    default void lockReleased(SessionLockEvent event) {
+    }
+}
diff --git a/flow-server/src/main/java/com/vaadin/flow/server/VaadinService.java b/flow-server/src/main/java/com/vaadin/flow/server/VaadinService.java
@@ -32,6 +32,7 @@
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
+import java.util.ListIterator;
 import java.util.Locale;
 import java.util.Map;
 import java.util.Map.Entry;
@@ -159,6 +160,7 @@ public abstract class VaadinService implements Serializable {
     private final List<SessionInitListener> sessionInitListeners = new CopyOnWriteArrayList<>();
     private final List<UIInitListener> uiInitListeners = new CopyOnWriteArrayList<>();
     private final List<SessionDestroyListener> sessionDestroyListeners = new CopyOnWriteArrayList<>();
+    private final List<SessionLockListener> sessionLockListeners = new CopyOnWriteArrayList<>();
 
     private SystemMessagesProvider systemMessagesProvider = DefaultSystemMessagesProvider
             .get();
@@ -813,6 +815,79 @@ public Registration addUIInitListener(UIInitListener listener) {
         return Registration.addAndRemove(uiInitListeners, listener);
     }
 
+    /**
+     * Adds a listener that gets notified when a session lock for this service
+     * is acquired and released, enabling observation of session-lock contention
+     * (for example to publish lock wait and hold-time metrics).
+     * <p>
+     * Register typically from a {@link VaadinServiceInitListener}. Listeners
+     * are notified for the outermost lock acquisition only; see
+     * {@link SessionLockListener} for the callback contract.
+     *
+     * @param listener
+     *            the session lock listener
+     * @return a handle that can be used for removing the listener
+     * @see SessionLockListener
+     */
+    public Registration addSessionLockListener(SessionLockListener listener) {
+        return Registration.addAndRemove(sessionLockListeners, listener);
+    }
+
+    boolean hasSessionLockListeners() {
+        return !sessionLockListeners.isEmpty();
+    }
+
+    void fireSessionLockRequested() {
+        if (sessionLockListeners.isEmpty()) {
+            return;
+        }
+        SessionLockEvent event = new SessionLockEvent(this);
+        for (SessionLockListener listener : sessionLockListeners) {
+            try {
+                listener.lockRequested(event);
+            } catch (RuntimeException e) {
+                getLogger().error("Error in SessionLockListener.lockRequested",
+                        e);
+            }
+        }
+    }
+
+    void fireSessionLockAcquired() {
+        if (sessionLockListeners.isEmpty()) {
+            return;
+        }
+        SessionLockEvent event = new SessionLockEvent(this);
+        for (SessionLockListener listener : sessionLockListeners) {
+            try {
+                listener.lockAcquired(event);
+            } catch (RuntimeException e) {
+                getLogger().error("Error in SessionLockListener.lockAcquired",
+                        e);
+            }
+        }
+    }
+
+    void fireSessionLockReleased() {
+        if (sessionLockListeners.isEmpty()) {
+            return;
+        }
+        SessionLockEvent event = new SessionLockEvent(this);
+        // Released is fired in reverse registration order so that listeners
+        // are nested: a listener's lockReleased runs before the lockReleased
+        // of the listeners that were notified before it on lockAcquired.
+        ListIterator<SessionLockListener> listeners = sessionLockListeners
+                .listIterator(sessionLockListeners.size());
+        while (listeners.hasPrevious()) {
+            SessionLockListener listener = listeners.previous();
+            try {
+                listener.lockReleased(event);
+            } catch (RuntimeException e) {
+                getLogger().error("Error in SessionLockListener.lockReleased",
+                        e);
+            }
+        }
+    }
+
     /**
      * Adds a listener that gets notified when a Vaadin service session that has
      * been initialized for this service is destroyed.
@@ -1027,7 +1102,7 @@ protected Lock lockSession(WrappedSession wrappedSession) {
             synchronized (VaadinService.class) {
                 lock = getSessionLock(wrappedSession);
                 if (lock == null) {
-                    lock = new ReentrantLock();
+                    lock = new InstrumentedReentrantLock(this);
                     setSessionLock(wrappedSession, lock);
                 }
             }
diff --git a/flow-server/src/test/java/com/vaadin/flow/server/SessionLockListenerTest.java b/flow-server/src/test/java/com/vaadin/flow/server/SessionLockListenerTest.java
