Difference between revisions of "AllOrNothingLocks"

From CSE231 Wiki
Jump to navigation Jump to search
(Added instruction to return an enum if the transaction fails)
 
(25 intermediate revisions by 2 users not shown)
Line 7: Line 7:
  
 
=Background=
 
=Background=
Check out the [[Lock_Ordering#Background|lock ordering]] studio.
+
Check out the [[Lock_Ordering#Background|lock ordering]] exercise.
  
In Java, locks are a synchronization tool that exists to ensure whatever is protected by the lock is only accessed one thread at a time, as to avoid a possible data race. In this studio we will explore the second type of locks: explicitly created <code>Lock</code> objects from the <code>java.util.concurrent.locks</code> package.
+
In Java, locks are a synchronization tool that exists to ensure whatever is protected by the lock is only accessed one thread at a time, as to avoid a possible data race. In this exercise we will explore the second type of locks: explicitly created <code>Lock</code> objects from the <code>java.util.concurrent.locks</code> package.
  
Every object has an intrinsic lock associated with the object, but <code>Lock</code> objects are explicitly defined and instantiated locks which can be called to lock or unlock. Lock objects are acted upon just like any other object, but we are mostly interested in the <code>lock()</code> method, the <code>tryLock()</code> method, and the <code>unlock()</code> method. For this studio, we will specifically use the <code>ReentrantLock</code> object, a class which implements the general <code>Lock</code> interface.
+
Every object has an intrinsic lock associated with the object, but <code>Lock</code> objects are explicitly defined and instantiated locks which can be called to lock or unlock. Lock objects are acted upon just like any other object, but we are mostly interested in the <code>lock()</code> method, the <code>tryLock()</code> method, and the <code>unlock()</code> method. For this exercise, we will specifically use the <code>ReentrantLock</code> object, a class which implements the general <code>Lock</code> interface.
  
 
To demonstrate how to avoid both data races and deadlock issues, we will create a method designed to transfer money between two bank accounts. Two parties should be able to asynchronously and continuously transfer money between each other without a data race (courtesy of locks) or deadlock (something you will address).
 
To demonstrate how to avoid both data races and deadlock issues, we will create a method designed to transfer money between two bank accounts. Two parties should be able to asynchronously and continuously transfer money between each other without a data race (courtesy of locks) or deadlock (something you will address).
Line 38: Line 38:
 
** [https://docs.oracle.com/javase/8/docs/api/java/util/ListIterator.html#hasPrevious-- boolean hasPrevious()]
 
** [https://docs.oracle.com/javase/8/docs/api/java/util/ListIterator.html#hasPrevious-- boolean hasPrevious()]
 
** [https://docs.oracle.com/javase/8/docs/api/java/util/ListIterator.html#previous-- E previous()]
 
** [https://docs.oracle.com/javase/8/docs/api/java/util/ListIterator.html#previous-- E previous()]
 +
 +
=Somewhat Dated Demo Videos=
 +
{{CollapsibleYouTube|All Or Nothing Locks|<youtube>0MLAdhm1RCA</youtube>}}
 +
 +
{{CollapsibleYouTube|Bank Account Try Lock|<youtube>yaB2f8CS5wQ</youtube>}}
 +
 +
{{CollapsibleYouTube|AllOrNothingLockUtils|<youtube>cI_wrhfT7Vw</youtube>}}
 +
 +
{{CollapsibleYouTube|Chef|<youtube>rKIEDf1nHVg</youtube>}}
 +
  
 
=Code To Implement=
 
=Code To Implement=
Line 51: Line 61:
 
}</nowiki>
 
}</nowiki>
  
===BankAccountTryLocking===
+
===BankAccountLockTrying===
 
 
{{CodeToImplement|BankAccountLockTrying|tryTransferMoney|lock.allornothing.bank.studio}}
 
  
{{ThreadSafe|public static TransferResult tryTransferMoney(AccountWithLock sender, AccountWithLock recipient, int amount)}}
+
{{CodeToImplement|BankAccountLockTrying|attemptToTransferMoney|lock.allornothing.bank.exercise}}
  
Open <code>BankAccountTryLocking.java</code>.
+
{{ThreadSafe|public static TransferResult attemptToTransferMoney(AccountWithReentrantLock sender, AccountWithReentrantLock recipient, int amount)}}
  
 
A couple of notes and common issues:
 
A couple of notes and common issues:
  
*<code>tryLock()</code> will immediately give up and return false if the lock is not available when it is called. Thus, you will need to construct a loop that will continuously run until the desired lock is available. You can exit out of this loop in two ways: with the break keyword or by returning a valid value for the method. We do this for you so you will not need to write any loops.
 
 
*<code>tryLock()</code> will grab the lock if it can. There's no need to call <code>lock()</code> after <code>tryLock()</code>.
 
*<code>tryLock()</code> will grab the lock if it can. There's no need to call <code>lock()</code> after <code>tryLock()</code>.
 
*We recommend you call the <code>TransferUtils.checkBalanceAndTransfer(sender, receiver, amount)</code> method for the sake of simplicity. This method will check that the sender and recipient are not the same people and that the sender has enough money in her account to send the specified amount to the recipient.
 
*We recommend you call the <code>TransferUtils.checkBalanceAndTransfer(sender, receiver, amount)</code> method for the sake of simplicity. This method will check that the sender and recipient are not the same people and that the sender has enough money in her account to send the specified amount to the recipient.
 
*Anytime you lock a lock object, you should/must use a <code>try/finally</code> block to unlock the lock.
 
*Anytime you lock a lock object, you should/must use a <code>try/finally</code> block to unlock the lock.
 
*Your implementation will have to make use of a nested <code>try/finally</code> block (one <code>try/finally</code> call within another).
 
*Your implementation will have to make use of a nested <code>try/finally</code> block (one <code>try/finally</code> call within another).
 +
*If at any point, you are unable to complete the transaction, your program should first, give up any locks it's currently holding (via the finally's), and then return the UNABLE_TO_ATTEMPT_AT_THIS_TIME TransferResult enum.
  
===LockUtils runWithAllLocksOrDontRunAtAll===
+
===AllOrNothingLockUtils===
<youtube>cI_wrhfT7Vw</youtube>
+
{{CodeToImplement|AllOrNothingLockUtils|tryLockAll<br>unlockAll<br>runWithAllLocksOrDontRunAtAll|lock.allornothing.util.exercise}}
  
{{CodeToImplement|LockUtils|tryLockAll<br>unlockAllHeldLocks<br>runWithAllLocksOrDontRunAtAll|lock.allornothing.util.studio}}
+
tryLockAll and unlockAll are private methods which will be used in the implementation of runWithAllLocksOrDontRunAtAll.
  
 +
====tryLockAll====
 
{{Sequential|private static boolean tryLockAll(List<ReentrantLock> locks)}}
 
{{Sequential|private static boolean tryLockAll(List<ReentrantLock> locks)}}
  
 +
tryLockAll should... well... [https://docs.oracle.com/javase/7/docs/api/java/util/concurrent/locks/Lock.html#tryLock() try to acquire] all of the locks.
 +
 +
* if all of the locks are successfully locked, true should be returned (with all of the locks held).
 +
* if all of the locks cannot be successfully locked, the locks that were acquired should be unlocked.
 +
 +
{{Alert|A lock cannot be unlocked from a thread that doesn't hold the lock.<br/>Consider using the [https://docs.oracle.com/javase/8/docs/api/java/util/ListIterator.html ListIterator] interface to move forward and backward through the provided list of ReentrantLocks.}}
 +
 +
====unlockAll====
 
{{Sequential|private static void unlockAll(List<ReentrantLock> locks)}}
 
{{Sequential|private static void unlockAll(List<ReentrantLock> locks)}}
  
{{ThreadSafe|public static boolean runWithAllLocksOrDontRunAtAll(List<ReentrantLock> locks, Runnable body)}}
+
unlockAll should... well... [https://docs.oracle.com/javase/7/docs/api/java/util/concurrent/locks/ReentrantLock.html#unlock() unlock] all of the locks.  This method should only be called when all of the locks are held by the current thread.  Thus, it should throw an [https://docs.oracle.com/javase/7/docs/api/java/lang/IllegalMonitorStateException.html IllegalMonitorStateException] if one of the locks is not held by the current thread.
 
 
Open <code>LockUtils.java</code>.
 
  
For this part of the studio you will need to implement:
+
* If a lock is held by the current thread, it should be unlocked.
 +
* If a lock is not held by the current thread, an [https://docs.oracle.com/javase/7/docs/api/java/lang/IllegalMonitorStateException.html IllegalMonitorStateException] should be thrown.  Note: this perhaps sounds more complicated than it is.  Calling an [https://docs.oracle.com/javase/7/docs/api/java/util/concurrent/locks/ReentrantLock.html#unlock() unlock] on an unheld Lock will throw an [https://docs.oracle.com/javase/7/docs/api/java/lang/IllegalMonitorStateException.html IllegalMonitorStateException].  Therefore, a simple for each loop that unlocks all of the locks without checking to see if they are held will produce the correct behavior.
  
<code>private static boolean tryLockAll(List<ReentrantLock> locks)</code>
+
====runWithAllLocksOrDontRunAtAll====
 +
{{ThreadSafe|public static boolean runWithAllLocksOrDontRunAtAll(List<ReentrantLock> locks, Runnable body)}}
  
and
+
runWithAllLocksOrDontRunAtAll should use tryLockAll and unlockAll to produce the desired behavior.
  
<code>private static void unlockAll(List<ReentrantLock> locks)</code>
+
* If all of the locks are successfully acquired, the [https://docs.oracle.com/javase/7/docs/api/java/lang/Runnable.html Runnable] body should be [https://docs.oracle.com/javase/7/docs/api/java/lang/Runnable.html#run() run] while the locks are being held, and then the locks should be released before returning true indicating success.
 +
* If all of the locks cannot be acquired, false should be returned indicating failure to run the specified body.
  
so that the useful utility (shouldn't they all be useful?)
+
====runWithAllLocks====
 +
This version of runWithAllLocks is a convenience method which repeatedly tries to runWithAllLocksOrDontRunAtAll until it works, invoking the failureAction each time it fails.
  
<nowiki>public static boolean runWithAllLocksOrDontRunAtAll(List<ReentrantLock> locks, Runnable body) {
+
{{CollapsibleCode|runWithAllLocks(locks, body, failureAction)|
boolean status = tryLockAll(locks);
+
<syntaxhighlight lang="java">
if (status) {
+
public static void runWithAllLocks(List<ReentrantLock> locks, Runnable body, InterruptibleRunnable failureAction) throws InterruptedException {
try {
+
while (true) {
body.run();
+
if (runWithAllLocksOrDontRunAtAll(locks, body)) {
} finally {
+
break;
unlockAll(locks);
+
} else {
 +
failureAction.run();
 
}
 
}
 
}
 
}
return status;
+
}
}</nowiki>
+
</syntaxhighlight>}}
  
produces correct thread safe behavior.
+
====runWithAllLocks====
 +
This version of runWithAllLocks is a convenience method which calls the more general version of runWithAllLocks, specifying to [https://docs.oracle.com/javase/7/docs/api/java/lang/Thread.html#yield() yield] the current Thread as its failure action.
  
Note: in <code>tryLockAll</code>, you will need to call <code>tryLock</code> on all of the given locks. However, if one fails, you will need to unlock everything you have currently locked. A lock cannot be unlocked from a thread that doesn't hold the lock. Consider using the [https://docs.oracle.com/javase/8/docs/api/java/util/ListIterator.html ListIterator] interface.
+
{{CollapsibleCode|runWithAllLocks(locks, body)|
 
+
<syntaxhighlight lang="java">
{{Warning | If tryLockAll fails to acquire all of the locks, make sure to unlock any of the locks you did acquire.}}
+
public static void runWithAllLocks(List<ReentrantLock> locks, Runnable body) throws InterruptedException {
 
+
runWithAllLocks(locks, body, () -> {
{{Warning | If tryLockAll fails, when rolling back a ListIterator to unlock any locks you acquired, be sure to do an initial prev() to set the iterator in the correct location before looping through to unlock the rest.}}
+
if (Thread.currentThread().isInterrupted()) {
 +
throw new InterruptedException();
 +
}
 +
Thread.yield();
 +
});
 +
}
 +
</syntaxhighlight>}}
  
{{Warning | An IllegalMonitorStateException() means that a thread tried to unlock a lock that it was not holding. }}
+
===Chef===
  
===KitchenLockUtilsApp===
+
{{CodeToImplement|Chef|attemptToPrepare|lock.allornothing.kitchen.exercise}}
  
{{CodeToImplement|KitchenLockUtilsApp|executeRecipe|lock.allornothing.kitchen.studio}}
+
{{Sequential|public static boolean attemptToPrepare(Recipe recipe)}}
 
 
{{Sequential|public static boolean executeRecipe(Recipe recipe)}}
 
 
 
Open <code>KitchenLockUtilsApp.java</code>.
 
  
 
A couple of notes:
 
A couple of notes:
  
 
*An object of class Recipe contains a list of Appliances that it needs in order to complete the item. An object of class Appliance has a lock that you can use to make sure the method remains thread-safe.
 
*An object of class Recipe contains a list of Appliances that it needs in order to complete the item. An object of class Appliance has a lock that you can use to make sure the method remains thread-safe.
*Use the <code>recipe.create()</code> method in order to actually execute the recipe. Caution: this method will throw an <code>IllegalThreadStateException()</code> if it is called without all the locks being held by the same thread that called the create method.
+
*Use the <code>recipe.prepare()</code> method in order to actually execute the recipe. Caution: this method will throw an <code>IllegalThreadStateException()</code> if it is called without all the locks being held by the same thread that called the create method.
* Since it is unknown how many locks each recipe will need beforehand, make use of the <code>LockUtils.runWithAllLocksOrDontRunAtAll(List<ReentrantLock> locks, Runnable body)</code> method you wrote earlier.
+
* Since it is unknown how many locks each recipe will need beforehand, make use of the <code>AllOrNothingLockUtils.runWithAllLocksOrDontRunAtAll(List<ReentrantLock> locks, Runnable body)</code> method you wrote earlier.
  
{{Warning|The javadocs incorrectly refer to runWithAllLocks when runWithAllLocksOrDontRunAtAll is the correct method to invoke.}}
+
Perhaps a higher-order function from earlier in the semester will be useful here.
 +
 
 +
{{Spoiler|[[Higher-order_Functions_Map_And_Reduce_Assignment#map|map higher-order function]]}}
  
 
=Testing Your Solution=
 
=Testing Your Solution=
==Correctness==
+
{{TestSuite|_TryLockingTestSuite|lock.allornothing.exercise}}
===Complete===
 
{{TestSuite|TryLockingTestSuite|lock.allornothing.studio}}
 
===Individual===
 
{{TestSuite|BankTryLockingTestSuite|lock.allornothing.bank.studio}}
 
 
 
{{TestSuite|LockUtilsTestSuite|lock.allornothing.studio}}
 
  
{{TestSuite|KitchenTestSuite|lock.allornothing.util.studio}}
+
=Pledge, Acknowledgments, Citations=
 +
{{Pledge|all-or-nothing-locks}}

Latest revision as of 17:01, 5 April 2023

credit for this assignment: Java Concurrency in Practice, Ben Choi, Miles Cushing, and Dennis Cosgrove

Motivation

In addition to Ordered Locks we can employ an all-or-nothing strategy for acquiring locks for mutual exclusion.

We gain experience with explicit locks and trying to acquire them and responding appropriately to success and failure.

Background

Check out the lock ordering exercise.

In Java, locks are a synchronization tool that exists to ensure whatever is protected by the lock is only accessed one thread at a time, as to avoid a possible data race. In this exercise we will explore the second type of locks: explicitly created Lock objects from the java.util.concurrent.locks package.

Every object has an intrinsic lock associated with the object, but Lock objects are explicitly defined and instantiated locks which can be called to lock or unlock. Lock objects are acted upon just like any other object, but we are mostly interested in the lock() method, the tryLock() method, and the unlock() method. For this exercise, we will specifically use the ReentrantLock object, a class which implements the general Lock interface.

To demonstrate how to avoid both data races and deadlock issues, we will create a method designed to transfer money between two bank accounts. Two parties should be able to asynchronously and continuously transfer money between each other without a data race (courtesy of locks) or deadlock (something you will address).

For this approach, we will make use of the tryLock() method in order to attempt to acquire an object’s lock. If the object’s lock is not available at the time, we will continue to try to acquire the lock until it finally succeeds, after which we can successfully transfer funds from one bank account to another. In this approach, an asynchronous pair of transfers from A to B and B to A will not lead to deadlock as the two processes will give up on acquiring the lock until it becomes available, at which point it will finally acquire the lock. This approach does not make use of ordering, but simply relies on making lock attempts give up if the desired lock is not immediately available (and then try again later).

Java Util Concurrent

Refer to Oracle's official documentation for more information:

Somewhat Dated Demo Videos

Video: All Or Nothing Locks  
Video: Bank Account Try Lock  
Video: AllOrNothingLockUtils  
Video: Chef  


Code To Implement

As mentioned in the background section, this implementation will avoid deadlock by giving up on acquiring a lock if it is not immediately available before coming back to it later (when it might actually be available). This implementation will need to make use of the ReentrantLocks associated with the sender and recipient bank account objects. More specifically, it will have to make use of the tryLock() method. For an example of how to format a tryLock, look below:

Lock lock = ...
if (lock.tryLock()) {
	try {
		doSomething();
	} finally {
		lock.unlock();
	}
}

BankAccountLockTrying

class: BankAccountLockTrying.java Java.png
methods: attemptToTransferMoney
package: lock.allornothing.bank.exercise
source folder: student/src/main/java

method: public static TransferResult attemptToTransferMoney(AccountWithReentrantLock sender, AccountWithReentrantLock recipient, int amount) Sequential.svg (thread-safe required)

A couple of notes and common issues:

  • tryLock() will grab the lock if it can. There's no need to call lock() after tryLock().
  • We recommend you call the TransferUtils.checkBalanceAndTransfer(sender, receiver, amount) method for the sake of simplicity. This method will check that the sender and recipient are not the same people and that the sender has enough money in her account to send the specified amount to the recipient.
  • Anytime you lock a lock object, you should/must use a try/finally block to unlock the lock.
  • Your implementation will have to make use of a nested try/finally block (one try/finally call within another).
  • If at any point, you are unable to complete the transaction, your program should first, give up any locks it's currently holding (via the finally's), and then return the UNABLE_TO_ATTEMPT_AT_THIS_TIME TransferResult enum.

AllOrNothingLockUtils

class: AllOrNothingLockUtils.java Java.png
methods: tryLockAll
unlockAll
runWithAllLocksOrDontRunAtAll
package: lock.allornothing.util.exercise
source folder: student/src/main/java

tryLockAll and unlockAll are private methods which will be used in the implementation of runWithAllLocksOrDontRunAtAll.

tryLockAll

method: private static boolean tryLockAll(List<ReentrantLock> locks) Sequential.svg (sequential implementation only)

tryLockAll should... well... try to acquire all of the locks.

  • if all of the locks are successfully locked, true should be returned (with all of the locks held).
  • if all of the locks cannot be successfully locked, the locks that were acquired should be unlocked.
Attention niels epting.svg Alert:A lock cannot be unlocked from a thread that doesn't hold the lock.
Consider using the ListIterator interface to move forward and backward through the provided list of ReentrantLocks.

unlockAll

method: private static void unlockAll(List<ReentrantLock> locks) Sequential.svg (sequential implementation only)

unlockAll should... well... unlock all of the locks. This method should only be called when all of the locks are held by the current thread. Thus, it should throw an IllegalMonitorStateException if one of the locks is not held by the current thread.

  • If a lock is held by the current thread, it should be unlocked.
  • If a lock is not held by the current thread, an IllegalMonitorStateException should be thrown. Note: this perhaps sounds more complicated than it is. Calling an unlock on an unheld Lock will throw an IllegalMonitorStateException. Therefore, a simple for each loop that unlocks all of the locks without checking to see if they are held will produce the correct behavior.

runWithAllLocksOrDontRunAtAll

method: public static boolean runWithAllLocksOrDontRunAtAll(List<ReentrantLock> locks, Runnable body) Sequential.svg (thread-safe required)

runWithAllLocksOrDontRunAtAll should use tryLockAll and unlockAll to produce the desired behavior.

  • If all of the locks are successfully acquired, the Runnable body should be run while the locks are being held, and then the locks should be released before returning true indicating success.
  • If all of the locks cannot be acquired, false should be returned indicating failure to run the specified body.

runWithAllLocks

This version of runWithAllLocks is a convenience method which repeatedly tries to runWithAllLocksOrDontRunAtAll until it works, invoking the failureAction each time it fails.

runWithAllLocks(locks, body, failureAction)  
public static void runWithAllLocks(List<ReentrantLock> locks, Runnable body, InterruptibleRunnable failureAction) throws InterruptedException {
	while (true) {
		if (runWithAllLocksOrDontRunAtAll(locks, body)) {
			break;
		} else {
			failureAction.run();
		}
	}
}

runWithAllLocks

This version of runWithAllLocks is a convenience method which calls the more general version of runWithAllLocks, specifying to yield the current Thread as its failure action.

runWithAllLocks(locks, body)  
public static void runWithAllLocks(List<ReentrantLock> locks, Runnable body) throws InterruptedException {
	runWithAllLocks(locks, body, () -> {
		if (Thread.currentThread().isInterrupted()) {
			throw new InterruptedException();
		}
		Thread.yield();
	});
}

Chef

class: Chef.java Java.png
methods: attemptToPrepare
package: lock.allornothing.kitchen.exercise
source folder: student/src/main/java

method: public static boolean attemptToPrepare(Recipe recipe) Sequential.svg (sequential implementation only)

A couple of notes:

  • An object of class Recipe contains a list of Appliances that it needs in order to complete the item. An object of class Appliance has a lock that you can use to make sure the method remains thread-safe.
  • Use the recipe.prepare() method in order to actually execute the recipe. Caution: this method will throw an IllegalThreadStateException() if it is called without all the locks being held by the same thread that called the create method.
  • Since it is unknown how many locks each recipe will need beforehand, make use of the AllOrNothingLockUtils.runWithAllLocksOrDontRunAtAll(List<ReentrantLock> locks, Runnable body) method you wrote earlier.

Perhaps a higher-order function from earlier in the semester will be useful here.

Testing Your Solution

class: _TryLockingTestSuite.java Junit.png
package: lock.allornothing.exercise
source folder: testing/src/test/java

Pledge, Acknowledgments, Citations

file: all-or-nothing-locks-pledge-acknowledgments-citations.txt

More info about the Honor Pledge