feat: add AbstractLockableStateful

state-core/src/main/java/org/incendo/state/AbstractLockableStateful.java

@@ -0,0 +1,95 @@
+//
+// MIT License
+//
+// Copyright (c) 2024 Incendo
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+//
+package org.incendo.state;
+
+import java.util.concurrent.locks.Lock;
+import java.util.concurrent.locks.ReentrantReadWriteLock;
+import org.apiguardian.api.API;
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.common.returnsreceiver.qual.This;
+
+/**
+ * Implementation of {@link AbstractStateful} which can be locked using a {@link ReentrantReadWriteLock}.
+ *
+ * @param <U> state type
+ * @param <V> self-referencing type
+ * @since 1.0.0
+ */
+@API(status = API.Status.STABLE, since = "1.0.0")
+public abstract class AbstractLockableStateful<U extends State<U>, V extends AbstractLockableStateful<U, V>>
+        extends AbstractStateful<U, V> {
+
+    private final ReentrantReadWriteLock lock = new ReentrantReadWriteLock();
+    private final Lock readLock = this.lock.readLock();
+    private final Lock writeLock = this.lock.writeLock();
+
+    /**
+     * Creates a new instance.
+     *
+     * @param initialState initial state
+     */
+    protected AbstractLockableStateful(final @NonNull U initialState) {
+        super(initialState);
+    }
+
+    @Override
+    public @This @NonNull V transition(final @NonNull U currentState, final @NonNull U newState) throws UnexpectedStateException,
+            IllegalStateTransitionException {
+        this.writeLock.lock();
+        try {
+            return super.transition(currentState, newState);
+        } finally {
+            this.writeLock.unlock();
+        }
+    }
+
+    @Override
+    public synchronized @This @NonNull V transitionTo(final @NonNull U state) throws IllegalStateTransitionException {
+        this.writeLock.lock();
+        try {
+            return super.transitionTo(state);
+        } finally {
+            this.writeLock.unlock();
+        }
+    }
+
+    @Override
+    public @NonNull U state() {
+        this.readLock.lock();
+        try {
+            return super.state();
+        } finally {
+            this.readLock.unlock();
+        }
+    }
+
+    /**
+     * Returns the lock.
+     *
+     * @return the lock
+     */
+    @NonNull ReentrantReadWriteLock lock() {
+        return this.lock;
+    }
+}

state-core/src/main/java/org/incendo/state/AbstractStateful.java

@@ -34,6 +34,7 @@
  * @param <U> state type
  * @param <V> self-referencing type
  * @since 1.0.0
+ * @see AbstractLockableStateful
  */
 @API(status = API.Status.STABLE, since = "1.0.0")
 public abstract class AbstractStateful<U extends State<U>, V extends AbstractStateful<U, V>> implements MutableStateful<U, V> {
@@ -50,13 +51,13 @@ protected AbstractStateful(final @NonNull U initialState) {
     }
 
     @Override
-    public final synchronized @NonNull U state() {
+    public synchronized @NonNull U state() {
         return this.state;
     }
 
     @Override
     @SuppressWarnings("unchecked")
-    public final synchronized @This @NonNull V transitionTo(final @NonNull U state) throws IllegalStateTransitionException {
+    public synchronized @This @NonNull V transitionTo(final @NonNull U state) throws IllegalStateTransitionException {
         Objects.requireNonNull(state, "state");
         if (!this.canTransitionTo(state)) {
             throw new IllegalStateTransitionException(this.state, state, this);
@@ -66,7 +67,7 @@ protected AbstractStateful(final @NonNull U initialState) {
     }
 
     @Override
-    public final synchronized @This @NonNull V transition(final @NonNull U currentState, final @NonNull U newState)
+    public synchronized @This @NonNull V transition(final @NonNull U currentState, final @NonNull U newState)
             throws UnexpectedStateException, IllegalStateTransitionException {
         Objects.requireNonNull(currentState, "currentState");
         if (!this.state.equals(currentState)) {

state-core/src/main/java/org/incendo/state/LazyStates.java

@@ -46,12 +46,12 @@ final class LazyStates<S extends State<S>> implements States<S> {
     }
 
     @Override
-    public boolean contains(@NonNull final S state) {
+    public boolean contains(final @NonNull S state) {
         return this.backingStates().contains(state);
     }
 
     @Override
-    public @NonNull States<S> withState(@NonNull final S state) {
+    public @NonNull States<S> withState(final @NonNull S state) {
         return this.backingStates().withState(state);
     }
 }

state-core/src/main/java/org/incendo/state/StateInteractionImpl.java

@@ -23,6 +23,7 @@
 //
 package org.incendo.state;
 
+import java.util.concurrent.locks.Lock;
 import java.util.function.Function;
 import org.apiguardian.api.API;
 import org.checkerframework.checker.nullness.qual.NonNull;
@@ -38,22 +39,39 @@ record StateInteractionImpl<U extends State<U>, V extends Stateful<U, V>>(
 
     @Override
     public @NonNull V execute() {
-        final U currentState = this.instance.state();
-        if (!this.incomingStates.contains(currentState)) {
-            throw new UnexpectedStateException(this.incomingStates, currentState, this.instance);
+        final Lock lock;
+        if (this.instance instanceof AbstractLockableStateful<?, ?> lockableStateful) {
+            lock = lockableStateful.lock().writeLock();
+        } else {
+            lock = null;
         }
 
-        if (this.shortcircuitStates.contains(currentState)) {
-            return this.instance;
+        if (lock != null) {
+            lock.lock();
         }
 
-        final V result = this.interaction.apply(this.instance);
+        try {
+            final U currentState = this.instance.state();
+            if (!this.incomingStates.contains(currentState)) {
+                throw new UnexpectedStateException(this.incomingStates, currentState, this.instance);
+            }
 
-        final U newState = result.state();
-        if (!this.outgoingStates.contains(newState)) {
-            throw new UnexpectedStateException(this.outgoingStates, newState, result);
-        }
+            if (this.shortcircuitStates.contains(currentState)) {
+                return this.instance;
+            }
+
+            final V result = this.interaction.apply(this.instance);
 
-        return result;
+            final U newState = result.state();
+            if (!this.outgoingStates.contains(newState)) {
+                throw new UnexpectedStateException(this.outgoingStates, newState, result);
+            }
+
+            return result;
+        } finally {
+            if (lock != null) {
+                lock.unlock();
+            }
+        }
     }
 }

state-core/src/main/java/org/incendo/state/StatefulImpl.java

@@ -27,7 +27,7 @@
 import org.checkerframework.checker.nullness.qual.NonNull;
 
 @API(status = API.Status.INTERNAL, since = "1.0.0")
-final class StatefulImpl<S extends State<S>> extends AbstractStateful<S, StatefulImpl<S>> {
+final class StatefulImpl<S extends State<S>> extends AbstractLockableStateful<S, StatefulImpl<S>> {
 
     StatefulImpl(final @NonNull S initialState) {
         super(initialState);

state-core/src/test/java/org/incendo/state/IntegrationTest.java

@@ -103,7 +103,7 @@ enum TestState implements State<TestState> {
         }
     }
 
-    static final class TestObject extends AbstractStateful<TestState, TestObject> {
+    static final class TestObject extends AbstractLockableStateful<TestState, TestObject> {
 
         private int fooCounter = 0;