LockingVisitors.java

  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.  *      http://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;

  19. import java.util.Objects;
  20. import java.util.concurrent.locks.Lock;
  21. import java.util.concurrent.locks.ReadWriteLock;
  22. import java.util.concurrent.locks.ReentrantReadWriteLock;
  23. import java.util.concurrent.locks.StampedLock;
  24. import java.util.function.Supplier;

  26. import org.apache.commons.lang3.function.Failable;
  27. import org.apache.commons.lang3.function.FailableConsumer;
  28. import org.apache.commons.lang3.function.FailableFunction;
  29. import org.apache.commons.lang3.function.Suppliers;

  31. /**
  32.  * Combines the monitor and visitor pattern to work with {@link java.util.concurrent.locks.Lock locked objects}. Locked
  33.  * objects are an alternative to synchronization. This, on Wikipedia, is known as the Visitor pattern
  34.  * (https://en.wikipedia.org/wiki/Visitor_pattern), and from the "Gang of Four" "Design Patterns" book's Visitor pattern
  35.  * [Gamma, E., Helm, R., & Johnson, R. (1998). Visitor. In Design patterns elements of reusable object oriented software (pp. 331-344). Reading: Addison Wesley.].
  36.  *
  37.  * <p>
  38.  * Locking is preferable, if there is a distinction between read access (multiple threads may have read access
  39.  * concurrently), and write access (only one thread may have write access at any given time). In comparison,
  40.  * synchronization doesn't support read access, because synchronized access is exclusive.
  41.  * </p>
  42.  * <p>
  43.  * Using this class is fairly straightforward:
  44.  * </p>
  45.  * <ol>
  46.  * <li>While still in single thread mode, create an instance of {@link LockingVisitors.StampedLockVisitor} by calling
  47.  * {@link #stampedLockVisitor(Object)}, passing the object which needs to be locked. Discard all references to the
  48.  * locked object. Instead, use references to the lock.</li>
  49.  * <li>If you want to access the locked object, create a {@link FailableConsumer}. The consumer will receive the locked
  50.  * object as a parameter. For convenience, the consumer may be implemented as a Lambda. Then invoke
  51.  * {@link LockingVisitors.StampedLockVisitor#acceptReadLocked(FailableConsumer)}, or
  52.  * {@link LockingVisitors.StampedLockVisitor#acceptWriteLocked(FailableConsumer)}, passing the consumer.</li>
  53.  * <li>As an alternative, if you need to produce a result object, you may use a {@link FailableFunction}. This function
  54.  * may also be implemented as a Lambda. To have the function executed, invoke
  55.  * {@link LockingVisitors.StampedLockVisitor#applyReadLocked(FailableFunction)}, or
  56.  * {@link LockingVisitors.StampedLockVisitor#applyWriteLocked(FailableFunction)}.</li>
  57.  * </ol>
  58.  * <p>
  59.  * Example: A thread safe logger class.
  60.  * </p>
  61.  *
  62.  * <pre>{@code
  63.  *   public class SimpleLogger {
  64.  *
  65.  *     private final StampedLockVisitor<PrintStream> lock;
  66.  *
  67.  *     public SimpleLogger(OutputStream out) {
  68.  *         lock = LockingVisitors.stampedLockVisitor(new PrintStream(out));
  69.  *     }
  70.  *
  71.  *     public void log(String message) {
  72.  *         lock.acceptWriteLocked(ps -> ps.println(message));
  73.  *     }
  74.  *
  75.  *     public void log(byte[] buffer) {
  76.  *         lock.acceptWriteLocked(ps -> { ps.write(buffer); ps.println(); });
  77.  *     }
  78.  * }
  79.  * }
  80.  * </pre>
  81.  *
  82.  * @since 3.11
  83.  */
  84. public class LockingVisitors {

  86.     /**
  87.      * Wraps a domain object and a lock for access by lambdas.
  88.      *
  89.      * @param <O> the wrapped object type.
  90.      * @param <L> the wrapped lock type.
  91.      */
  92.     public static class LockVisitor<O, L> {

  94.         /**
  95.          * The lock object, untyped, since, for example {@link StampedLock} does not implement a locking interface in
  96.          * Java 8.
  97.          */
  98.         private final L lock;

  100.         /**
  101.          * The guarded object.
  102.          */
  103.         private final O object;

  105.         /**
  106.          * Supplies the read lock, usually from the lock object.
  107.          */
  108.         private final Supplier<Lock> readLockSupplier;

  110.         /**
  111.          * Supplies the write lock, usually from the lock object.
  112.          */
  113.         private final Supplier<Lock> writeLockSupplier;

  115.         /**
  116.          * Constructs an instance.
  117.          *
  118.          * @param object The object to guard.
  119.          * @param lock The locking object.
  120.          * @param readLockSupplier Supplies the read lock, usually from the lock object.
  121.          * @param writeLockSupplier Supplies the write lock, usually from the lock object.
  122.          */
  123.         protected LockVisitor(final O object, final L lock, final Supplier<Lock> readLockSupplier, final Supplier<Lock> writeLockSupplier) {
  124.             this.object = Objects.requireNonNull(object, "object");
  125.             this.lock = Objects.requireNonNull(lock, "lock");
  126.             this.readLockSupplier = Objects.requireNonNull(readLockSupplier, "readLockSupplier");
  127.             this.writeLockSupplier = Objects.requireNonNull(writeLockSupplier, "writeLockSupplier");
  128.         }

  130.         /**
  131.          * Provides read (shared, non-exclusive) access to the locked (hidden) object. More precisely, what the method
  132.          * will do (in the given order):
  133.          *
  134.          * <ol>
  135.          * <li>Obtain a read (shared) lock on the locked (hidden) object. The current thread may block, until such a
  136.          * lock is granted.</li>
  137.          * <li>Invokes the given {@link FailableConsumer consumer}, passing the locked object as the parameter.</li>
  138.          * <li>Release the lock, as soon as the consumers invocation is done. If the invocation results in an error, the
  139.          * lock will be released anyways.</li>
  140.          * </ol>
  141.          *
  142.          * @param consumer The consumer, which is being invoked to use the hidden object, which will be passed as the
  143.          *        consumers parameter.
  144.          * @see #acceptWriteLocked(FailableConsumer)
  145.          * @see #applyReadLocked(FailableFunction)
  146.          */
  147.         public void acceptReadLocked(final FailableConsumer<O, ?> consumer) {
  148.             lockAcceptUnlock(readLockSupplier, consumer);
  149.         }

  151.         /**
  152.          * Provides write (exclusive) access to the locked (hidden) object. More precisely, what the method will do (in
  153.          * the given order):
  154.          *
  155.          * <ol>
  156.          * <li>Obtain a write (shared) lock on the locked (hidden) object. The current thread may block, until such a
  157.          * lock is granted.</li>
  158.          * <li>Invokes the given {@link FailableConsumer consumer}, passing the locked object as the parameter.</li>
  159.          * <li>Release the lock, as soon as the consumers invocation is done. If the invocation results in an error, the
  160.          * lock will be released anyways.</li>
  161.          * </ol>
  162.          *
  163.          * @param consumer The consumer, which is being invoked to use the hidden object, which will be passed as the
  164.          *        consumers parameter.
  165.          * @see #acceptReadLocked(FailableConsumer)
  166.          * @see #applyWriteLocked(FailableFunction)
  167.          */
  168.         public void acceptWriteLocked(final FailableConsumer<O, ?> consumer) {
  169.             lockAcceptUnlock(writeLockSupplier, consumer);
  170.         }

  172.         /**
  173.          * Provides read (shared, non-exclusive) access to the locked (hidden) object for the purpose of computing a
  174.          * result object. More precisely, what the method will do (in the given order):
  175.          *
  176.          * <ol>
  177.          * <li>Obtain a read (shared) lock on the locked (hidden) object. The current thread may block, until such a
  178.          * lock is granted.</li>
  179.          * <li>Invokes the given {@link FailableFunction function}, passing the locked object as the parameter,
  180.          * receiving the functions result.</li>
  181.          * <li>Release the lock, as soon as the consumers invocation is done. If the invocation results in an error, the
  182.          * lock will be released anyways.</li>
  183.          * <li>Return the result object, that has been received from the functions invocation.</li>
  184.          * </ol>
  185.          * <p>
  186.          * <em>Example:</em> Consider that the hidden object is a list, and we wish to know the current size of the
  187.          * list. This might be achieved with the following:
  188.          * </p>
  189.          * <pre>{@code
  190.          * private Lock<List<Object>> listLock;
  191.          *
  192.          * public int getCurrentListSize() {
  193.          *     final Integer sizeInteger = listLock.applyReadLocked(list -> Integer.valueOf(list.size));
  194.          *     return sizeInteger.intValue();
  195.          * }
  196.          * }
  197.          * </pre>
  198.          *
  199.          * @param <T> The result type (both the functions, and this method's.)
  200.          * @param function The function, which is being invoked to compute the result. The function will receive the
  201.          *        hidden object.
  202.          * @return The result object, which has been returned by the functions invocation.
  203.          * @throws IllegalStateException The result object would be, in fact, the hidden object. This would extend
  204.          *         access to the hidden object beyond this methods lifetime and will therefore be prevented.
  205.          * @see #acceptReadLocked(FailableConsumer)
  206.          * @see #applyWriteLocked(FailableFunction)
  207.          */
  208.         public <T> T applyReadLocked(final FailableFunction<O, T, ?> function) {
  209.             return lockApplyUnlock(readLockSupplier, function);
  210.         }

  212.         /**
  213.          * Provides write (exclusive) access to the locked (hidden) object for the purpose of computing a result object.
  214.          * More precisely, what the method will do (in the given order):
  215.          *
  216.          * <ol>
  217.          * <li>Obtain a read (shared) lock on the locked (hidden) object. The current thread may block, until such a
  218.          * lock is granted.</li>
  219.          * <li>Invokes the given {@link FailableFunction function}, passing the locked object as the parameter,
  220.          * receiving the functions result.</li>
  221.          * <li>Release the lock, as soon as the consumers invocation is done. If the invocation results in an error, the
  222.          * lock will be released anyways.</li>
  223.          * <li>Return the result object, that has been received from the functions invocation.</li>
  224.          * </ol>
  225.          *
  226.          * @param <T> The result type (both the functions, and this method's.)
  227.          * @param function The function, which is being invoked to compute the result. The function will receive the
  228.          *        hidden object.
  229.          * @return The result object, which has been returned by the functions invocation.
  230.          * @throws IllegalStateException The result object would be, in fact, the hidden object. This would extend
  231.          *         access to the hidden object beyond this methods lifetime and will therefore be prevented.
  232.          * @see #acceptReadLocked(FailableConsumer)
  233.          * @see #applyWriteLocked(FailableFunction)
  234.          */
  235.         public <T> T applyWriteLocked(final FailableFunction<O, T, ?> function) {
  236.             return lockApplyUnlock(writeLockSupplier, function);
  237.         }

  239.         /**
  240.          * Gets the lock.
  241.          *
  242.          * @return the lock.
  243.          */
  244.         public L getLock() {
  245.             return lock;
  246.         }

  248.         /**
  249.          * Gets the guarded object.
  250.          *
  251.          * @return the object.
  252.          */
  253.         public O getObject() {
  254.             return object;
  255.         }

  257.         /**
  258.          * This method provides the default implementation for {@link #acceptReadLocked(FailableConsumer)}, and
  259.          * {@link #acceptWriteLocked(FailableConsumer)}.
  260.          *
  261.          * @param lockSupplier A supplier for the lock. (This provides, in fact, a long, because a {@link StampedLock} is used
  262.          *        internally.)
  263.          * @param consumer The consumer, which is to be given access to the locked (hidden) object, which will be passed
  264.          *        as a parameter.
  265.          * @see #acceptReadLocked(FailableConsumer)
  266.          * @see #acceptWriteLocked(FailableConsumer)
  267.          */
  268.         protected void lockAcceptUnlock(final Supplier<Lock> lockSupplier, final FailableConsumer<O, ?> consumer) {
  269.             final Lock lock = Objects.requireNonNull(Suppliers.get(lockSupplier), "lock");
  270.             lock.lock();
  271.             try {
  272.                 if (consumer != null) {
  273.                     consumer.accept(object);
  274.                 }
  275.             } catch (final Throwable t) {
  276.                 throw Failable.rethrow(t);
  277.             } finally {
  278.                 lock.unlock();
  279.             }
  280.         }

  282.         /**
  283.          * This method provides the actual implementation for {@link #applyReadLocked(FailableFunction)}, and
  284.          * {@link #applyWriteLocked(FailableFunction)}.
  285.          *
  286.          * @param <T> The result type (both the functions, and this method's.)
  287.          * @param lockSupplier A supplier for the lock. (This provides, in fact, a long, because a {@link StampedLock} is used
  288.          *        internally.)
  289.          * @param function The function, which is being invoked to compute the result object. This function will receive
  290.          *        the locked (hidden) object as a parameter.
  291.          * @return The result object, which has been returned by the functions invocation.
  292.          * @throws IllegalStateException The result object would be, in fact, the hidden object. This would extend
  293.          *         access to the hidden object beyond this methods lifetime and will therefore be prevented.
  294.          * @see #applyReadLocked(FailableFunction)
  295.          * @see #applyWriteLocked(FailableFunction)
  296.          */
  297.         protected <T> T lockApplyUnlock(final Supplier<Lock> lockSupplier, final FailableFunction<O, T, ?> function) {
  298.             final Lock lock = Objects.requireNonNull(Suppliers.get(lockSupplier), "lock");
  299.             lock.lock();
  300.             try {
  301.                 return function.apply(object);
  302.             } catch (final Throwable t) {
  303.                 throw Failable.rethrow(t);
  304.             } finally {
  305.                 lock.unlock();
  306.             }
  307.         }

  309.     }

  311.     /**
  312.      * This class implements a wrapper for a locked (hidden) object, and provides the means to access it. The basic
  313.      * idea, is that the user code forsakes all references to the locked object, using only the wrapper object, and the
  314.      * accessor methods {@link #acceptReadLocked(FailableConsumer)}, {@link #acceptWriteLocked(FailableConsumer)},
  315.      * {@link #applyReadLocked(FailableFunction)}, and {@link #applyWriteLocked(FailableFunction)}. By doing so, the
  316.      * necessary protections are guaranteed.
  317.      *
  318.      * @param <O> The locked (hidden) objects type.
  319.      */
  320.     public static class ReadWriteLockVisitor<O> extends LockVisitor<O, ReadWriteLock> {

  322.         /**
  323.          * Creates a new instance with the given locked object. This constructor is supposed to be used for subclassing
  324.          * only. In general, it is suggested to use {@link LockingVisitors#stampedLockVisitor(Object)} instead.
  325.          *
  326.          * @param object The locked (hidden) object. The caller is supposed to drop all references to the locked object.
  327.          * @param readWriteLock the lock to use.
  328.          */
  329.         protected ReadWriteLockVisitor(final O object, final ReadWriteLock readWriteLock) {
  330.             super(object, readWriteLock, readWriteLock::readLock, readWriteLock::writeLock);
  331.         }
  332.     }

  334.     /**
  335.      * This class implements a wrapper for a locked (hidden) object, and provides the means to access it. The basic
  336.      * idea is that the user code forsakes all references to the locked object, using only the wrapper object, and the
  337.      * accessor methods {@link #acceptReadLocked(FailableConsumer)}, {@link #acceptWriteLocked(FailableConsumer)},
  338.      * {@link #applyReadLocked(FailableFunction)}, and {@link #applyWriteLocked(FailableFunction)}. By doing so, the
  339.      * necessary protections are guaranteed.
  340.      *
  341.      * @param <O> The locked (hidden) objects type.
  342.      */
  343.     public static class StampedLockVisitor<O> extends LockVisitor<O, StampedLock> {

  345.         /**
  346.          * Creates a new instance with the given locked object. This constructor is supposed to be used for subclassing
  347.          * only. In general, it is suggested to use {@link LockingVisitors#stampedLockVisitor(Object)} instead.
  348.          *
  349.          * @param object The locked (hidden) object. The caller is supposed to drop all references to the locked object.
  350.          * @param stampedLock the lock to use.
  351.          */
  352.         protected StampedLockVisitor(final O object, final StampedLock stampedLock) {
  353.             super(object, stampedLock, stampedLock::asReadLock, stampedLock::asWriteLock);
  354.         }
  355.     }

  357.     /**
  358.      * Creates a new instance of {@link ReadWriteLockVisitor} with the given (hidden) object and lock.
  359.      *
  360.      * @param <O> The locked objects type.
  361.      * @param object The locked (hidden) object.
  362.      * @param readWriteLock The lock to use.
  363.      * @return The created instance, a {@link StampedLockVisitor lock} for the given object.
  364.      * @since 3.13.0
  365.      */
  366.     public static <O> ReadWriteLockVisitor<O> create(final O object, final ReadWriteLock readWriteLock) {
  367.         return new LockingVisitors.ReadWriteLockVisitor<>(object, readWriteLock);
  368.     }

  370.     /**
  371.      * Creates a new instance of {@link ReadWriteLockVisitor} with the given (hidden) object.
  372.      *
  373.      * @param <O> The locked objects type.
  374.      * @param object The locked (hidden) object.
  375.      * @return The created instance, a {@link StampedLockVisitor lock} for the given object.
  376.      */
  377.     public static <O> ReadWriteLockVisitor<O> reentrantReadWriteLockVisitor(final O object) {
  378.         return create(object, new ReentrantReadWriteLock());
  379.     }

  381.     /**
  382.      * Creates a new instance of {@link StampedLockVisitor} with the given (hidden) object.
  383.      *
  384.      * @param <O> The locked objects type.
  385.      * @param object The locked (hidden) object.
  386.      * @return The created instance, a {@link StampedLockVisitor lock} for the given object.
  387.      */
  388.     public static <O> StampedLockVisitor<O> stampedLockVisitor(final O object) {
  389.         return new LockingVisitors.StampedLockVisitor<>(object, new StampedLock());
  390.     }

  392.     /**
  393.      * Make private in 4.0.
  394.      *
  395.      * @deprecated TODO Make private in 4.0.
  396.      */
  397.     @Deprecated
  398.     public LockingVisitors() {
  399.         // empty
  400.     }
  401. }
Created with JaCoCo 0.8.12.202403310830