View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      https://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.lang3.concurrent.locks;
18  
19  import static org.junit.jupiter.api.Assertions.assertEquals;
20  import static org.junit.jupiter.api.Assertions.assertFalse;
21  import static org.junit.jupiter.api.Assertions.assertNotNull;
22  import static org.junit.jupiter.api.Assertions.assertNotSame;
23  import static org.junit.jupiter.api.Assertions.assertSame;
24  import static org.junit.jupiter.api.Assertions.assertThrows;
25  import static org.junit.jupiter.api.Assertions.assertTrue;
26  
27  import java.util.ArrayList;
28  import java.util.List;
29  import java.util.concurrent.CountDownLatch;
30  import java.util.concurrent.ExecutorService;
31  import java.util.concurrent.Executors;
32  import java.util.concurrent.Future;
33  import java.util.concurrent.TimeUnit;
34  import java.util.concurrent.atomic.AtomicInteger;
35  import java.util.concurrent.locks.Lock;
36  import java.util.concurrent.locks.ReadWriteLock;
37  import java.util.concurrent.locks.ReentrantLock;
38  import java.util.concurrent.locks.ReentrantReadWriteLock;
39  import java.util.concurrent.locks.StampedLock;
40  
41  import org.apache.commons.lang3.AbstractLangTest;
42  import org.apache.commons.lang3.concurrent.locks.LockingVisitors.LockVisitor;
43  import org.apache.commons.lang3.concurrent.locks.LockingVisitors.ReadWriteLockVisitor;
44  import org.apache.commons.lang3.concurrent.locks.LockingVisitors.ReentrantLockVisitor;
45  import org.apache.commons.lang3.concurrent.locks.LockingVisitors.StampedLockVisitor;
46  import org.apache.commons.lang3.function.FailableConsumer;
47  import org.junit.jupiter.api.Test;
48  import org.junit.jupiter.params.ParameterizedTest;
49  import org.junit.jupiter.params.provider.ValueSource;
50  
51  /**
52   * Tests {@link LockingVisitors}.
53   */
54  class LockingVisitorsTest extends AbstractLangTest {
55  
56      private static final int NUMBER_OF_THREADS = 10;
57  
58      private static boolean tryLock(final Lock lock) {
59          if (!lock.tryLock()) {
60              return false;
61          }
62          lock.unlock();
63          return true;
64      }
65  
66      private <T> void assertConcurrentReaders(final LockVisitor<T, ?> visitor, final ExecutorService executor) throws Exception {
67          final CountDownLatch entered = new CountDownLatch(NUMBER_OF_THREADS);
68          final CountDownLatch release = new CountDownLatch(1);
69          final List<Future<?>> readers = new ArrayList<>();
70          try {
71              for (int i = 0; i < NUMBER_OF_THREADS; i++) {
72                  readers.add(executor.submit(() -> visitor.acceptReadLocked(values -> {
73                      entered.countDown();
74                      assertTrue(release.await(10, TimeUnit.SECONDS), "Readers released");
75                  })));
76              }
77              // All callbacks must enter before any callback is allowed to leave.
78              assertTrue(entered.await(10, TimeUnit.SECONDS), "Read callbacks run concurrently");
79          } finally {
80              release.countDown();
81          }
82          for (final Future<?> reader : readers) {
83              reader.get(10, TimeUnit.SECONDS);
84          }
85      }
86  
87      private <T> void invoke(final LockVisitor<T, ?> visitor, final boolean write, final boolean apply,
88              final FailableConsumer<T, Exception> consumer) {
89          if (apply) {
90              final T result;
91              if (write) {
92                  result = visitor.applyWriteLocked(values -> {
93                      consumer.accept(values);
94                      return values;
95                  });
96              } else {
97                  result = visitor.applyReadLocked(values -> {
98                      consumer.accept(values);
99                      return values;
100                 });
101             }
102             assertSame(visitor.getObject(), result);
103         } else if (write) {
104             visitor.acceptWriteLocked(consumer);
105         } else {
106             visitor.acceptReadLocked(consumer);
107         }
108     }
109 
110     private <T> void runTest(final boolean write, final boolean exclusive, final LockVisitor<T, ?> visitor,
111             final Lock readLock, final Lock writeLock) throws Exception {
112         assertNotNull(visitor.getLock());
113         assertNotNull(visitor.getObject());
114         final ExecutorService executor = Executors.newFixedThreadPool(NUMBER_OF_THREADS);
115         try {
116             for (final boolean apply : new boolean[] { false, true }) {
117                 for (final boolean fail : new boolean[] { false, true }) {
118                     final AtomicInteger calls = new AtomicInteger();
119                     final IllegalStateException failure = new IllegalStateException("Callback failure");
120                     final FailableConsumer<T, Exception> consumer = values -> {
121                         assertSame(visitor.getObject(), values);
122                         calls.incrementAndGet();
123                         // A single other thread probes both locks, so probes cannot mask a missing visitor lock.
124                         executor.submit(() -> {
125                             assertEquals(!exclusive, tryLock(readLock), "Read access during the callback");
126                             assertFalse(tryLock(writeLock), "Write access during the callback");
127                         }).get(10, TimeUnit.SECONDS);
128                         if (fail) {
129                             throw failure;
130                         }
131                     };
132                     if (fail) {
133                         assertSame(failure, assertThrows(IllegalStateException.class, () -> invoke(visitor, write, apply, consumer)));
134                     } else {
135                         invoke(visitor, write, apply, consumer);
136                     }
137                     assertEquals(1, calls.get(), "Callback invoked exactly once");
138                     // Probe after both successful and failing callbacks, from a thread that does not own the lock.
139                     executor.submit(() -> {
140                         assertTrue(tryLock(readLock), "Read lock released after the callback");
141                         assertTrue(tryLock(writeLock), "Write lock released after the callback");
142                     }).get(10, TimeUnit.SECONDS);
143                 }
144             }
145             if (!exclusive) {
146                 assertConcurrentReaders(visitor, executor);
147             }
148         } finally {
149             executor.shutdownNow();
150             assertTrue(executor.awaitTermination(10, TimeUnit.SECONDS));
151         }
152     }
153 
154     @ParameterizedTest
155     @ValueSource(booleans = { true, false })
156     void testBuilderLockVisitor(final boolean fair) throws Exception {
157         final AtomicInteger obj = new AtomicInteger();
158         final ReadWriteLock lock = new ReentrantReadWriteLock(fair);
159         // @formatter:off
160         final LockVisitor<AtomicInteger, ReadWriteLock> lockVisitor = new LockVisitor.LVBuilder()
161           .setObject(obj)
162           .setLock(lock)
163           .setReadLockSupplier(lock::readLock)
164           .setWriteLockSupplier(lock::writeLock)
165           .get();
166         // @formatter:on
167         lockVisitor.acceptReadLocked(AtomicInteger::incrementAndGet);
168         assertEquals(1, obj.get());
169         lockVisitor.acceptReadLocked(AtomicInteger::incrementAndGet);
170         assertEquals(2, obj.get());
171         runTest(false, false, lockVisitor, lock.readLock(), lock.writeLock());
172         runTest(true, true, lockVisitor, lock.readLock(), lock.writeLock());
173     }
174 
175     @ParameterizedTest
176     @ValueSource(booleans = { true, false })
177     void testBuilderReadWriteLockVisitor(final boolean fair) throws Exception {
178         final AtomicInteger obj = new AtomicInteger();
179         final ReadWriteLock lock = new ReentrantReadWriteLock(fair);
180         // @formatter:off
181         final LockingVisitors.ReadWriteLockVisitor<AtomicInteger> lockVisitor = ReadWriteLockVisitor.<AtomicInteger>builder()
182           .setObject(obj)
183           .setLock(lock)
184           .get();
185         // @formatter:on
186         lockVisitor.acceptReadLocked(AtomicInteger::incrementAndGet);
187         assertEquals(1, obj.get());
188         lockVisitor.acceptReadLocked(AtomicInteger::incrementAndGet);
189         assertEquals(2, obj.get());
190         runTest(false, false, lockVisitor, lock.readLock(), lock.writeLock());
191         runTest(true, true, lockVisitor, lock.readLock(), lock.writeLock());
192     }
193 
194     @ParameterizedTest
195     @ValueSource(booleans = { true, false })
196     void testBuilderReentrantLockVisitor(final boolean fair) throws Exception {
197         final AtomicInteger obj = new AtomicInteger();
198         final ReentrantLock lock = new ReentrantLock(fair);
199         // @formatter:off
200         final LockingVisitors.ReentrantLockVisitor<AtomicInteger> lockVisitor = ReentrantLockVisitor.<AtomicInteger>builder()
201           .setObject(obj)
202           .setLock(lock)
203           .get();
204         // @formatter:on
205         lockVisitor.acceptReadLocked(AtomicInteger::incrementAndGet);
206         assertEquals(1, obj.get());
207         lockVisitor.acceptReadLocked(AtomicInteger::incrementAndGet);
208         assertEquals(2, obj.get());
209         runTest(false, true, lockVisitor, lock, lock);
210         runTest(true, true, lockVisitor, lock, lock);
211     }
212 
213     @ParameterizedTest
214     @ValueSource(booleans = { true, false })
215     void testBuilderReentrantReadWriteLockVisitor(final boolean fair) throws Exception {
216         final AtomicInteger obj = new AtomicInteger();
217         final ReentrantReadWriteLock lock = new ReentrantReadWriteLock(fair);
218         // @formatter:off
219         final LockingVisitors.ReadWriteLockVisitor<AtomicInteger> lockVisitor = ReadWriteLockVisitor.<AtomicInteger>builder()
220           .setObject(obj)
221           .setLock(lock)
222           .get();
223         // @formatter:on
224         lockVisitor.acceptReadLocked(AtomicInteger::incrementAndGet);
225         assertEquals(1, obj.get());
226         lockVisitor.acceptReadLocked(AtomicInteger::incrementAndGet);
227         assertEquals(2, obj.get());
228         runTest(false, false, lockVisitor, lock.readLock(), lock.writeLock());
229         runTest(true, true, lockVisitor, lock.readLock(), lock.writeLock());
230     }
231 
232     @Test
233     void testBuilderReentrantStampedLockVisitor() throws Exception {
234         final AtomicInteger obj = new AtomicInteger();
235         final StampedLock lock = new StampedLock();
236         // @formatter:off
237         final LockingVisitors.StampedLockVisitor<AtomicInteger> lockVisitor = StampedLockVisitor.<AtomicInteger>builder()
238           .setObject(obj)
239           .setLock(lock)
240           .get();
241         // @formatter:on
242         lockVisitor.acceptReadLocked(AtomicInteger::incrementAndGet);
243         assertEquals(1, obj.get());
244         lockVisitor.acceptReadLocked(AtomicInteger::incrementAndGet);
245         assertEquals(2, obj.get());
246         runTest(false, false, lockVisitor, lock.asReadLock(), lock.asWriteLock());
247         runTest(true, true, lockVisitor, lock.asReadLock(), lock.asWriteLock());
248     }
249 
250     @Test
251     void testCreate() {
252         final AtomicInteger obj = new AtomicInteger();
253         final ReadWriteLock lock = new ReentrantReadWriteLock();
254         LockingVisitors.create(obj, lock).acceptReadLocked(AtomicInteger::incrementAndGet);
255         LockingVisitors.create(obj, lock).acceptReadLocked(null);
256         assertEquals(1, obj.get());
257         LockingVisitors.create(obj, lock).acceptWriteLocked(AtomicInteger::incrementAndGet);
258         LockingVisitors.create(obj, lock).acceptWriteLocked(null);
259         assertEquals(2, obj.get());
260     }
261 
262     @SuppressWarnings("deprecation")
263     @Test
264     void testDeprecatedConstructor() {
265         assertNotNull(new LockingVisitors().toString());
266     }
267 
268     @Test
269     void testReentrantLock() throws Exception {
270         final boolean[] values = new boolean[NUMBER_OF_THREADS];
271         final ReentrantLockVisitor<boolean[]> visitor = LockingVisitors.reentrantLockVisitor(values);
272         assertSame(values, visitor.getObject());
273         runTest(false, true, visitor, visitor.getLock(), visitor.getLock());
274         runTest(true, true, visitor, visitor.getLock(), visitor.getLock());
275     }
276 
277     @ParameterizedTest
278     @ValueSource(booleans = { true, false })
279     void testReentrantLockFairness(final boolean fairness) throws Exception {
280         final boolean[] values = new boolean[NUMBER_OF_THREADS];
281         final ReentrantLock lock = new ReentrantLock(fairness);
282         final ReentrantLockVisitor<boolean[]> visitor = LockingVisitors.create(values, lock);
283         assertSame(values, visitor.getObject());
284         runTest(false, true, visitor, lock, lock);
285         runTest(true, true, visitor, lock, lock);
286     }
287 
288     @Test
289     void testReentrantReadWriteLockExclusive() throws Exception {
290         final boolean[] values = new boolean[NUMBER_OF_THREADS];
291         final ReadWriteLockVisitor<boolean[]> visitor = LockingVisitors.reentrantReadWriteLockVisitor(values);
292         assertSame(values, visitor.getObject());
293         runTest(true, true, visitor, visitor.getLock().readLock(), visitor.getLock().writeLock());
294     }
295 
296     @Test
297     void testReentrantReadWriteLockNotExclusive() throws Exception {
298         final boolean[] values = new boolean[NUMBER_OF_THREADS];
299         final ReadWriteLockVisitor<boolean[]> visitor = LockingVisitors.reentrantReadWriteLockVisitor(values);
300         assertSame(values, visitor.getObject());
301         runTest(false, false, visitor, visitor.getLock().readLock(), visitor.getLock().writeLock());
302     }
303 
304     @Test
305     void testResultValidation() {
306         final Object hidden = new Object();
307         final StampedLockVisitor<Object> lock = LockingVisitors.stampedLockVisitor(hidden);
308         final Object o1 = lock.applyReadLocked(h -> new Object());
309         assertNotNull(o1);
310         assertNotSame(hidden, o1);
311         final Object o2 = lock.applyWriteLocked(h -> new Object());
312         assertNotNull(o2);
313         assertNotSame(hidden, o2);
314     }
315 
316     @Test
317     void testStampedLockExclusive() throws Exception {
318         final boolean[] values = new boolean[NUMBER_OF_THREADS];
319         final StampedLockVisitor<boolean[]> visitor = LockingVisitors.stampedLockVisitor(values);
320         assertSame(values, visitor.getObject());
321         runTest(true, true, visitor, visitor.getLock().asReadLock(), visitor.getLock().asWriteLock());
322     }
323 
324     @Test
325     void testStampedLockNotExclusive() throws Exception {
326         final boolean[] values = new boolean[NUMBER_OF_THREADS];
327         final StampedLockVisitor<boolean[]> visitor = LockingVisitors.stampedLockVisitor(values);
328         assertSame(values, visitor.getObject());
329         runTest(false, false, visitor, visitor.getLock().asReadLock(), visitor.getLock().asWriteLock());
330     }
331 }