From d41660809d53b1679a6dd697e07679da5e543f4f Mon Sep 17 00:00:00 2001 From: Jochen Wiedmann Date: Fri, 26 Jun 2020 11:51:06 +0200 Subject: [PATCH] Adding Javadocs for the Locks.Lock class. Improvements in the test suite. --- .../commons/lang3/concurrent/Locks.java | 178 +++++++++++++++++- .../commons/lang3/concurrent/LocksTest.java | 37 ++++ 2 files changed, 213 insertions(+), 2 deletions(-) diff --git a/src/main/java/org/apache/commons/lang3/concurrent/Locks.java b/src/main/java/org/apache/commons/lang3/concurrent/Locks.java index 28df9c095..48e16eb8d 100644 --- a/src/main/java/org/apache/commons/lang3/concurrent/Locks.java +++ b/src/main/java/org/apache/commons/lang3/concurrent/Locks.java @@ -70,31 +70,174 @@ import org.apache.commons.lang3.function.FailableFunction; */ public class Locks { + /** + * This class implements a wrapper for a locked (hidden) object, and + * provides the means to access it. The basic idea, is that the user + * code forsakes all references to the locked object, using only the + * wrapper object, and the accessor methods + * {@link #acceptReadLocked(FailableConsumer)}, + * {@link #acceptWriteLocked(FailableConsumer)}, + * {@link #applyReadLocked(FailableFunction)}, and + * {@link #applyWriteLocked(FailableFunction)}. By doing so, the + * necessary protections are guaranteed. + * @param The locked (hidden) objects type. + * + * @since 3.11 + */ public static class Lock { - private final StampedLock lock = new StampedLock(); private final O lockedObject; + /** + * Creates a new instance with the given locked object. This + * constructor is supposed to be used for subclassing only. + * In general, it is suggested to use {@link Locks#lock(Object)} + * instead. + * @param lockedObject The locked (hidden) object. The caller is + * supposed to drop all references to the locked object. + */ public Lock(final O lockedObject) { this.lockedObject = Objects.requireNonNull(lockedObject, "Locked Object"); } + /** + * Provides read (shared, non-exclusive) access to the locked (hidden) object. + * More precisely, what the method will do (in the given order): + *
    + *
  1. Obtain a read (shared) lock on the locked (hidden) object. + * The current thread may block, until such a lock is granted. + *
    2. + *
  2. Invokes the given {@link FailableConsumer consumer}, passing the + * locked object as the parameter.
    3. + *
  3. Release the lock, as soon as the consumers invocation is done. + * If the invocation results in an error, the lock will be released + * anyways. + *
    4. + *
+ * @param consumer The consumer, which is being invoked to use the + * hidden object, which will be passed as the consumers parameter. + * @see #acceptWriteLocked(FailableConsumer) + * @see #applyReadLocked(FailableFunction) + */ public void acceptReadLocked(final FailableConsumer consumer) { lockAcceptUnlock(() -> lock.readLock(), consumer); } + /** + * Provides write (exclusive) access to the locked (hidden) object. + * More precisely, what the method will do (in the given order): + *
    + *
  1. Obtain a write (shared) lock on the locked (hidden) object. + * The current thread may block, until such a lock is granted. + *
    2. + *
  2. Invokes the given {@link FailableConsumer consumer}, passing the + * locked object as the parameter.
    3. + *
  3. Release the lock, as soon as the consumers invocation is done. + * If the invocation results in an error, the lock will be released + * anyways. + *
    4. + *
+ * @param consumer The consumer, which is being invoked to use the + * hidden object, which will be passed as the consumers parameter. + * @see #acceptReadLocked(FailableConsumer) + * @see #applyWriteLocked(FailableFunction) + */ public void acceptWriteLocked(final FailableConsumer consumer) { lockAcceptUnlock(() -> lock.writeLock(), consumer); } + /** + * Provides read (shared, non-exclusive) access to the locked (hidden) + * object for the purpose of computing a result object. + * More precisely, what the method will do (in the given order): + *
    + *
  1. Obtain a read (shared) lock on the locked (hidden) object. + * The current thread may block, until such a lock is granted. + *
    2. + *
  2. Invokes the given {@link FailableFunction function}, passing the + * locked object as the parameter, receiving the functions result.
    3. + *
  3. Release the lock, as soon as the consumers invocation is done. + * If the invocation results in an error, the lock will be released + * anyways. + *
    4. + *
  4. + * Return the result object, that has been received from the + * functions invocation.
    5. + *
+ * + * Example: Suggest, that the hidden object is a list, and we + * wish to know the current size of the list. This might be achieved + * with the following: + * + * 
+         *   private Lock<List<Object>> listLock;
+         *
+         *   public int getCurrentListSize() {
+         *       final Integer sizeInteger
+         *           = listLock.applyReadLocked((list) -> Integer.valueOf(list.size));
+         *       return sizeInteger.intValue();
+         *   }
+         *
+ * @param The result type (both the functions, and this method's.) + * @param function The function, which is being invoked to compute the + * result. The function will receive the hidden object. + * @return The result object, which has been returned by the + * functions invocation. + * @throws IllegalStateException The result object would be, in fact, + * the hidden object. This would extend access to the hidden object + * beyond this methods lifetime and will therefore be prevented. + * @see #acceptReadLocked(FailableConsumer) + * @see #applyWriteLocked(FailableFunction) + */ public T applyReadLocked(final FailableFunction function) { return lockApplyUnlock(() -> lock.readLock(), function); } + /** + * Provides write (exclusive) access to the locked (hidden) + * object for the purpose of computing a result object. + * More precisely, what the method will do (in the given order): + *
    + *
  1. Obtain a read (shared) lock on the locked (hidden) object. + * The current thread may block, until such a lock is granted. + *
    2. + *
  2. Invokes the given {@link FailableFunction function}, passing the + * locked object as the parameter, receiving the functions result.
    3. + *
  3. Release the lock, as soon as the consumers invocation is done. + * If the invocation results in an error, the lock will be released + * anyways. + *
    4. + *
  4. + * Return the result object, that has been received from the + * functions invocation.
    5. + *
+ * @param The result type (both the functions, and this method's.) + * @param function The function, which is being invoked to compute the + * result. The function will receive the hidden object. + * @return The result object, which has been returned by the + * functions invocation. + * @throws IllegalStateException The result object would be, in fact, + * the hidden object. This would extend access to the hidden object + * beyond this methods lifetime and will therefore be prevented. + * @see #acceptReadLocked(FailableConsumer) + * @see #applyWriteLocked(FailableFunction) + */ public T applyWriteLocked(final FailableFunction function) { return lockApplyUnlock(() -> lock.writeLock(), function); } + /** + * This method provides the actual implementation for + * {@link #acceptReadLocked(FailableConsumer)}, and + * {@link #acceptWriteLocked(FailableConsumer)}. + * @param stampSupplier A supplier for the lock. (This provides, in + * fact, a long, because a {@link StampedLock} is used internally.) + * @param consumer The consumer, which is to be given access to the + * locked (hidden) object, which will be passed as a parameter. + * @see #acceptReadLocked(FailableConsumer) + * @see #acceptWriteLocked(FailableConsumer) + * @see #lockApplyUnlock(LongSupplier, FailableFunction) + */ protected void lockAcceptUnlock(final LongSupplier stampSupplier, final FailableConsumer consumer) { final long stamp = stampSupplier.getAsLong(); try { @@ -106,10 +249,33 @@ public class Locks { } } + /** + * This method provides the actual implementation for + * {@link #applyReadLocked(FailableFunction)}, and + * {@link #applyWriteLocked(FailableFunction)}. + * @param The result type (both the functions, and this method's.) + * @param stampSupplier A supplier for the lock. (This provides, in + * fact, a long, because a {@link StampedLock} is used internally.) + * @param function The function, which is being invoked to compute + * the result object. This function will receive the locked (hidden) + * object as a parameter. + * @return The result object, which has been returned by the + * functions invocation. + * @throws IllegalStateException The result object would be, in fact, + * the hidden object. This would extend access to the hidden object + * beyond this methods lifetime and will therefore be prevented. + * @see #applyReadLocked(FailableFunction) + * @see #applyWriteLocked(FailableFunction) + * @see #lockAcceptUnlock(LongSupplier, FailableConsumer) + */ protected T lockApplyUnlock(final LongSupplier stampSupplier, final FailableFunction function) { final long stamp = stampSupplier.getAsLong(); try { - return function.apply(lockedObject); + final T t = function.apply(lockedObject); + if (t == lockedObject) { + throw new IllegalStateException("The returned object is, in fact, the hidden object."); + } + return t; } catch (final Throwable t) { throw Failable.rethrow(t); } finally { @@ -118,6 +284,14 @@ public class Locks { } } + /** + * Creates a new instance of {@link Lock} with the given locked + * (hidden) object. + * @param The locked objects type. + * @param object The locked (hidden) object. + * @return The created instance, a {@link Lock lock} for the + * given object. + */ public static Locks.Lock lock(final O object) { return new Locks.Lock<>(object); } diff --git a/src/test/java/org/apache/commons/lang3/concurrent/LocksTest.java b/src/test/java/org/apache/commons/lang3/concurrent/LocksTest.java index 2d577ecdb..706281ec9 100644 --- a/src/test/java/org/apache/commons/lang3/concurrent/LocksTest.java +++ b/src/test/java/org/apache/commons/lang3/concurrent/LocksTest.java @@ -16,7 +16,11 @@ */ package org.apache.commons.lang3.concurrent; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNotSame; import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.junit.jupiter.api.Assertions.fail; import java.util.function.LongConsumer; @@ -36,6 +40,7 @@ public class LocksTest { runTest(DELAY, false, l -> assertTrue(l < NUMBER_OF_THREADS*DELAY)); } + @Test public void testWriteLock() throws Exception { final long DELAY = 100; /** If our threads are running concurrently, then we expect to be no faster @@ -44,6 +49,38 @@ public class LocksTest { runTest(DELAY, true, l -> assertTrue(l >= NUMBER_OF_THREADS*DELAY)); } + @Test + public void testResultValidation() { + final Object hidden = new Object(); + final Lock lock = Locks.lock(hidden); + final Object o1 = lock.applyReadLocked((h) -> { + return new Object(); + }); + assertNotNull(o1); + assertNotSame(hidden, o1); + final Object o2 = lock.applyWriteLocked((h) -> { + return new Object(); + }); + assertNotNull(o2); + assertNotSame(hidden, o2); + try { + lock.applyReadLocked((h) -> { + return hidden; + }); + fail("Expected Exception"); + } catch (IllegalStateException e) { + assertEquals("The returned object is, in fact, the hidden object.", e.getMessage()); + } + try { + lock.applyReadLocked((h) -> { + return hidden; + }); + fail("Expected Exception"); + } catch (IllegalStateException e) { + assertEquals("The returned object is, in fact, the hidden object.", e.getMessage()); + } + } + private void runTest(final long delay, final boolean exclusiveLock, final LongConsumer runTimeCheck) throws InterruptedException { final boolean[] booleanValues = new boolean[10]; final Lock lock = Locks.lock(booleanValues);