From c141bc961cb5cb84c47a21c3a5b0f15ab0035728 Mon Sep 17 00:00:00 2001 From: Jochen Wiedmann Date: Thu, 28 May 2020 22:52:46 +0200 Subject: [PATCH] Adding the Locks class. --- src/changes/changes.xml | 5 +- .../java/org/apache/commons/lang3/Locks.java | 116 ++++++++++++++++++ .../org/apache/commons/lang3/LocksTest.java | 73 +++++++++++ 3 files changed, 192 insertions(+), 2 deletions(-) create mode 100644 src/main/java/org/apache/commons/lang3/Locks.java create mode 100644 src/test/java/org/apache/commons/lang3/LocksTest.java diff --git a/src/changes/changes.xml b/src/changes/changes.xml index 1df43f20b..2204f329f 100644 --- a/src/changes/changes.xml +++ b/src/changes/changes.xml @@ -46,7 +46,7 @@ The type attribute can be add,update,fix,remove. - Fix Javdoc for StringUtils.appendIfMissingIgnoreCase() #507. + Fix Javadoc for StringUtils.appendIfMissingIgnoreCase() #507. org.junit-pioneer:junit-pioneer 0.5.4 -> 0.6.0. org.junit.jupiter:junit-jupiter 5.6.0 -> 5.6.1. com.github.spotbugs:spotbugs 4.0.0 -> 4.0.3. @@ -59,6 +59,7 @@ The type attribute can be add,update,fix,remove. (Javadoc) Fix return tag for throwableOf*() methods #518. Add ArrayUtils.isSameLength() to compare more array types #430. CharSequenceUtils.regionMatches is wrong dealing with Georgian. + Added the Locks class as a convenient possibility to deal with locked objects. @@ -275,7 +276,7 @@ The type attribute can be add,update,fix,remove. Enhance MethodUtils to allow invocation of private methods Fix implementation of StringUtils.getJaroWinklerDistance() Fix dead links in StringUtils.getLevenshteinDistance() javadoc - "\u2284":"⊄" mapping missing from EntityArrays#HTML40_EXTENDED_ESCAPE + "\u2284":"nsub" mapping missing from EntityArrays#HTML40_EXTENDED_ESCAPE Simplify ArrayUtils removeElements by using new decrementAndGet() method Add getAndIncrement/getAndDecrement/getAndAdd/incrementAndGet/decrementAndGet/addAndGet in Mutable* classes Optimize BitField constructor implementation diff --git a/src/main/java/org/apache/commons/lang3/Locks.java b/src/main/java/org/apache/commons/lang3/Locks.java new file mode 100644 index 000000000..60b4f6aa1 --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/Locks.java @@ -0,0 +1,116 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 org.apache.commons.lang3; + +import java.util.Objects; +import java.util.concurrent.locks.StampedLock; + +import org.apache.commons.lang3.Functions.FailableConsumer; +import org.apache.commons.lang3.Functions.FailableFunction; + + +/** Utility class for working with {@link java.util.concurrent.locks.Lock locked objects}. Locked objects are an + * alternative to synchronization. + * + * Locking is preferable, if there is a distinction between read access (multiple threads may have read + * access concurrently), and write access (only one thread may have write access at any given time. + * In comparison, synchronization doesn't support read access, because synchronized access is exclusive. + * + * Using this class is fairly straightforward: + *
    + *
  1. While still in single thread mode, create an instance of {@link Locks.Lock} by calling + * {@link #lock(Object)}, passing the object, which needs to be locked. Discard all + * references to the locked object. Instead, use references to the lock.
    2. + *
  2. If you want to access the locked object, create a {@link FailableConsumer}. The consumer + * will receive the locked object as a parameter. For convenience, the consumer may be + * implemented as a Lamba. Then invoke {@link Locks.Lock#runReadLocked(FailableConsumer)}, + * or {@link Locks.Lock#runWriteLocked(FailableConsumer)}, passing the consumer.
    3. + *
  3. As an alternative, if you need to produce a result object, you may use a + * {@link FailableFunction}. This function may also be implemented as a Lambda. To + * have the function executed, invoke {@link Locks.Lock#callReadLocked(FailableFunction)}, or + * {@link Locks.Lock#callWriteLocked(FailableFunction)}.
    4. + *
+ * + * Example: A thread safe logger class. + * 
+ *   public class SimpleLogger {
+ *     private final Lock<PrintStream> lock;
+ *
+ *     public SimpleLogger(OutputStream out) {
+ *         PrintStream ps = new Printstream(out);
+ *         lock = Locks.lock(ps);
+ *     }
+ * 
+ *     public void log(String message) {
+ *         lock.runWriteLocked((ps) -> ps.println(message));
+ *     }
+ *
+ *     public void log(byte[] buffer) {
+ *         lock.runWriteLocked((ps) -> { ps.write(buffer); ps.println(); });
+ *     }
+ *
+ */ +public class Locks { + public static class Lock { + private final O lockedObject; + private final StampedLock lock = new StampedLock(); + + public Lock(O lockedObject) { + this.lockedObject = Objects.requireNonNull(lockedObject, "Locked Object"); + } + + public void runReadLocked(FailableConsumer consumer) { + runLocked(lock.readLock(), consumer); + } + + public void runWriteLocked(FailableConsumer consumer) { + runLocked(lock.writeLock(), consumer); + } + + public T callReadLocked(FailableFunction function) { + return callLocked(lock.readLock(), function); + } + + public T callWriteLocked(FailableFunction function) { + return callLocked(lock.writeLock(), function); + } + + protected void runLocked(long stamp, FailableConsumer consumer) { + try { + consumer.accept(lockedObject); + } catch (Throwable t) { + throw Functions.rethrow(t); + } finally { + lock.unlock(stamp); + } + } + + protected T callLocked(long stamp, FailableFunction function) { + try { + return function.apply(lockedObject); + } catch (Throwable t) { + throw Functions.rethrow(t); + } finally { + lock.unlock(stamp); + } + } + } + + public static Locks.Lock lock(O object) { + return new Locks.Lock(object); + } +} diff --git a/src/test/java/org/apache/commons/lang3/LocksTest.java b/src/test/java/org/apache/commons/lang3/LocksTest.java new file mode 100644 index 000000000..e2dd6b0b8 --- /dev/null +++ b/src/test/java/org/apache/commons/lang3/LocksTest.java @@ -0,0 +1,73 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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 org.apache.commons.lang3; + +import static org.junit.jupiter.api.Assertions.*; + +import org.apache.commons.lang3.Functions.FailableConsumer; +import org.apache.commons.lang3.Locks.Lock; +import org.junit.jupiter.api.Test; + +class LocksTest { + @Test + void testReadLock() throws Exception { + final long DELAY=3000; + final boolean[] booleanValues = new boolean[10]; + final Lock lock = Locks.lock(booleanValues); + final boolean[] runningValues = new boolean[10]; + + final long startTime = System.currentTimeMillis(); + for (int i = 0; i < booleanValues.length; i++) { + final int index = i; + final FailableConsumer consumer = (b) -> { + b[index] = false; + Thread.sleep(DELAY); + b[index] = true; + modify(runningValues, index, false); + }; + final Thread t = new Thread(() -> lock.runReadLocked(consumer)); + modify(runningValues, i, true); + t.start(); + } + while (someValueIsTrue(runningValues)) { + Thread.sleep(100); + } + final long endTime = System.currentTimeMillis(); + for (int i = 0; i < booleanValues.length; i++) { + assertTrue(booleanValues[i]); + } + // If our threads would be running in exclusive mode, then we'd need + // at least DELAY milliseconds for each. + assertTrue((endTime-startTime) < booleanValues.length*DELAY); + } + + protected void modify(boolean[] booleanArray, int offset, boolean value) { + synchronized(booleanArray) { + booleanArray[offset] = value; + } + } + protected boolean someValueIsTrue(boolean[] booleanArray) { + synchronized(booleanArray) { + for (int i = 0; i < booleanArray.length; i++) { + if (booleanArray[i]) { + return true; + } + } + return false; + } + } +}