25 |
26 |
27 |
--------------------------------------------------------------------------------
/documentation/javadoc/apidocs/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 | concurrent-locks 1.0.0-SNAPSHOT API
8 |
19 |
20 |
31 |
32 |
--------------------------------------------------------------------------------
/code/src/main/java/com/googlecode/concurentlocks/ReadWriteUpdateLock.java:
--------------------------------------------------------------------------------
1 | /**
2 | * Copyright 2013 Niall Gallagher
3 | *
4 | * Licensed under the Apache License, Version 2.0 (the "License");
5 | * you may not use this file except in compliance with the License.
6 | * You may obtain a copy of the License at
7 | *
8 | * http://www.apache.org/licenses/LICENSE-2.0
9 | *
10 | * Unless required by applicable law or agreed to in writing, software
11 | * distributed under the License is distributed on an "AS IS" BASIS,
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | * See the License for the specific language governing permissions and
14 | * limitations under the License.
15 | */
16 | package com.googlecode.concurentlocks;
17 |
18 | import java.util.concurrent.locks.Lock;
19 | import java.util.concurrent.locks.ReadWriteLock;
20 |
21 | /**
22 | * Extends the JDK {@link ReadWriteLock}, providing an update lock in addition to the read lock and the write
23 | * lock.
24 | *
25 | * The {@link #updateLock update lock} supports read-only operations and can coexist with multiple
26 | * {@link #readLock read lock}s held simultaneously by other reader threads. However it may also be upgraded from
27 | * its read-only status to a {@link #writeLock write lock}, and it may be downgraded again back to a read lock.
28 | *
29 | * See implementation {@link ReentrantReadWriteUpdateLock} for more details.
30 | *
31 | * @author Niall Gallagher
32 | */
33 | public interface ReadWriteUpdateLock extends ReadWriteLock {
34 |
35 | /**
36 | * Returns a lock which allows reading and which may also be upgraded to a lock allowing writing.
37 | *
38 | * @return a lock which allows reading and which may also be upgraded to a lock allowing writing.
39 | */
40 | Lock updateLock();
41 | }
42 |
--------------------------------------------------------------------------------
/archive/googlecode-tags/1.0.0/src/main/java/com/googlecode/concurentlocks/ReadWriteUpdateLock.java:
--------------------------------------------------------------------------------
1 | /**
2 | * Copyright 2013 Niall Gallagher
3 | *
4 | * Licensed under the Apache License, Version 2.0 (the "License");
5 | * you may not use this file except in compliance with the License.
6 | * You may obtain a copy of the License at
7 | *
8 | * http://www.apache.org/licenses/LICENSE-2.0
9 | *
10 | * Unless required by applicable law or agreed to in writing, software
11 | * distributed under the License is distributed on an "AS IS" BASIS,
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | * See the License for the specific language governing permissions and
14 | * limitations under the License.
15 | */
16 | package com.googlecode.concurentlocks;
17 |
18 | import java.util.concurrent.locks.Lock;
19 | import java.util.concurrent.locks.ReadWriteLock;
20 |
21 | /**
22 | * Extends the JDK {@link ReadWriteLock}, providing an update lock in addition to the read lock and the write
23 | * lock.
24 | *
25 | * The {@link #updateLock update lock} supports read-only operations and can coexist with multiple
26 | * {@link #readLock read lock}s held simultaneously by other reader threads. However it may also be upgraded from
27 | * its read-only status to a {@link #writeLock write lock}, and it may be downgraded again back to a read lock.
28 | *
29 | * See implementation {@link ReentrantReadWriteUpdateLock} for more details.
30 | *
31 | * @author Niall Gallagher
32 | */
33 | public interface ReadWriteUpdateLock extends ReadWriteLock {
34 |
35 | /**
36 | * Returns a lock which allows reading and which may also be upgraded to a lock allowing writing.
37 | *
38 | * @return a lock which allows reading and which may also be upgraded to a lock allowing writing.
39 | */
40 | Lock updateLock();
41 | }
42 |
--------------------------------------------------------------------------------
/code/src/main/java/com/googlecode/concurentlocks/CompositeLock.java:
--------------------------------------------------------------------------------
1 | /**
2 | * Copyright 2013 Niall Gallagher
3 | *
4 | * Licensed under the Apache License, Version 2.0 (the "License");
5 | * you may not use this file except in compliance with the License.
6 | * You may obtain a copy of the License at
7 | *
8 | * http://www.apache.org/licenses/LICENSE-2.0
9 | *
10 | * Unless required by applicable law or agreed to in writing, software
11 | * distributed under the License is distributed on an "AS IS" BASIS,
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | * See the License for the specific language governing permissions and
14 | * limitations under the License.
15 | */
16 | package com.googlecode.concurentlocks;
17 |
18 | import java.util.*;
19 | import java.util.concurrent.TimeUnit;
20 | import java.util.concurrent.locks.Condition;
21 | import java.util.concurrent.locks.Lock;
22 |
23 | /**
24 | * A lock spanning a group of backing locks. When this composite lock is locked, it locks all backing locks, and when
25 | * unlocked, it unlocks all backing locks. Employs roll back logic to ensure that either all locks are acquired
26 | * or no locks are acquired. Locks are unlocked in the reverse of the order in which the were acquired.
27 | *
28 | * This class delegates most of its implementation to the {@link Locks} utility class.
29 | *
30 | * @author Niall Gallagher
31 | */
32 | public class CompositeLock implements Lock {
33 |
34 | final Deque locks;
35 |
36 | public CompositeLock(Lock... locks) {
37 | this(new LinkedList(Arrays.asList(locks)));
38 | }
39 |
40 | public CompositeLock(Deque locks) {
41 | this.locks = locks;
42 | }
43 |
44 | @Override
45 | public void lock() {
46 | Locks.lockAll(locks);
47 | }
48 |
49 | @Override
50 | public void lockInterruptibly() throws InterruptedException {
51 | Locks.lockInterruptiblyAll(locks);
52 | }
53 | @Override
54 | public boolean tryLock() {
55 | return Locks.tryLockAll(locks);
56 | }
57 |
58 | @Override
59 | public boolean tryLock(long time, TimeUnit unit) throws InterruptedException {
60 | return Locks.tryLockAll(time, unit, locks);
61 | }
62 |
63 | @Override
64 | public void unlock() {
65 | // Unlock in reverse order...
66 | Locks.unlockAll(new Iterable() {
67 | @Override
68 | public Iterator iterator() {
69 | return locks.descendingIterator();
70 | }
71 | });
72 | }
73 |
74 | @Override
75 | public Condition newCondition() {
76 | throw new UnsupportedOperationException("This lock does not support conditions");
77 | }
78 | }
79 |
--------------------------------------------------------------------------------
/archive/googlecode-tags/1.0.0/src/main/java/com/googlecode/concurentlocks/CompositeLock.java:
--------------------------------------------------------------------------------
1 | /**
2 | * Copyright 2013 Niall Gallagher
3 | *
4 | * Licensed under the Apache License, Version 2.0 (the "License");
5 | * you may not use this file except in compliance with the License.
6 | * You may obtain a copy of the License at
7 | *
8 | * http://www.apache.org/licenses/LICENSE-2.0
9 | *
10 | * Unless required by applicable law or agreed to in writing, software
11 | * distributed under the License is distributed on an "AS IS" BASIS,
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | * See the License for the specific language governing permissions and
14 | * limitations under the License.
15 | */
16 | package com.googlecode.concurentlocks;
17 |
18 | import java.util.*;
19 | import java.util.concurrent.TimeUnit;
20 | import java.util.concurrent.locks.Condition;
21 | import java.util.concurrent.locks.Lock;
22 |
23 | /**
24 | * A lock spanning a group of backing locks. When this composite lock is locked, it locks all backing locks, and when
25 | * unlocked, it unlocks all backing locks. Employs roll back logic to ensure that either all locks are acquired
26 | * or no locks are acquired. Locks are unlocked in the reverse of the order in which the were acquired.
27 | *
28 | * This class delegates most of its implementation to the {@link Locks} utility class.
29 | *
30 | * @author Niall Gallagher
31 | */
32 | public class CompositeLock implements Lock {
33 |
34 | final Deque locks;
35 |
36 | public CompositeLock(Lock... locks) {
37 | this(new LinkedList(Arrays.asList(locks)));
38 | }
39 |
40 | public CompositeLock(Deque locks) {
41 | this.locks = locks;
42 | }
43 |
44 | @Override
45 | public void lock() {
46 | Locks.lockAll(locks);
47 | }
48 |
49 | @Override
50 | public void lockInterruptibly() throws InterruptedException {
51 | Locks.lockInterruptiblyAll(locks);
52 | }
53 | @Override
54 | public boolean tryLock() {
55 | return Locks.tryLockAll(locks);
56 | }
57 |
58 | @Override
59 | public boolean tryLock(long time, TimeUnit unit) throws InterruptedException {
60 | return Locks.tryLockAll(time, unit, locks);
61 | }
62 |
63 | @Override
64 | public void unlock() {
65 | // Unlock in reverse order...
66 | Locks.unlockAll(new Iterable() {
67 | @Override
68 | public Iterator iterator() {
69 | return locks.descendingIterator();
70 | }
71 | });
72 | }
73 |
74 | @Override
75 | public Condition newCondition() {
76 | throw new UnsupportedOperationException("This lock does not support conditions");
77 | }
78 | }
79 |
--------------------------------------------------------------------------------
/code/src/test/java/com/googlecode/concurentlocks/examples/ExampleUsage.java:
--------------------------------------------------------------------------------
1 | /**
2 | * Copyright 2013 Niall Gallagher
3 | *
4 | * Licensed under the Apache License, Version 2.0 (the "License");
5 | * you may not use this file except in compliance with the License.
6 | * You may obtain a copy of the License at
7 | *
8 | * http://www.apache.org/licenses/LICENSE-2.0
9 | *
10 | * Unless required by applicable law or agreed to in writing, software
11 | * distributed under the License is distributed on an "AS IS" BASIS,
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | * See the License for the specific language governing permissions and
14 | * limitations under the License.
15 | */
16 | package com.googlecode.concurentlocks.examples;
17 |
18 | import com.googlecode.concurentlocks.ReadWriteUpdateLock;
19 | import com.googlecode.concurentlocks.ReentrantReadWriteUpdateLock;
20 |
21 | /**
22 | * Demonstrates usage of {@link com.googlecode.concurentlocks.ReentrantReadWriteUpdateLock}.
23 | *
24 | * For simplicity leaves methods to actually read and write the document as an exercise to the reader.
25 | *
26 | * @author Niall Gallagher
27 | */
28 | public abstract class ExampleUsage {
29 |
30 | final ReadWriteUpdateLock readWriteUpdateLock = new ReentrantReadWriteUpdateLock();
31 |
32 | public void updateDocumentIfNecessary() {
33 | readWriteUpdateLock.updateLock().lock(); // allows other readers, blocks others from acquiring update or write locks
34 | try {
35 | // STEP 1: Read in the document...
36 | Document currentDocument = readInDocument();
37 | // Decide if document actually needs to be updated...
38 | if (shouldUpdate(currentDocument)) {
39 | // STEP 2: Generate a new version of the document...
40 | Document newVersion = generateNewVersion(currentDocument);
41 | // STEP 3: Write out new version...
42 | readWriteUpdateLock.writeLock().lock(); // upgrade to the write lock, at this point blocks other readers
43 | try {
44 | writeOutDocument(newVersion);
45 | }
46 | finally {
47 | readWriteUpdateLock.writeLock().unlock(); // downgrade back to update lock
48 | }
49 | }
50 | }
51 | finally {
52 | readWriteUpdateLock.updateLock().unlock(); // release update lock
53 | }
54 | }
55 |
56 | public Document readDocument() {
57 | readWriteUpdateLock.readLock().lock(); // blocks others from acquiring write lock
58 | try {
59 | return readInDocument();
60 | }
61 | finally {
62 | readWriteUpdateLock.readLock().unlock();
63 | }
64 | }
65 |
66 | interface Document {}
67 | protected abstract Document readInDocument();
68 | protected abstract boolean shouldUpdate(Document document);
69 | protected abstract Document generateNewVersion(Document document);
70 | protected abstract void writeOutDocument(Document document);
71 | }
72 |
--------------------------------------------------------------------------------
/documentation/javadoc/apidocs/deprecated-list.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 | Deprecated List (concurrent-locks 1.0.0-SNAPSHOT API)
8 |
9 |
10 |
11 |
12 |
18 |
21 |
22 |
An implementation of ReadWriteUpdateLock, extending the functionality of the JDK
87 | ReentrantReadWriteLock with an update lock in addition to the read and write lock, supporting upgrade
88 | from read-only operation to writing status, and downgrade again.
Utility methods to group-lock and group-unlock collections of locks, including roll back support to
106 | ensure that either all locks are acquired or no locks are acquired.
An implementation of ReadWriteUpdateLock, extending the functionality of the JDK
113 | ReentrantReadWriteLock with an update lock in addition to the read and write lock, supporting upgrade
114 | from read-only operation to writing status, and downgrade again.
This API (Application Programming Interface) document has pages corresponding to the items in the navigation bar, described as follows.
68 |
69 |
70 |
71 |
72 |
Package
73 |
Each package has a page that contains a list of its classes and interfaces, with a summary for each. This page can contain six categories:
74 |
75 |
Interfaces (italic)
76 |
Classes
77 |
Enums
78 |
Exceptions
79 |
Errors
80 |
Annotation Types
81 |
82 |
83 |
84 |
Class/Interface
85 |
Each class, interface, nested class and nested interface has its own separate page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions:
86 |
87 |
Class inheritance diagram
88 |
Direct Subclasses
89 |
All Known Subinterfaces
90 |
All Known Implementing Classes
91 |
Class/interface declaration
92 |
Class/interface description
93 |
94 |
95 |
Nested Class Summary
96 |
Field Summary
97 |
Constructor Summary
98 |
Method Summary
99 |
100 |
101 |
Field Detail
102 |
Constructor Detail
103 |
Method Detail
104 |
105 |
Each summary entry contains the first sentence from the detailed description for that item. The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.
106 |
107 |
108 |
Annotation Type
109 |
Each annotation type has its own separate page with the following sections:
110 |
111 |
Annotation Type declaration
112 |
Annotation Type description
113 |
Required Element Summary
114 |
Optional Element Summary
115 |
Element Detail
116 |
117 |
118 |
119 |
Enum
120 |
Each enum has its own separate page with the following sections:
121 |
122 |
Enum declaration
123 |
Enum description
124 |
Enum Constant Summary
125 |
Enum Constant Detail
126 |
127 |
128 |
129 |
Use
130 |
Each documented package, class and interface has its own Use page. This page describes what packages, classes, methods, constructors and fields use any part of the given class or package. Given a class or interface A, its Use page includes subclasses of A, fields declared as A, methods that return A, and methods and constructors with parameters of type A. You can access this page by first going to the package, class or interface, then clicking on the "Use" link in the navigation bar.
131 |
132 |
133 |
Tree (Class Hierarchy)
134 |
There is a Class Hierarchy page for all packages, plus a hierarchy for each package. Each hierarchy page contains a list of classes and a list of interfaces. The classes are organized by inheritance structure starting with java.lang.Object. The interfaces do not inherit from java.lang.Object.
135 |
136 |
When viewing the Overview page, clicking on "Tree" displays the hierarchy for all packages.
137 |
When viewing a particular package, class or interface page, clicking "Tree" displays the hierarchy for only that package.
138 |
139 |
140 |
141 |
Deprecated API
142 |
The Deprecated API page lists all of the API that have been deprecated. A deprecated API is not recommended for use, generally due to improvements, and a replacement API is usually given. Deprecated APIs may be removed in future implementations.
143 |
144 |
145 |
Index
146 |
The Index contains an alphabetic list of all classes, interfaces, constructors, methods, and fields.
147 |
148 |
149 |
Prev/Next
150 |
These links take you to the next or previous class, interface, package, or related page.
151 |
152 |
153 |
Frames/No Frames
154 |
These links show and hide the HTML frames. All pages are available with or without frames.
155 |
156 |
157 |
All Classes
158 |
The All Classes link shows all classes and interfaces except non-static nested types.
159 |
160 |
161 |
Serialized Form
162 |
Each serializable or externalizable class has a description of its serialization fields and methods. This information is of interest to re-implementors, not to developers using the API. While there is no link in the navigation bar, you can get to this information by going to any serialized class and clicking "Serialized Form" in the "See also" section of the class description.
215 |
216 |
217 |
--------------------------------------------------------------------------------
/code/src/main/java/com/googlecode/concurentlocks/Locks.java:
--------------------------------------------------------------------------------
1 | /**
2 | * Copyright 2013 Niall Gallagher
3 | *
4 | * Licensed under the Apache License, Version 2.0 (the "License");
5 | * you may not use this file except in compliance with the License.
6 | * You may obtain a copy of the License at
7 | *
8 | * http://www.apache.org/licenses/LICENSE-2.0
9 | *
10 | * Unless required by applicable law or agreed to in writing, software
11 | * distributed under the License is distributed on an "AS IS" BASIS,
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | * See the License for the specific language governing permissions and
14 | * limitations under the License.
15 | */
16 | package com.googlecode.concurentlocks;
17 |
18 | import java.util.*;
19 | import java.util.concurrent.TimeUnit;
20 | import java.util.concurrent.locks.Lock;
21 |
22 | /**
23 | * Utility methods to group-lock and group-unlock collections of locks, including roll back support to
24 | * ensure that either all locks are acquired or no locks are acquired.
25 | *
26 | * @author Niall Gallagher
27 | */
28 | public class Locks {
29 |
30 | /**
31 | * Calls {@link java.util.concurrent.locks.Lock#lock()} on all locks provided by the given iterable, in the order
32 | * provided by the iterable. Automatically releases any locks acquired (in reverse order) by calling
33 | * {@link java.util.concurrent.locks.Lock#unlock()} if an exception is thrown, before re-throwing the exception.
34 | *
35 | * @param locks The locks to acquire
36 | * @param Type of the lock
37 | */
38 | public static void lockAll(Iterable locks) {
39 | Deque stack = new LinkedList();
40 | try {
41 | for (L lock : locks) {
42 | lock.lock();
43 | stack.push(lock);
44 | }
45 | }
46 | catch (RuntimeException e) {
47 | // Roll back: unlock the locks acquired so far...
48 | unlockAll(stack);
49 | throw e;
50 | }
51 | }
52 |
53 | /**
54 | * Calls {@link java.util.concurrent.locks.Lock#lockInterruptibly()} on all locks provided by the given iterable, in
55 | * the order provided by the iterable. Automatically releases any locks acquired (in reverse order) by calling
56 | * {@link java.util.concurrent.locks.Lock#unlock()} if the thread is interrupted while waiting for a lock or if
57 | * an exception is thrown, before re-throwing the exception.
58 | *
59 | * @param locks The locks to acquire
60 | * @param Type of the lock
61 | * @throws InterruptedException If the thread is interrupted while waiting for a lock
62 | */
63 | public static void lockInterruptiblyAll(Iterable locks) throws InterruptedException {
64 | Deque stack = new LinkedList();
65 | try {
66 | for (L lock : locks) {
67 | lock.lockInterruptibly();
68 | stack.push(lock);
69 | }
70 | }
71 | catch (InterruptedException e) {
72 | // Roll back: unlock the locks acquired so far...
73 | unlockAll(stack);
74 | throw e;
75 | }
76 | catch (RuntimeException e) {
77 | // Roll back: unlock the locks acquired so far...
78 | unlockAll(stack);
79 | throw e;
80 | }
81 | }
82 |
83 | /**
84 | * Calls {@link java.util.concurrent.locks.Lock#tryLock()} on all locks provided by the given iterable, in the order
85 | * provided by the iterable. Automatically releases any locks acquired (in reverse order) by calling
86 | * {@link java.util.concurrent.locks.Lock#unlock()} if it is not possible to obtain any lock, if the thread is
87 | * interrupted while waiting for a lock, or if an exception is thrown, before re-throwing the exception.
88 | *
89 | * @param locks The locks to acquire
90 | * @param Type of the lock
91 | * @return True if at least one lock was supplied and all supplied locks were acquired successfully, otherwise false
92 | */
93 | public static boolean tryLockAll(Iterable locks) {
94 | Deque stack = new LinkedList();
95 | boolean success = false;
96 | try {
97 | for (L lock : locks) {
98 | success = lock.tryLock();
99 | if (success) {
100 | stack.push(lock);
101 | }
102 | else {
103 | break;
104 | }
105 | }
106 | }
107 | catch (RuntimeException e) {
108 | // Roll back: unlock the locks acquired so far...
109 | unlockAll(stack);
110 | throw e;
111 | }
112 | if (!success) {
113 | // Roll back: unlock the locks acquired so far...
114 | unlockAll(stack);
115 | }
116 | return success;
117 | }
118 |
119 | /**
120 | * Calls {@link java.util.concurrent.locks.Lock#tryLock()} on all locks provided by the given iterable, in the order
121 | * provided by the iterable. Automatically releases any locks acquired (in reverse order) by calling
122 | * {@link java.util.concurrent.locks.Lock#unlock()} if it is not possible to obtain any lock within the remaining
123 | * time within the timeout given, if the thread is interrupted while waiting for a lock, or if an exception is
124 | * thrown, before re-throwing the exception.
125 | *
126 | * @param time the maximum time to wait for all locks combined
127 | * @param unit the time unit of the {@code time} argument
128 | * @param locks The locks to acquire
129 | * @param Type of the lock
130 | * @return True if at least one lock was supplied and all supplied locks were acquired successfully, otherwise false
131 | * @throws InterruptedException If the thread is interrupted while waiting for a lock
132 | */
133 | public static boolean tryLockAll(long time, TimeUnit unit, Iterable locks) throws InterruptedException {
134 | Deque stack = new LinkedList();
135 | boolean success = false;
136 | try {
137 | long limitNanos = unit.toNanos(time);
138 | long startNanos = System.nanoTime();
139 | for (L lock : locks) {
140 | long remainingNanos = !success
141 | ? limitNanos // No need to calculate remaining time in first iteration
142 | : limitNanos - (System.nanoTime() - startNanos); // recalculate in subsequent iterations
143 |
144 | // Note if remaining time is <= 0, we still try to obtain additional locks, supplying zero or negative
145 | // timeouts to those locks, which should treat it as a non-blocking tryLock() per API docs...
146 | success = lock.tryLock(remainingNanos, TimeUnit.NANOSECONDS);
147 | if (success) {
148 | stack.push(lock);
149 | }
150 | else {
151 | break;
152 | }
153 | }
154 | }
155 | catch (RuntimeException e) {
156 | // Roll back: unlock the locks acquired so far...
157 | unlockAll(stack);
158 | throw e;
159 | }
160 | catch (InterruptedException e) {
161 | // Roll back: unlock the locks acquired so far...
162 | unlockAll(stack);
163 | throw e;
164 | }
165 | if (!success) {
166 | // Roll back: unlock the locks acquired so far...
167 | unlockAll(stack);
168 | }
169 | return success;
170 | }
171 |
172 | /**
173 | * Calls {@link java.util.concurrent.locks.Lock#unlock()} on all locks provided by the given iterable, in the
174 | * order provided by the iterable. Note you may therefore wish to supply locks in reverse order.
175 | *
176 | * @param locks The locks to unlock
177 | * @param Type of the lock
178 | */
179 | public static void unlockAll(Iterable locks) {
180 | for (L lock : locks) {
181 | lock.unlock();
182 | }
183 | }
184 |
185 | // ***************************
186 | // *** Varargs variants... ***
187 | // ***************************
188 |
189 | /**
190 | * Varargs variant of {@link #lockAll(Iterable)}
191 | * @see #lockAll(Iterable)
192 | */
193 | @SuppressWarnings({"JavaDoc"})
194 | public static void lockAll(L... locks) {
195 | lockAll(Arrays.asList(locks));
196 | }
197 |
198 | /**
199 | * Varargs variant of {@link #lockInterruptiblyAll(Iterable)}
200 | * @see #lockInterruptiblyAll(Iterable)
201 | */
202 | @SuppressWarnings({"JavaDoc"})
203 | public static void lockInterruptiblyAll(L... locks) throws InterruptedException {
204 | lockInterruptiblyAll(Arrays.asList(locks));
205 | }
206 |
207 | /**
208 | * Varargs variant of {@link #tryLockAll(Iterable)}
209 | * @see #tryLockAll(Iterable)
210 | */
211 | @SuppressWarnings({"JavaDoc"})
212 | public static boolean tryLockAll(L... locks) {
213 | return tryLockAll(Arrays.asList(locks));
214 | }
215 |
216 | /**
217 | * Varargs variant of {@link #tryLockAll(long, java.util.concurrent.TimeUnit, Iterable)}
218 | * @see #tryLockAll(long, java.util.concurrent.TimeUnit, Iterable)
219 | */
220 | @SuppressWarnings({"JavaDoc"})
221 | public static boolean tryLockAll(long time, TimeUnit unit, L... locks) throws InterruptedException {
222 | return tryLockAll(time, unit, Arrays.asList(locks));
223 | }
224 |
225 | /**
226 | * Varargs variant of {@link #unlockAll(Iterable)}
227 | * @see #unlockAll(Iterable)
228 | */
229 | @SuppressWarnings({"JavaDoc"})
230 | public static void unlockAll(L... locks) {
231 | unlockAll(Arrays.asList(locks));
232 | }
233 |
234 | /**
235 | * Private constructor, not used.
236 | */
237 | Locks() {
238 | }
239 | }
240 |
--------------------------------------------------------------------------------
/archive/googlecode-tags/1.0.0/src/main/java/com/googlecode/concurentlocks/Locks.java:
--------------------------------------------------------------------------------
1 | /**
2 | * Copyright 2013 Niall Gallagher
3 | *
4 | * Licensed under the Apache License, Version 2.0 (the "License");
5 | * you may not use this file except in compliance with the License.
6 | * You may obtain a copy of the License at
7 | *
8 | * http://www.apache.org/licenses/LICENSE-2.0
9 | *
10 | * Unless required by applicable law or agreed to in writing, software
11 | * distributed under the License is distributed on an "AS IS" BASIS,
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | * See the License for the specific language governing permissions and
14 | * limitations under the License.
15 | */
16 | package com.googlecode.concurentlocks;
17 |
18 | import java.util.*;
19 | import java.util.concurrent.TimeUnit;
20 | import java.util.concurrent.locks.Lock;
21 |
22 | /**
23 | * Utility methods to group-lock and group-unlock collections of locks, including roll back support to
24 | * ensure that either all locks are acquired or no locks are acquired.
25 | *
26 | * @author Niall Gallagher
27 | */
28 | public class Locks {
29 |
30 | /**
31 | * Calls {@link java.util.concurrent.locks.Lock#lock()} on all locks provided by the given iterable, in the order
32 | * provided by the iterable. Automatically releases any locks acquired (in reverse order) by calling
33 | * {@link java.util.concurrent.locks.Lock#unlock()} if an exception is thrown, before re-throwing the exception.
34 | *
35 | * @param locks The locks to acquire
36 | * @param Type of the lock
37 | */
38 | public static void lockAll(Iterable locks) {
39 | Deque stack = new LinkedList();
40 | try {
41 | for (L lock : locks) {
42 | lock.lock();
43 | stack.push(lock);
44 | }
45 | }
46 | catch (RuntimeException e) {
47 | // Roll back: unlock the locks acquired so far...
48 | unlockAll(stack);
49 | throw e;
50 | }
51 | }
52 |
53 | /**
54 | * Calls {@link java.util.concurrent.locks.Lock#lockInterruptibly()} on all locks provided by the given iterable, in
55 | * the order provided by the iterable. Automatically releases any locks acquired (in reverse order) by calling
56 | * {@link java.util.concurrent.locks.Lock#unlock()} if the thread is interrupted while waiting for a lock or if
57 | * an exception is thrown, before re-throwing the exception.
58 | *
59 | * @param locks The locks to acquire
60 | * @param Type of the lock
61 | * @throws InterruptedException If the thread is interrupted while waiting for a lock
62 | */
63 | public static void lockInterruptiblyAll(Iterable locks) throws InterruptedException {
64 | Deque stack = new LinkedList();
65 | try {
66 | for (L lock : locks) {
67 | lock.lockInterruptibly();
68 | stack.push(lock);
69 | }
70 | }
71 | catch (InterruptedException e) {
72 | // Roll back: unlock the locks acquired so far...
73 | unlockAll(stack);
74 | throw e;
75 | }
76 | catch (RuntimeException e) {
77 | // Roll back: unlock the locks acquired so far...
78 | unlockAll(stack);
79 | throw e;
80 | }
81 | }
82 |
83 | /**
84 | * Calls {@link java.util.concurrent.locks.Lock#tryLock()} on all locks provided by the given iterable, in the order
85 | * provided by the iterable. Automatically releases any locks acquired (in reverse order) by calling
86 | * {@link java.util.concurrent.locks.Lock#unlock()} if it is not possible to obtain any lock, if the thread is
87 | * interrupted while waiting for a lock, or if an exception is thrown, before re-throwing the exception.
88 | *
89 | * @param locks The locks to acquire
90 | * @param Type of the lock
91 | * @return True if at least one lock was supplied and all supplied locks were acquired successfully, otherwise false
92 | */
93 | public static boolean tryLockAll(Iterable locks) {
94 | Deque stack = new LinkedList();
95 | boolean success = false;
96 | try {
97 | for (L lock : locks) {
98 | success = lock.tryLock();
99 | if (success) {
100 | stack.push(lock);
101 | }
102 | else {
103 | break;
104 | }
105 | }
106 | }
107 | catch (RuntimeException e) {
108 | // Roll back: unlock the locks acquired so far...
109 | unlockAll(stack);
110 | throw e;
111 | }
112 | if (!success) {
113 | // Roll back: unlock the locks acquired so far...
114 | unlockAll(stack);
115 | }
116 | return success;
117 | }
118 |
119 | /**
120 | * Calls {@link java.util.concurrent.locks.Lock#tryLock()} on all locks provided by the given iterable, in the order
121 | * provided by the iterable. Automatically releases any locks acquired (in reverse order) by calling
122 | * {@link java.util.concurrent.locks.Lock#unlock()} if it is not possible to obtain any lock within the remaining
123 | * time within the timeout given, if the thread is interrupted while waiting for a lock, or if an exception is
124 | * thrown, before re-throwing the exception.
125 | *
126 | * @param time the maximum time to wait for all locks combined
127 | * @param unit the time unit of the {@code time} argument
128 | * @param locks The locks to acquire
129 | * @param Type of the lock
130 | * @return True if at least one lock was supplied and all supplied locks were acquired successfully, otherwise false
131 | * @throws InterruptedException If the thread is interrupted while waiting for a lock
132 | */
133 | public static boolean tryLockAll(long time, TimeUnit unit, Iterable locks) throws InterruptedException {
134 | Deque stack = new LinkedList();
135 | boolean success = false;
136 | try {
137 | long limitNanos = unit.toNanos(time);
138 | long startNanos = System.nanoTime();
139 | for (L lock : locks) {
140 | long remainingNanos = !success
141 | ? limitNanos // No need to calculate remaining time in first iteration
142 | : limitNanos - (System.nanoTime() - startNanos); // recalculate in subsequent iterations
143 |
144 | // Note if remaining time is <= 0, we still try to obtain additional locks, supplying zero or negative
145 | // timeouts to those locks, which should treat it as a non-blocking tryLock() per API docs...
146 | success = lock.tryLock(remainingNanos, TimeUnit.NANOSECONDS);
147 | if (success) {
148 | stack.push(lock);
149 | }
150 | else {
151 | break;
152 | }
153 | }
154 | }
155 | catch (RuntimeException e) {
156 | // Roll back: unlock the locks acquired so far...
157 | unlockAll(stack);
158 | throw e;
159 | }
160 | catch (InterruptedException e) {
161 | // Roll back: unlock the locks acquired so far...
162 | unlockAll(stack);
163 | throw e;
164 | }
165 | if (!success) {
166 | // Roll back: unlock the locks acquired so far...
167 | unlockAll(stack);
168 | }
169 | return success;
170 | }
171 |
172 | /**
173 | * Calls {@link java.util.concurrent.locks.Lock#unlock()} on all locks provided by the given iterable, in the
174 | * order provided by the iterable. Note you may therefore wish to supply locks in reverse order.
175 | *
176 | * @param locks The locks to unlock
177 | * @param Type of the lock
178 | */
179 | public static void unlockAll(Iterable locks) {
180 | for (L lock : locks) {
181 | lock.unlock();
182 | }
183 | }
184 |
185 | // ***************************
186 | // *** Varargs variants... ***
187 | // ***************************
188 |
189 | /**
190 | * Varargs variant of {@link #lockAll(Iterable)}
191 | * @see #lockAll(Iterable)
192 | */
193 | @SuppressWarnings({"JavaDoc"})
194 | public static void lockAll(L... locks) {
195 | lockAll(Arrays.asList(locks));
196 | }
197 |
198 | /**
199 | * Varargs variant of {@link #lockInterruptiblyAll(Iterable)}
200 | * @see #lockInterruptiblyAll(Iterable)
201 | */
202 | @SuppressWarnings({"JavaDoc"})
203 | public static void lockInterruptiblyAll(L... locks) throws InterruptedException {
204 | lockInterruptiblyAll(Arrays.asList(locks));
205 | }
206 |
207 | /**
208 | * Varargs variant of {@link #tryLockAll(Iterable)}
209 | * @see #tryLockAll(Iterable)
210 | */
211 | @SuppressWarnings({"JavaDoc"})
212 | public static boolean tryLockAll(L... locks) {
213 | return tryLockAll(Arrays.asList(locks));
214 | }
215 |
216 | /**
217 | * Varargs variant of {@link #tryLockAll(long, java.util.concurrent.TimeUnit, Iterable)}
218 | * @see #tryLockAll(long, java.util.concurrent.TimeUnit, Iterable)
219 | */
220 | @SuppressWarnings({"JavaDoc"})
221 | public static boolean tryLockAll(long time, TimeUnit unit, L... locks) throws InterruptedException {
222 | return tryLockAll(time, unit, Arrays.asList(locks));
223 | }
224 |
225 | /**
226 | * Varargs variant of {@link #unlockAll(Iterable)}
227 | * @see #unlockAll(Iterable)
228 | */
229 | @SuppressWarnings({"JavaDoc"})
230 | public static void unlockAll(L... locks) {
231 | unlockAll(Arrays.asList(locks));
232 | }
233 |
234 | /**
235 | * Private constructor, not used.
236 | */
237 | Locks() {
238 | }
239 | }
240 |
--------------------------------------------------------------------------------
/code/src/main/java/com/googlecode/concurentlocks/ReentrantReadWriteUpdateLock.java:
--------------------------------------------------------------------------------
1 | /**
2 | * Copyright 2013 Niall Gallagher
3 | *
4 | * Licensed under the Apache License, Version 2.0 (the "License");
5 | * you may not use this file except in compliance with the License.
6 | * You may obtain a copy of the License at
7 | *
8 | * http://www.apache.org/licenses/LICENSE-2.0
9 | *
10 | * Unless required by applicable law or agreed to in writing, software
11 | * distributed under the License is distributed on an "AS IS" BASIS,
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | * See the License for the specific language governing permissions and
14 | * limitations under the License.
15 | */
16 | package com.googlecode.concurentlocks;
17 |
18 | import java.util.concurrent.TimeUnit;
19 | import java.util.concurrent.locks.*;
20 |
21 | /**
22 | * An implementation of {@link ReadWriteUpdateLock}, extending the functionality of the JDK
23 | * {@link ReentrantReadWriteLock} with an update lock in addition to the read and write lock, supporting upgrade
24 | * from read-only operation to writing status, and downgrade again.
25 | *
26 | *
Background - JDK ReentrantReadWriteLock
27 | * The ReentrantReadWriteLock in the JDK classifies threads as needing to read-without-write,
28 | * write-without-read, or write-before-read. Threads can obtain the read lock, or the write lock, and if
29 | * they have the write lock, they can downgrade it to a read lock. But the key limitation is that it does not support
30 | * read-before-write: threads which hold a read lock cannot upgrade it to a write lock.
31 | *
32 | * Imagine a data structure, let's say a cache, where most requests are to read data, but also there is a maintenance
33 | * thread responsible for periodically traversing the data structure to find and update stale entries. The maintenance
34 | * thread thus would mostly read entries while traversing the data structure, and periodically it might encounter
35 | * entries which need to be updated.
36 | *
37 | * If a classic ReentrantReadWriteLock is used to control access, the write-before-read support afforded by that lock
38 | * would be insufficient, because if at any point the thread updated an entry and then downgraded its write lock to a
39 | * read lock, it would not be able to upgrade it again to a write lock if it found other stale entries. So the
40 | * maintenance thread would need to hold the write lock for its entire traversal of the data structure, preventing read
41 | * access for that entire duration.
42 | *
43 | *
ReentrantReadWriteUpdateLock Overview
44 | * The third type of lock provided, an update lock, is like a super read lock. It behaves like a read lock, in that it
45 | * allows read access to the thread which holds it, and it concurrently "plays nice" with other threads which hold
46 | * regular read locks, allowing those threads concurrent read access.
47 | *
48 | * The key difference is that the update lock can be upgraded from its read-only status, to a write lock. Thus it
49 | * supports read-before-write usage. Also the write lock can be downgraded again to an update lock, write-before-read
50 | * usage. A restriction however is that, similar to the write lock, only one thread may acquire the update lock at a
51 | * time.
52 | *
53 | * This is sufficient in situations like the example above, to allow read-mostly, write-occasionally threads to operate
54 | * on the data structure without blocking access to read-only threads most of the time: upgrading to the write lock only
55 | * for the short periods in which they need it, before downgrading to the update lock again. As such it can reduce the
56 | * latency for read-only requests, and increase concurrency in applications which otherwise would use a read-write lock.
57 | *
58 | *
65 | * * An IllegalStateException will be thrown if a thread holding a regular read lock tries to acquire the
66 | * update or write lock, or if a thread holding the update or write lock tries to acquire a regular read lock.
67 | *
68 | * @author Niall Gallagher
69 | */
70 | public class ReentrantReadWriteUpdateLock implements ReadWriteUpdateLock {
71 |
72 | final ReadWriteLock readWriteLock = new ReentrantReadWriteLock(true);
73 | final Lock updateMutex = new ReentrantLock();
74 |
75 | final ReadLock readLock = new ReadLock();
76 | final UpdateLock updateLock = new UpdateLock();
77 | final WriteLock writeLock = new WriteLock();
78 |
79 | @Override
80 | public Lock updateLock() {
81 | return updateLock;
82 | }
83 |
84 | @Override
85 | public Lock readLock() {
86 | return readLock;
87 | }
88 |
89 | @Override
90 | public Lock writeLock() {
91 | return writeLock;
92 | }
93 |
94 | static abstract class HoldCountLock implements Lock {
95 |
96 | static class HoldCount { int value; }
97 |
98 | final ThreadLocal threadHoldCount = new ThreadLocal() {
99 | @Override
100 | protected HoldCount initialValue() {
101 | return new HoldCount();
102 | }
103 | };
104 |
105 | final Lock backingLock;
106 |
107 | public HoldCountLock(Lock backingLock) {
108 | this.backingLock = backingLock;
109 | }
110 |
111 | HoldCount holdCount() {
112 | return threadHoldCount.get();
113 | }
114 |
115 | @Override
116 | public void lock() {
117 | validatePreconditions();
118 | backingLock.lock();
119 | holdCount().value++;
120 | }
121 |
122 | @Override
123 | public void lockInterruptibly() throws InterruptedException {
124 | validatePreconditions();
125 | backingLock.lockInterruptibly();
126 | holdCount().value++;
127 | }
128 |
129 | @Override
130 | public boolean tryLock() {
131 | validatePreconditions();
132 | if (backingLock.tryLock()) {
133 | holdCount().value++;
134 | return true;
135 | }
136 | return false;
137 | }
138 |
139 | @Override
140 | public boolean tryLock(long time, TimeUnit unit) throws InterruptedException {
141 | validatePreconditions();
142 | if (backingLock.tryLock(time, unit)) {
143 | holdCount().value++;
144 | return true;
145 | }
146 | return false;
147 | }
148 |
149 | @Override
150 | public void unlock() {
151 | backingLock.unlock();
152 | holdCount().value--;
153 | }
154 |
155 | @Override
156 | public Condition newCondition() {
157 | throw new UnsupportedOperationException("This lock does not support conditions");
158 | }
159 |
160 | abstract void validatePreconditions();
161 | }
162 |
163 | class ReadLock extends HoldCountLock {
164 |
165 | public ReadLock() {
166 | super(readWriteLock.readLock());
167 | }
168 |
169 | void validatePreconditions() {
170 | if (updateLock.holdCount().value > 0) {
171 | throw new IllegalStateException("Cannot acquire read lock, as this thread previously acquired and must first release the update lock");
172 | }
173 | }
174 | }
175 |
176 | class UpdateLock extends HoldCountLock {
177 |
178 | public UpdateLock() {
179 | super(updateMutex);
180 | }
181 |
182 | void validatePreconditions() {
183 | if (readLock.holdCount().value > 0) {
184 | throw new IllegalStateException("Cannot acquire update lock, as this thread previously acquired and must first release the read lock");
185 | }
186 | }
187 | }
188 |
189 | class WriteLock implements Lock {
190 |
191 | @Override
192 | public void lock() {
193 | validatePreconditions();
194 | // Acquire UPDATE lock again, even if calling thread might already hold it.
195 | // This allow threads to go from both NONE -> WRITE and from UPDATE -> WRITE.
196 | // This also ensures that only the thread holding the single UPDATE lock,
197 | // can request the WRITE lock...
198 | Locks.lockAll(updateLock, readWriteLock.writeLock());
199 | }
200 |
201 | @Override
202 | public void lockInterruptibly() throws InterruptedException {
203 | validatePreconditions();
204 | Locks.lockInterruptiblyAll(updateLock, readWriteLock.writeLock());
205 | }
206 |
207 | @Override
208 | public boolean tryLock() {
209 | validatePreconditions();
210 | return Locks.tryLockAll(updateLock, readWriteLock.writeLock());
211 | }
212 |
213 | @Override
214 | public boolean tryLock(long time, TimeUnit unit) throws InterruptedException {
215 | validatePreconditions();
216 | return Locks.tryLockAll(time, unit, updateLock, readWriteLock.writeLock());
217 | }
218 |
219 | @Override
220 | public void unlock() {
221 | Locks.unlockAll(readWriteLock.writeLock(), updateLock);
222 | }
223 |
224 | @Override
225 | public Condition newCondition() {
226 | throw new UnsupportedOperationException("This lock does not support conditions");
227 | }
228 |
229 | void validatePreconditions() {
230 | if (readLock.holdCount().value > 0) {
231 | throw new IllegalStateException("Cannot acquire write lock, as this thread previously acquired and must first release the read lock");
232 | }
233 | }
234 | }
235 | }
236 |
--------------------------------------------------------------------------------
/archive/googlecode-tags/1.0.0/src/main/java/com/googlecode/concurentlocks/ReentrantReadWriteUpdateLock.java:
--------------------------------------------------------------------------------
1 | /**
2 | * Copyright 2013 Niall Gallagher
3 | *
4 | * Licensed under the Apache License, Version 2.0 (the "License");
5 | * you may not use this file except in compliance with the License.
6 | * You may obtain a copy of the License at
7 | *
8 | * http://www.apache.org/licenses/LICENSE-2.0
9 | *
10 | * Unless required by applicable law or agreed to in writing, software
11 | * distributed under the License is distributed on an "AS IS" BASIS,
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | * See the License for the specific language governing permissions and
14 | * limitations under the License.
15 | */
16 | package com.googlecode.concurentlocks;
17 |
18 | import java.util.concurrent.TimeUnit;
19 | import java.util.concurrent.locks.*;
20 |
21 | /**
22 | * An implementation of {@link ReadWriteUpdateLock}, extending the functionality of the JDK
23 | * {@link ReentrantReadWriteLock} with an update lock in addition to the read and write lock, supporting upgrade
24 | * from read-only operation to writing status, and downgrade again.
25 | *
26 | *
Background - JDK ReentrantReadWriteLock
27 | * The ReentrantReadWriteLock in the JDK classifies threads as needing to read-without-write,
28 | * write-without-read, or write-before-read. Threads can obtain the read lock, or the write lock, and if
29 | * they have the write lock, they can downgrade it to a read lock. But the key limitation is that it does not support
30 | * read-before-write: threads which hold a read lock cannot upgrade it to a write lock.
31 | *
32 | * Imagine a data structure, let's say a cache, where most requests are to read data, but also there is a maintenance
33 | * thread responsible for periodically traversing the data structure to find and update stale entries. The maintenance
34 | * thread thus would mostly read entries while traversing the data structure, and periodically it might encounter
35 | * entries which need to be updated.
36 | *
37 | * If a classic ReentrantReadWriteLock is used to control access, the write-before-read support afforded by that lock
38 | * would be insufficient, because if at any point the thread updated an entry and then downgraded its write lock to a
39 | * read lock, it would not be able to upgrade it again to a write lock if it found other stale entries. So the
40 | * maintenance thread would need to hold the write lock for its entire traversal of the data structure, preventing read
41 | * access for that entire duration.
42 | *
43 | *
ReentrantReadWriteUpdateLock Overview
44 | * The third type of lock provided, an update lock, is like a super read lock. It behaves like a read lock, in that it
45 | * allows read access to the thread which holds it, and it concurrently "plays nice" with other threads which hold
46 | * regular read locks, allowing those threads concurrent read access.
47 | *
48 | * The key difference is that the update lock can be upgraded from its read-only status, to a write lock. Thus it
49 | * supports read-before-write usage. Also the write lock can be downgraded again to an update lock, write-before-read
50 | * usage. A restriction however is that, similar to the write lock, only one thread may acquire the update lock at a
51 | * time.
52 | *
53 | * This is sufficient in situations like the example above, to allow read-mostly, write-occasionally threads to operate
54 | * on the data structure without blocking access to read-only threads most of the time: upgrading to the write lock only
55 | * for the short periods in which they need it, before downgrading to the update lock again. As such it can reduce the
56 | * latency for read-only requests, and increase concurrency in applications which otherwise would use a read-write lock.
57 | *
58 | *
public interface ReadWriteUpdateLock
100 | extends ReadWriteLock
101 |
Extends the JDK ReadWriteLock, providing an update lock in addition to the read lock and the write
102 | lock.
103 |
104 | The update lock supports read-only operations and can coexist with multiple
105 | read locks held simultaneously by other reader threads. However it may also be upgraded from
106 | its read-only status to a write lock, and it may be downgraded again back to a read lock.
107 |
108 | See implementation ReentrantReadWriteUpdateLock for more details.
235 |
236 |
237 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Concurrent-Locks #
2 |
3 | This project provides additional Lock implementations for Java, extending the base functionality and performance provided by the JDK.
4 |
5 | # ReentrantReadWriteUpdateLock #
6 | The [ReentrantReadWriteUpdateLock](http://htmlpreview.github.io/?http://raw.githubusercontent.com/npgall/concurrent-locks/master/documentation/javadoc/apidocs/com/googlecode/concurentlocks/ReentrantReadWriteUpdateLock.html) provided in this project, is like the [ReentrantReadWriteLock](http://docs.oracle.com/javase/6/docs/api/java/util/concurrent/locks/ReentrantReadWriteLock.html) counterpart in the JDK, but in addition to providing a _read_ lock and a _write_ lock, it provides a third option: an _update_ lock.
7 |
8 | Unlike the JDK, this efficiently supports **_read-before-write_ data access patterns**.
9 |
10 | ## Background - JDK ReentrantReadWriteLock ##
11 | The `ReentrantReadWriteLock` in the JDK classifies threads as needing to _read-without-write_, _write-without-read_, or _write-before-read_. Threads can obtain the read lock, or the write lock, and if they have the write lock, they can downgrade it to a read lock. But the key limitation is that it does not support _read-before-write_: threads which hold a read lock cannot upgrade it to a write lock. Thus the JDK `ReentrantReadWriteLock` does not support _read-before-write_ access patterns efficiently.
12 |
13 | Read-before-write is common. Imagine a document (or a resource) where most requests are to read data, but also occasionally the document might need to be updated, which involves reading it in, performing some analysis and alterations to it, then writing out a new version. An efficient lock implementation would minimize the amount of time for which reading threads are blocked, while the document is being updated.
14 |
15 | The only way to provide safe access to the document while it is being updated like this using the `ReentrantReadWriteLock` of the JDK, is for a thread which might update the document (a "writing thread") to do so in three steps:
16 | 1. Acquire the write lock, and only then read the document
17 | 1. Hold the write lock while analyzing and generating a new version of the document
18 | 1. Hold the write lock while writing out the new version
19 |
20 | If the writing thread did not acquire any lock before it got to step 3, and it tried to acquire the write lock only at step 3, then a race condition is possible with other threads doing the same thing, because at step 3 there would be no guarantee that the version each thread had read at step 1 had not already been overwritten with another version by another thread. Performing a write in this case, would be susceptible to the lost update problem, where one thread overwrites changes made by another thread.
21 |
22 | If the writing thread acquired a read lock at step 1, it would be guaranteed that the version of the document it read had not been modified by other threads by the time it got to step 3, but at step 3 it would be unable to acquire the write lock because the JDK `ReentrantReadWriteLock` does not allow the read lock to be upgraded to a write lock.
23 |
24 | So the only solution with the the JDK `ReentrantReadWriteLock`, is for the writing thread to hold the write lock all for three steps of the process, which prevents concurrent read access by other threads for the entire duration, which is needless for steps 1 & 2.
25 |
26 | The following table shows the situations in which a conventional Read-Write lock can needlessly block reading threads in applications with _read-before-write_ access patterns. The extended periods for which reads are blocked, of course will be felt most severely in applications in which reading and writing are long-running operations, in applications where document access has relatively high latency (e.g. across a network), or in applications with high levels of concurrency.
27 |
28 | **Read-before-write access pattern with conventional Read-Write lock**
29 |
30 | | **Step** | **Concurrent reads allowed?** |
31 | |:---------|:------------------------------|
32 | |1. Acquire write lock and read data|NO |
33 | |2. Holding write lock, perform computations on the data|NO |
34 | |3. If new data needs to be written, holding write lock, write new data|NO |
35 | |4. Release write lock|YES |
36 |
37 | ## ReentrantReadWriteUpdateLock Overview ##
38 | The `ReentrantReadWriteUpdateLock` in this project provides a third type of lock, an _update lock_. An update lock is an intermediate type of lock between a read lock and a write lock. Like the write lock, only one thread can acquire an update lock at a time. But like a read lock, it allows read access to the thread which holds it, and concurrently to other threads which hold regular read locks.
39 |
40 | The key feature is that the update lock can be upgraded from its read-only status, to a write lock. Thus it supports _read-before-write_ access patterns efficiently. Also the write lock can be downgraded again to an update lock, supporting _write-before-read_ access patterns efficiently.
41 |
42 | The following table shows the situations in which the Read-Write-Update lock provided in this project can increase concurrency in applications with _read-before-write_ access patterns. It should also be noted that if the writing thread determines that the document does not need to be updated after all, then it does not upgrade to a write lock and so concurrent reads will not be blocked at all.
43 |
44 | **Read-before-write access pattern with Read-Write-Update lock**
45 |
46 | | **Step** | **Concurrent reads allowed?** |
47 | |:---------|:------------------------------|
48 | |1. Acquire update lock and read data|YES |
49 | |2. Holding update lock, perform computations on the data|YES |
50 | |3. If new data needs to be written, upgrade to write lock, write new data|NO |
51 | |4. Release write lock, optionally release update lock|YES |
52 |
53 | **Example Usage - Writing Threads**
54 | ```java
55 | final ReadWriteUpdateLock readWriteUpdateLock = new ReentrantReadWriteUpdateLock();
56 |
57 | public void updateDocumentIfNecessary() {
58 | readWriteUpdateLock.updateLock().lock(); // allows other readers, blocks others from acquiring update or write locks
59 | try {
60 | // STEP 1: Read in the document...
61 | Document currentDocument = readInDocument();
62 | // Decide if document actually needs to be updated...
63 | if (shouldUpdate(currentDocument)) {
64 | // STEP 2: Generate a new version of the document...
65 | Document newVersion = generateNewVersion(currentDocument);
66 | // STEP 3: Write out new version...
67 | readWriteUpdateLock.writeLock().lock(); // upgrade to the write lock, at this point blocks other readers
68 | try {
69 | writeOutDocument(newVersion);
70 | }
71 | finally {
72 | readWriteUpdateLock.writeLock().unlock(); // downgrade back to update lock
73 | }
74 | }
75 | }
76 | finally {
77 | readWriteUpdateLock.updateLock().unlock(); // release update lock
78 | }
79 | }
80 | ```
81 |
82 | **Example Usage - Reading Threads**
83 | ```java
84 | public Document readDocument() {
85 | readWriteUpdateLock.readLock().lock(); // blocks others from acquiring write lock
86 | try {
87 | return readInDocument();
88 | }
89 | finally {
90 | readWriteUpdateLock.readLock().unlock();
91 | }
92 | }
93 | ```
94 |
95 | **Supported Lock Acquisition Paths**
96 |
97 | | **Lock Type** | **Associated Permissions** | **Permitted acquisitions** | **Permitted downgrades** | **Prohibited**|
98 | |:--------------|:---------------------------|:---------------------------|:-------------------------|:----------------------------|
99 | |Read |• Read (shared) |• None → Read • Read → Read (reentrant)|• Read → None |• Read → Update • Read → Write|
100 | |Update |• Read (shared) |• None → Update • Update → Update (reentrant) • Write → Update (reentrant)|• Update → None |• Update → Read |
101 | |Write |• Read (exclusive) • Write (exclusive)|• None → Write • Update → Write • Write → Write (reentrant)|• Write → Update • Write → None|• Write → Read |
102 |
103 |
CompositeLock
104 | A lock spanning a group of backing locks. When locked CompositeLock locks all backing locks. When unlocked, it unlocks all backing locks.
105 |
106 | Ensures that either all backing locks are acquired, or no backing locks are acquired, by applying roll back logic such that failure to acquire any one lock, causes all locks already acquired to be unlocked.
107 |
108 | Lock acquisition methods which take timeouts, are implemented such that the timeout is applied across the acquisition of all locks.
109 |
110 | Locks are unlocked in the reverse of the order in which the were acquired.
111 |
112 |
Utilities
113 | The Locks class provides utility methods which mimic the JDK java.util.concurrent.locks.Lock API, but instead apply those operations on groups of backing locks.
114 |
115 | Provides methods:
116 |
lockAll(Iterable<L> locks)
117 |
lockInterruptiblyAll(Iterable<L> locks)
118 |
tryLockAll(Iterable<L> locks)
119 |
tryLockAll(long time, TimeUnit unit, Iterable<L> locks)
120 |
unlockAll(Iterable<L> locks)
121 |
122 |
Usage in Maven and Non-Maven Projects
123 |
124 | Concurrent-Locks is in Maven Central, and can be added to a Maven project as follows:
125 | ```xml
126 |
127 | com.googlecode.concurrent-locks
128 | concurrent-locks
129 | 1.0.0
130 |
131 | ```
132 |
133 | For non-Maven projects, the library can be downloaded directly from Maven Central [here](http://search.maven.org/remotecontent?filepath=com/googlecode/concurrent-locks/concurrent-locks/).
134 |
135 |
Project Status
136 |
137 | * Development of the library is complete, and all code has 100% test coverage
138 | * The completed library has been deployed to Maven central as version 1.0.0
139 | * There are no known bugs
140 | * For a technical discussion of locks in this project, see the thread on the JDK concurrency-interest mailing list
141 | * API JavaDocs are available here
142 |
143 | Report any bugs/feature requests in the [Issues](http://github.com/npgall/concurrent-locks/issues) tab.
144 | For support please use the Discussion Group, not direct email to the developers.
145 |
--------------------------------------------------------------------------------
/LICENSE.txt:
--------------------------------------------------------------------------------
1 | Apache License
2 | Version 2.0, January 2004
3 | http://www.apache.org/licenses/
4 |
5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6 |
7 | 1. Definitions.
8 |
9 | "License" shall mean the terms and conditions for use, reproduction,
10 | and distribution as defined by Sections 1 through 9 of this document.
11 |
12 | "Licensor" shall mean the copyright owner or entity authorized by
13 | the copyright owner that is granting the License.
14 |
15 | "Legal Entity" shall mean the union of the acting entity and all
16 | other entities that control, are controlled by, or are under common
17 | control with that entity. For the purposes of this definition,
18 | "control" means (i) the power, direct or indirect, to cause the
19 | direction or management of such entity, whether by contract or
20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the
21 | outstanding shares, or (iii) beneficial ownership of such entity.
22 |
23 | "You" (or "Your") shall mean an individual or Legal Entity
24 | exercising permissions granted by this License.
25 |
26 | "Source" form shall mean the preferred form for making modifications,
27 | including but not limited to software source code, documentation
28 | source, and configuration files.
29 |
30 | "Object" form shall mean any form resulting from mechanical
31 | transformation or translation of a Source form, including but
32 | not limited to compiled object code, generated documentation,
33 | and conversions to other media types.
34 |
35 | "Work" shall mean the work of authorship, whether in Source or
36 | Object form, made available under the License, as indicated by a
37 | copyright notice that is included in or attached to the work
38 | (an example is provided in the Appendix below).
39 |
40 | "Derivative Works" shall mean any work, whether in Source or Object
41 | form, that is based on (or derived from) the Work and for which the
42 | editorial revisions, annotations, elaborations, or other modifications
43 | represent, as a whole, an original work of authorship. For the purposes
44 | of this License, Derivative Works shall not include works that remain
45 | separable from, or merely link (or bind by name) to the interfaces of,
46 | the Work and Derivative Works thereof.
47 |
48 | "Contribution" shall mean any work of authorship, including
49 | the original version of the Work and any modifications or additions
50 | to that Work or Derivative Works thereof, that is intentionally
51 | submitted to Licensor for inclusion in the Work by the copyright owner
52 | or by an individual or Legal Entity authorized to submit on behalf of
53 | the copyright owner. For the purposes of this definition, "submitted"
54 | means any form of electronic, verbal, or written communication sent
55 | to the Licensor or its representatives, including but not limited to
56 | communication on electronic mailing lists, source code control systems,
57 | and issue tracking systems that are managed by, or on behalf of, the
58 | Licensor for the purpose of discussing and improving the Work, but
59 | excluding communication that is conspicuously marked or otherwise
60 | designated in writing by the copyright owner as "Not a Contribution."
61 |
62 | "Contributor" shall mean Licensor and any individual or Legal Entity
63 | on behalf of whom a Contribution has been received by Licensor and
64 | subsequently incorporated within the Work.
65 |
66 | 2. Grant of Copyright License. Subject to the terms and conditions of
67 | this License, each Contributor hereby grants to You a perpetual,
68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69 | copyright license to reproduce, prepare Derivative Works of,
70 | publicly display, publicly perform, sublicense, and distribute the
71 | Work and such Derivative Works in Source or Object form.
72 |
73 | 3. Grant of Patent License. Subject to the terms and conditions of
74 | this License, each Contributor hereby grants to You a perpetual,
75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76 | (except as stated in this section) patent license to make, have made,
77 | use, offer to sell, sell, import, and otherwise transfer the Work,
78 | where such license applies only to those patent claims licensable
79 | by such Contributor that are necessarily infringed by their
80 | Contribution(s) alone or by combination of their Contribution(s)
81 | with the Work to which such Contribution(s) was submitted. If You
82 | institute patent litigation against any entity (including a
83 | cross-claim or counterclaim in a lawsuit) alleging that the Work
84 | or a Contribution incorporated within the Work constitutes direct
85 | or contributory patent infringement, then any patent licenses
86 | granted to You under this License for that Work shall terminate
87 | as of the date such litigation is filed.
88 |
89 | 4. Redistribution. You may reproduce and distribute copies of the
90 | Work or Derivative Works thereof in any medium, with or without
91 | modifications, and in Source or Object form, provided that You
92 | meet the following conditions:
93 |
94 | (a) You must give any other recipients of the Work or
95 | Derivative Works a copy of this License; and
96 |
97 | (b) You must cause any modified files to carry prominent notices
98 | stating that You changed the files; and
99 |
100 | (c) You must retain, in the Source form of any Derivative Works
101 | that You distribute, all copyright, patent, trademark, and
102 | attribution notices from the Source form of the Work,
103 | excluding those notices that do not pertain to any part of
104 | the Derivative Works; and
105 |
106 | (d) If the Work includes a "NOTICE" text file as part of its
107 | distribution, then any Derivative Works that You distribute must
108 | include a readable copy of the attribution notices contained
109 | within such NOTICE file, excluding those notices that do not
110 | pertain to any part of the Derivative Works, in at least one
111 | of the following places: within a NOTICE text file distributed
112 | as part of the Derivative Works; within the Source form or
113 | documentation, if provided along with the Derivative Works; or,
114 | within a display generated by the Derivative Works, if and
115 | wherever such third-party notices normally appear. The contents
116 | of the NOTICE file are for informational purposes only and
117 | do not modify the License. You may add Your own attribution
118 | notices within Derivative Works that You distribute, alongside
119 | or as an addendum to the NOTICE text from the Work, provided
120 | that such additional attribution notices cannot be construed
121 | as modifying the License.
122 |
123 | You may add Your own copyright statement to Your modifications and
124 | may provide additional or different license terms and conditions
125 | for use, reproduction, or distribution of Your modifications, or
126 | for any such Derivative Works as a whole, provided Your use,
127 | reproduction, and distribution of the Work otherwise complies with
128 | the conditions stated in this License.
129 |
130 | 5. Submission of Contributions. Unless You explicitly state otherwise,
131 | any Contribution intentionally submitted for inclusion in the Work
132 | by You to the Licensor shall be under the terms and conditions of
133 | this License, without any additional terms or conditions.
134 | Notwithstanding the above, nothing herein shall supersede or modify
135 | the terms of any separate license agreement you may have executed
136 | with Licensor regarding such Contributions.
137 |
138 | 6. Trademarks. This License does not grant permission to use the trade
139 | names, trademarks, service marks, or product names of the Licensor,
140 | except as required for reasonable and customary use in describing the
141 | origin of the Work and reproducing the content of the NOTICE file.
142 |
143 | 7. Disclaimer of Warranty. Unless required by applicable law or
144 | agreed to in writing, Licensor provides the Work (and each
145 | Contributor provides its Contributions) on an "AS IS" BASIS,
146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147 | implied, including, without limitation, any warranties or conditions
148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149 | PARTICULAR PURPOSE. You are solely responsible for determining the
150 | appropriateness of using or redistributing the Work and assume any
151 | risks associated with Your exercise of permissions under this License.
152 |
153 | 8. Limitation of Liability. In no event and under no legal theory,
154 | whether in tort (including negligence), contract, or otherwise,
155 | unless required by applicable law (such as deliberate and grossly
156 | negligent acts) or agreed to in writing, shall any Contributor be
157 | liable to You for damages, including any direct, indirect, special,
158 | incidental, or consequential damages of any character arising as a
159 | result of this License or out of the use or inability to use the
160 | Work (including but not limited to damages for loss of goodwill,
161 | work stoppage, computer failure or malfunction, or any and all
162 | other commercial damages or losses), even if such Contributor
163 | has been advised of the possibility of such damages.
164 |
165 | 9. Accepting Warranty or Additional Liability. While redistributing
166 | the Work or Derivative Works thereof, You may choose to offer,
167 | and charge a fee for, acceptance of support, warranty, indemnity,
168 | or other liability obligations and/or rights consistent with this
169 | License. However, in accepting such obligations, You may act only
170 | on Your own behalf and on Your sole responsibility, not on behalf
171 | of any other Contributor, and only if You agree to indemnify,
172 | defend, and hold each Contributor harmless for any liability
173 | incurred by, or claims asserted against, such Contributor by reason
174 | of your accepting any such warranty or additional liability.
175 |
176 | END OF TERMS AND CONDITIONS
177 |
178 | APPENDIX: How to apply the Apache License to your work.
179 |
180 | To apply the Apache License to your work, attach the following
181 | boilerplate notice, with the fields enclosed by brackets "{}"
182 | replaced with your own identifying information. (Don't include
183 | the brackets!) The text should be enclosed in the appropriate
184 | comment syntax for the file format. We also recommend that a
185 | file or class name and description of purpose be included on the
186 | same "printed page" as the copyright notice for easier
187 | identification within third-party archives.
188 |
189 | Copyright {yyyy} {name of copyright owner}
190 |
191 | Licensed under the Apache License, Version 2.0 (the "License");
192 | you may not use this file except in compliance with the License.
193 | You may obtain a copy of the License at
194 |
195 | http://www.apache.org/licenses/LICENSE-2.0
196 |
197 | Unless required by applicable law or agreed to in writing, software
198 | distributed under the License is distributed on an "AS IS" BASIS,
199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200 | See the License for the specific language governing permissions and
201 | limitations under the License.
202 |
--------------------------------------------------------------------------------
/documentation/javadoc/apidocs/stylesheet.css:
--------------------------------------------------------------------------------
1 | /* Javadoc style sheet */
2 | /*
3 | Overall document style
4 | */
5 | body {
6 | background-color:#ffffff;
7 | color:#353833;
8 | font-family:Arial, Helvetica, sans-serif;
9 | font-size:76%;
10 | margin:0;
11 | }
12 | a:link, a:visited {
13 | text-decoration:none;
14 | color:#4c6b87;
15 | }
16 | a:hover, a:focus {
17 | text-decoration:none;
18 | color:#bb7a2a;
19 | }
20 | a:active {
21 | text-decoration:none;
22 | color:#4c6b87;
23 | }
24 | a[name] {
25 | color:#353833;
26 | }
27 | a[name]:hover {
28 | text-decoration:none;
29 | color:#353833;
30 | }
31 | pre {
32 | font-size:1.3em;
33 | }
34 | h1 {
35 | font-size:1.8em;
36 | }
37 | h2 {
38 | font-size:1.5em;
39 | }
40 | h3 {
41 | font-size:1.4em;
42 | }
43 | h4 {
44 | font-size:1.3em;
45 | }
46 | h5 {
47 | font-size:1.2em;
48 | }
49 | h6 {
50 | font-size:1.1em;
51 | }
52 | ul {
53 | list-style-type:disc;
54 | }
55 | code, tt {
56 | font-size:1.2em;
57 | }
58 | dt code {
59 | font-size:1.2em;
60 | }
61 | table tr td dt code {
62 | font-size:1.2em;
63 | vertical-align:top;
64 | }
65 | sup {
66 | font-size:.6em;
67 | }
68 | /*
69 | Document title and Copyright styles
70 | */
71 | .clear {
72 | clear:both;
73 | height:0px;
74 | overflow:hidden;
75 | }
76 | .aboutLanguage {
77 | float:right;
78 | padding:0px 21px;
79 | font-size:.8em;
80 | z-index:200;
81 | margin-top:-7px;
82 | }
83 | .legalCopy {
84 | margin-left:.5em;
85 | }
86 | .bar a, .bar a:link, .bar a:visited, .bar a:active {
87 | color:#FFFFFF;
88 | text-decoration:none;
89 | }
90 | .bar a:hover, .bar a:focus {
91 | color:#bb7a2a;
92 | }
93 | .tab {
94 | background-color:#0066FF;
95 | background-image:url(resources/titlebar.gif);
96 | background-position:left top;
97 | background-repeat:no-repeat;
98 | color:#ffffff;
99 | padding:8px;
100 | width:5em;
101 | font-weight:bold;
102 | }
103 | /*
104 | Navigation bar styles
105 | */
106 | .bar {
107 | background-image:url(resources/background.gif);
108 | background-repeat:repeat-x;
109 | color:#FFFFFF;
110 | padding:.8em .5em .4em .8em;
111 | height:auto;/*height:1.8em;*/
112 | font-size:1em;
113 | margin:0;
114 | }
115 | .topNav {
116 | background-image:url(resources/background.gif);
117 | background-repeat:repeat-x;
118 | color:#FFFFFF;
119 | float:left;
120 | padding:0;
121 | width:100%;
122 | clear:right;
123 | height:2.8em;
124 | padding-top:10px;
125 | overflow:hidden;
126 | }
127 | .bottomNav {
128 | margin-top:10px;
129 | background-image:url(resources/background.gif);
130 | background-repeat:repeat-x;
131 | color:#FFFFFF;
132 | float:left;
133 | padding:0;
134 | width:100%;
135 | clear:right;
136 | height:2.8em;
137 | padding-top:10px;
138 | overflow:hidden;
139 | }
140 | .subNav {
141 | background-color:#dee3e9;
142 | border-bottom:1px solid #9eadc0;
143 | float:left;
144 | width:100%;
145 | overflow:hidden;
146 | }
147 | .subNav div {
148 | clear:left;
149 | float:left;
150 | padding:0 0 5px 6px;
151 | }
152 | ul.navList, ul.subNavList {
153 | float:left;
154 | margin:0 25px 0 0;
155 | padding:0;
156 | }
157 | ul.navList li{
158 | list-style:none;
159 | float:left;
160 | padding:3px 6px;
161 | }
162 | ul.subNavList li{
163 | list-style:none;
164 | float:left;
165 | font-size:90%;
166 | }
167 | .topNav a:link, .topNav a:active, .topNav a:visited, .bottomNav a:link, .bottomNav a:active, .bottomNav a:visited {
168 | color:#FFFFFF;
169 | text-decoration:none;
170 | }
171 | .topNav a:hover, .bottomNav a:hover {
172 | text-decoration:none;
173 | color:#bb7a2a;
174 | }
175 | .navBarCell1Rev {
176 | background-image:url(resources/tab.gif);
177 | background-color:#a88834;
178 | color:#FFFFFF;
179 | margin: auto 5px;
180 | border:1px solid #c9aa44;
181 | }
182 | /*
183 | Page header and footer styles
184 | */
185 | .header, .footer {
186 | clear:both;
187 | margin:0 20px;
188 | padding:5px 0 0 0;
189 | }
190 | .indexHeader {
191 | margin:10px;
192 | position:relative;
193 | }
194 | .indexHeader h1 {
195 | font-size:1.3em;
196 | }
197 | .title {
198 | color:#2c4557;
199 | margin:10px 0;
200 | }
201 | .subTitle {
202 | margin:5px 0 0 0;
203 | }
204 | .header ul {
205 | margin:0 0 25px 0;
206 | padding:0;
207 | }
208 | .footer ul {
209 | margin:20px 0 5px 0;
210 | }
211 | .header ul li, .footer ul li {
212 | list-style:none;
213 | font-size:1.2em;
214 | }
215 | /*
216 | Heading styles
217 | */
218 | div.details ul.blockList ul.blockList ul.blockList li.blockList h4, div.details ul.blockList ul.blockList ul.blockListLast li.blockList h4 {
219 | background-color:#dee3e9;
220 | border-top:1px solid #9eadc0;
221 | border-bottom:1px solid #9eadc0;
222 | margin:0 0 6px -8px;
223 | padding:2px 5px;
224 | }
225 | ul.blockList ul.blockList ul.blockList li.blockList h3 {
226 | background-color:#dee3e9;
227 | border-top:1px solid #9eadc0;
228 | border-bottom:1px solid #9eadc0;
229 | margin:0 0 6px -8px;
230 | padding:2px 5px;
231 | }
232 | ul.blockList ul.blockList li.blockList h3 {
233 | padding:0;
234 | margin:15px 0;
235 | }
236 | ul.blockList li.blockList h2 {
237 | padding:0px 0 20px 0;
238 | }
239 | /*
240 | Page layout container styles
241 | */
242 | .contentContainer, .sourceContainer, .classUseContainer, .serializedFormContainer, .constantValuesContainer {
243 | clear:both;
244 | padding:10px 20px;
245 | position:relative;
246 | }
247 | .indexContainer {
248 | margin:10px;
249 | position:relative;
250 | font-size:1.0em;
251 | }
252 | .indexContainer h2 {
253 | font-size:1.1em;
254 | padding:0 0 3px 0;
255 | }
256 | .indexContainer ul {
257 | margin:0;
258 | padding:0;
259 | }
260 | .indexContainer ul li {
261 | list-style:none;
262 | }
263 | .contentContainer .description dl dt, .contentContainer .details dl dt, .serializedFormContainer dl dt {
264 | font-size:1.1em;
265 | font-weight:bold;
266 | margin:10px 0 0 0;
267 | color:#4E4E4E;
268 | }
269 | .contentContainer .description dl dd, .contentContainer .details dl dd, .serializedFormContainer dl dd {
270 | margin:10px 0 10px 20px;
271 | }
272 | .serializedFormContainer dl.nameValue dt {
273 | margin-left:1px;
274 | font-size:1.1em;
275 | display:inline;
276 | font-weight:bold;
277 | }
278 | .serializedFormContainer dl.nameValue dd {
279 | margin:0 0 0 1px;
280 | font-size:1.1em;
281 | display:inline;
282 | }
283 | /*
284 | List styles
285 | */
286 | ul.horizontal li {
287 | display:inline;
288 | font-size:0.9em;
289 | }
290 | ul.inheritance {
291 | margin:0;
292 | padding:0;
293 | }
294 | ul.inheritance li {
295 | display:inline;
296 | list-style:none;
297 | }
298 | ul.inheritance li ul.inheritance {
299 | margin-left:15px;
300 | padding-left:15px;
301 | padding-top:1px;
302 | }
303 | ul.blockList, ul.blockListLast {
304 | margin:10px 0 10px 0;
305 | padding:0;
306 | }
307 | ul.blockList li.blockList, ul.blockListLast li.blockList {
308 | list-style:none;
309 | margin-bottom:25px;
310 | }
311 | ul.blockList ul.blockList li.blockList, ul.blockList ul.blockListLast li.blockList {
312 | padding:0px 20px 5px 10px;
313 | border:1px solid #9eadc0;
314 | background-color:#f9f9f9;
315 | }
316 | ul.blockList ul.blockList ul.blockList li.blockList, ul.blockList ul.blockList ul.blockListLast li.blockList {
317 | padding:0 0 5px 8px;
318 | background-color:#ffffff;
319 | border:1px solid #9eadc0;
320 | border-top:none;
321 | }
322 | ul.blockList ul.blockList ul.blockList ul.blockList li.blockList {
323 | margin-left:0;
324 | padding-left:0;
325 | padding-bottom:15px;
326 | border:none;
327 | border-bottom:1px solid #9eadc0;
328 | }
329 | ul.blockList ul.blockList ul.blockList ul.blockList li.blockListLast {
330 | list-style:none;
331 | border-bottom:none;
332 | padding-bottom:0;
333 | }
334 | table tr td dl, table tr td dl dt, table tr td dl dd {
335 | margin-top:0;
336 | margin-bottom:1px;
337 | }
338 | /*
339 | Table styles
340 | */
341 | .contentContainer table, .classUseContainer table, .constantValuesContainer table {
342 | border-bottom:1px solid #9eadc0;
343 | width:100%;
344 | }
345 | .contentContainer ul li table, .classUseContainer ul li table, .constantValuesContainer ul li table {
346 | width:100%;
347 | }
348 | .contentContainer .description table, .contentContainer .details table {
349 | border-bottom:none;
350 | }
351 | .contentContainer ul li table th.colOne, .contentContainer ul li table th.colFirst, .contentContainer ul li table th.colLast, .classUseContainer ul li table th, .constantValuesContainer ul li table th, .contentContainer ul li table td.colOne, .contentContainer ul li table td.colFirst, .contentContainer ul li table td.colLast, .classUseContainer ul li table td, .constantValuesContainer ul li table td{
352 | vertical-align:top;
353 | padding-right:20px;
354 | }
355 | .contentContainer ul li table th.colLast, .classUseContainer ul li table th.colLast,.constantValuesContainer ul li table th.colLast,
356 | .contentContainer ul li table td.colLast, .classUseContainer ul li table td.colLast,.constantValuesContainer ul li table td.colLast,
357 | .contentContainer ul li table th.colOne, .classUseContainer ul li table th.colOne,
358 | .contentContainer ul li table td.colOne, .classUseContainer ul li table td.colOne {
359 | padding-right:3px;
360 | }
361 | .overviewSummary caption, .packageSummary caption, .contentContainer ul.blockList li.blockList caption, .summary caption, .classUseContainer caption, .constantValuesContainer caption {
362 | position:relative;
363 | text-align:left;
364 | background-repeat:no-repeat;
365 | color:#FFFFFF;
366 | font-weight:bold;
367 | clear:none;
368 | overflow:hidden;
369 | padding:0px;
370 | margin:0px;
371 | }
372 | caption a:link, caption a:hover, caption a:active, caption a:visited {
373 | color:#FFFFFF;
374 | }
375 | .overviewSummary caption span, .packageSummary caption span, .contentContainer ul.blockList li.blockList caption span, .summary caption span, .classUseContainer caption span, .constantValuesContainer caption span {
376 | white-space:nowrap;
377 | padding-top:8px;
378 | padding-left:8px;
379 | display:block;
380 | float:left;
381 | background-image:url(resources/titlebar.gif);
382 | height:18px;
383 | }
384 | .overviewSummary .tabEnd, .packageSummary .tabEnd, .contentContainer ul.blockList li.blockList .tabEnd, .summary .tabEnd, .classUseContainer .tabEnd, .constantValuesContainer .tabEnd {
385 | width:10px;
386 | background-image:url(resources/titlebar_end.gif);
387 | background-repeat:no-repeat;
388 | background-position:top right;
389 | position:relative;
390 | float:left;
391 | }
392 | ul.blockList ul.blockList li.blockList table {
393 | margin:0 0 12px 0px;
394 | width:100%;
395 | }
396 | .tableSubHeadingColor {
397 | background-color: #EEEEFF;
398 | }
399 | .altColor {
400 | background-color:#eeeeef;
401 | }
402 | .rowColor {
403 | background-color:#ffffff;
404 | }
405 | .overviewSummary td, .packageSummary td, .contentContainer ul.blockList li.blockList td, .summary td, .classUseContainer td, .constantValuesContainer td {
406 | text-align:left;
407 | padding:3px 3px 3px 7px;
408 | }
409 | th.colFirst, th.colLast, th.colOne, .constantValuesContainer th {
410 | background:#dee3e9;
411 | border-top:1px solid #9eadc0;
412 | border-bottom:1px solid #9eadc0;
413 | text-align:left;
414 | padding:3px 3px 3px 7px;
415 | }
416 | td.colOne a:link, td.colOne a:active, td.colOne a:visited, td.colOne a:hover, td.colFirst a:link, td.colFirst a:active, td.colFirst a:visited, td.colFirst a:hover, td.colLast a:link, td.colLast a:active, td.colLast a:visited, td.colLast a:hover, .constantValuesContainer td a:link, .constantValuesContainer td a:active, .constantValuesContainer td a:visited, .constantValuesContainer td a:hover {
417 | font-weight:bold;
418 | }
419 | td.colFirst, th.colFirst {
420 | border-left:1px solid #9eadc0;
421 | white-space:nowrap;
422 | }
423 | td.colLast, th.colLast {
424 | border-right:1px solid #9eadc0;
425 | }
426 | td.colOne, th.colOne {
427 | border-right:1px solid #9eadc0;
428 | border-left:1px solid #9eadc0;
429 | }
430 | table.overviewSummary {
431 | padding:0px;
432 | margin-left:0px;
433 | }
434 | table.overviewSummary td.colFirst, table.overviewSummary th.colFirst,
435 | table.overviewSummary td.colOne, table.overviewSummary th.colOne {
436 | width:25%;
437 | vertical-align:middle;
438 | }
439 | table.packageSummary td.colFirst, table.overviewSummary th.colFirst {
440 | width:25%;
441 | vertical-align:middle;
442 | }
443 | /*
444 | Content styles
445 | */
446 | .description pre {
447 | margin-top:0;
448 | }
449 | .deprecatedContent {
450 | margin:0;
451 | padding:10px 0;
452 | }
453 | .docSummary {
454 | padding:0;
455 | }
456 | /*
457 | Formatting effect styles
458 | */
459 | .sourceLineNo {
460 | color:green;
461 | padding:0 30px 0 0;
462 | }
463 | h1.hidden {
464 | visibility:hidden;
465 | overflow:hidden;
466 | font-size:.9em;
467 | }
468 | .block {
469 | display:block;
470 | margin:3px 0 0 0;
471 | }
472 | .strong {
473 | font-weight:bold;
474 | }
475 |
--------------------------------------------------------------------------------
/code/src/test/java/com/googlecode/concurentlocks/LocksTest.java:
--------------------------------------------------------------------------------
1 | /**
2 | * Copyright 2013 Niall Gallagher
3 | *
4 | * Licensed under the Apache License, Version 2.0 (the "License");
5 | * you may not use this file except in compliance with the License.
6 | * You may obtain a copy of the License at
7 | *
8 | * http://www.apache.org/licenses/LICENSE-2.0
9 | *
10 | * Unless required by applicable law or agreed to in writing, software
11 | * distributed under the License is distributed on an "AS IS" BASIS,
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | * See the License for the specific language governing permissions and
14 | * limitations under the License.
15 | */
16 | package com.googlecode.concurentlocks;
17 |
18 | import org.junit.Test;
19 |
20 | import java.util.concurrent.*;
21 | import java.util.concurrent.atomic.AtomicBoolean;
22 | import java.util.concurrent.atomic.AtomicLong;
23 | import java.util.concurrent.locks.Lock;
24 | import java.util.concurrent.locks.ReentrantLock;
25 |
26 | import static org.junit.Assert.*;
27 |
28 | /**
29 | * @author Niall Gallagher
30 | */
31 | public class LocksTest {
32 |
33 | @Test
34 | public void testLockAll() throws Exception {
35 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock());
36 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock());
37 |
38 | Locks.lockAll(lock1, lock2);
39 | assertEquals(1, lock1.holdCount().value);
40 | assertEquals(1, lock2.holdCount().value);
41 | }
42 |
43 | @Test
44 | public void testLockAll_Rollback() throws Exception {
45 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock());
46 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock()) {
47 | @Override
48 | public void lock() {
49 | throw new RuntimeException();
50 | }
51 | };
52 | Exception expected = null;
53 | try {
54 | Locks.lockAll(lock1, lock2);
55 | }
56 | catch (RuntimeException e) {
57 | expected = e;
58 | }
59 | assertNotNull(expected);
60 | assertEquals(0, lock1.holdCount().value);
61 | assertEquals(0, lock2.holdCount().value);
62 | }
63 |
64 | @Test
65 | public void testLockInterruptiblyAll() throws Exception {
66 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock());
67 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock());
68 |
69 | Locks.lockInterruptiblyAll(lock1, lock2);
70 | assertEquals(1, lock1.holdCount().value);
71 | assertEquals(1, lock2.holdCount().value);
72 | }
73 |
74 | @Test
75 | public void testLockInterruptiblyAll_RollbackOnRuntimeException() throws Exception {
76 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock());
77 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock()) {
78 | @Override
79 | public void lockInterruptibly() throws InterruptedException {
80 | throw new RuntimeException();
81 | }
82 | };
83 | Exception expected = null;
84 | try {
85 | Locks.lockInterruptiblyAll(lock1, lock2);
86 | }
87 | catch (RuntimeException e) {
88 | expected = e;
89 | }
90 | assertNotNull(expected);
91 | assertEquals(0, lock1.holdCount().value);
92 | assertEquals(0, lock2.holdCount().value);
93 | }
94 |
95 | @Test
96 | public void testLockInterruptiblyAll_RollbackOnInterruptedException() throws Exception {
97 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock());
98 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock()) {
99 | @Override
100 | public void lockInterruptibly() throws InterruptedException {
101 | throw new InterruptedException();
102 | }
103 | };
104 | Exception expected = null;
105 | try {
106 | Locks.lockInterruptiblyAll(lock1, lock2);
107 | }
108 | catch (InterruptedException e) {
109 | expected = e;
110 | }
111 | assertNotNull(expected);
112 | assertEquals(0, lock1.holdCount().value);
113 | assertEquals(0, lock2.holdCount().value);
114 | }
115 |
116 | @Test
117 | public void testTryLockAll() throws Exception {
118 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock());
119 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock());
120 |
121 | boolean acquired = Locks.tryLockAll(lock1, lock2);
122 | assertTrue(acquired);
123 | assertEquals(1, lock1.holdCount().value);
124 | assertEquals(1, lock2.holdCount().value);
125 | }
126 |
127 | @Test
128 | public void testTryLockAll_RollbackOnFailure() throws Exception {
129 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock());
130 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock()) {
131 | @Override
132 | public boolean tryLock() {
133 | return false;
134 | }
135 | };
136 |
137 | boolean acquired = Locks.tryLockAll(lock1, lock2);
138 | assertFalse(acquired);
139 | assertEquals(0, lock1.holdCount().value);
140 | assertEquals(0, lock2.holdCount().value);
141 | }
142 |
143 | @Test
144 | public void testTryLockAll_RollbackOnException() throws Exception {
145 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock());
146 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock()) {
147 | @Override
148 | public boolean tryLock() {
149 | throw new RuntimeException();
150 | }
151 | };
152 |
153 | Exception expected = null;
154 | try {
155 | Locks.tryLockAll(lock1, lock2);
156 | }
157 | catch (RuntimeException e) {
158 | expected = e;
159 | }
160 | assertNotNull(expected);
161 | assertEquals(0, lock1.holdCount().value);
162 | assertEquals(0, lock2.holdCount().value);
163 | }
164 |
165 | @Test
166 | public void testTryLockAllWithTimeout() throws Exception {
167 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock());
168 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock());
169 |
170 | boolean acquired = Locks.tryLockAll(1L, TimeUnit.MILLISECONDS, lock1, lock2);
171 | assertTrue(acquired);
172 | assertEquals(1, lock1.holdCount().value);
173 | assertEquals(1, lock2.holdCount().value);
174 | }
175 |
176 | @Test
177 | public void testTryLockAllWithTimeout_RollbackOnFailure() throws Exception {
178 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock());
179 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock()) {
180 | @Override
181 | public boolean tryLock(long time, TimeUnit unit) throws InterruptedException {
182 | return false;
183 | }
184 | };
185 |
186 | boolean acquired = Locks.tryLockAll(1L, TimeUnit.MILLISECONDS, lock1, lock2);
187 | assertFalse(acquired);
188 | assertEquals(0, lock1.holdCount().value);
189 | assertEquals(0, lock2.holdCount().value);
190 | }
191 |
192 | @Test
193 | public void testTryLockAllWithTimeout_RollbackOnRuntimeException() throws Exception {
194 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock());
195 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock()) {
196 | @Override
197 | public boolean tryLock(long time, TimeUnit unit) throws InterruptedException {
198 | throw new RuntimeException();
199 | }
200 | };
201 |
202 | Exception expected = null;
203 | try {
204 | Locks.tryLockAll(1L, TimeUnit.MILLISECONDS, lock1, lock2);
205 | }
206 | catch (RuntimeException e) {
207 | expected = e;
208 | }
209 | assertNotNull(expected);
210 | assertEquals(0, lock1.holdCount().value);
211 | assertEquals(0, lock2.holdCount().value);
212 | }
213 |
214 | @Test
215 | public void testTryLockAllWithTimeout_RollbackOnInterruptedException() throws Exception {
216 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock());
217 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock()) {
218 | @Override
219 | public boolean tryLock(long time, TimeUnit unit) throws InterruptedException {
220 | throw new InterruptedException();
221 | }
222 | };
223 |
224 | Exception expected = null;
225 | try {
226 | Locks.tryLockAll(1L, TimeUnit.MILLISECONDS, lock1, lock2);
227 | }
228 | catch (InterruptedException e) {
229 | expected = e;
230 | }
231 | assertNotNull(expected);
232 | assertEquals(0, lock1.holdCount().value);
233 | assertEquals(0, lock2.holdCount().value);
234 | }
235 |
236 | @Test
237 | public void testTryLockAllWithTimeout_TimeoutSpansAllAcquisitions() throws Exception {
238 | // Acquire a lock in a background thread so that it is never available to foreground thread...
239 | final ReentrantLock unavailableLock = new ReentrantLock();
240 | ExecutorService executor = Executors.newSingleThreadExecutor();
241 | assertTrue(executor.submit(new ReentrantReadWriteUpdateLockTest.TryLockTask(unavailableLock)).get());
242 | try {
243 | // Set up lock1.
244 | // Should acquire lock1, even though in doing so we use more time than timeout allows...
245 | final AtomicBoolean lock1WasInitiallyAcquired = new AtomicBoolean();
246 | final AtomicLong timeoutSuppliedToLock1 = new AtomicLong(Long.MIN_VALUE);
247 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock()){
248 | @Override
249 | public boolean tryLock(long time, TimeUnit unit) throws InterruptedException {
250 | timeoutSuppliedToLock1.set(unit.toNanos(time)); // A positive timeout should be supplied to this lock
251 | boolean acquired = super.tryLock(time, unit);
252 | lock1WasInitiallyAcquired.set(acquired);
253 | Thread.sleep(1000); // Sleep for longer than overall timeout
254 | return acquired;
255 | }
256 | };
257 |
258 | // Set up lock2.
259 | // Should acquire lock2, because even though timeout expired it's available without blocking...
260 | final AtomicBoolean lock2WasInitiallyAcquired = new AtomicBoolean();
261 | final AtomicLong timeoutSuppliedToLock2 = new AtomicLong(Long.MAX_VALUE);
262 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock()){
263 | @Override
264 | public boolean tryLock(long time, TimeUnit unit) throws InterruptedException {
265 | timeoutSuppliedToLock2.set(unit.toNanos(time)); // A negative timeout should be supplied to this lock
266 | boolean acquired = super.tryLock(time, unit); // Should succeed as no need to wait
267 | lock2WasInitiallyAcquired.set(acquired);
268 | return acquired;
269 | }
270 | };
271 |
272 | // Set up lock3.
273 | // Should fail to acquire lock3, because it's unavailable and it can't block as timeout expired...
274 | final AtomicBoolean lock3WasInitiallyAcquired = new AtomicBoolean();
275 | final AtomicLong timeoutSuppliedToLock3 = new AtomicLong(Long.MAX_VALUE);
276 | HoldCountLock lock3 = new HoldCountLock(unavailableLock) {
277 | @Override
278 | public boolean tryLock(long time, TimeUnit unit) throws InterruptedException {
279 | timeoutSuppliedToLock3.set(unit.toNanos(time)); // A negative timeout should be supplied to this lock
280 | boolean acquired = super.tryLock(time, unit); // Should fail as can't wait due to timeout <= 0
281 | lock3WasInitiallyAcquired.set(acquired);
282 | return acquired;
283 | }
284 | };
285 |
286 | // Now actually try to acquire the locks...
287 | boolean acquired = Locks.tryLockAll(1L, TimeUnit.NANOSECONDS, lock1, lock2, lock3);
288 | // Should fail...
289 | assertFalse(acquired);
290 |
291 | // Lock 1 should have been supplied a positive timeout and it should have been acquired...
292 | assertTrue(timeoutSuppliedToLock1.get() > 0);
293 | assertTrue(lock1WasInitiallyAcquired.get());
294 |
295 | // Lock 2 should have been supplied a negative timeout as lock1 used all of the available time,
296 | // but acquisition should have succeeded anyway because it was uncontended and available without blocking...
297 | assertTrue(timeoutSuppliedToLock2.get() < 0);
298 | assertTrue(lock2WasInitiallyAcquired.get());
299 |
300 | // Lock 3 should have been supplied a negative timeout as lock1 used all of the available time,
301 | // and acquisition should have failed because it was unavailable and could not block due to timeout expired...
302 | assertTrue(timeoutSuppliedToLock3.get() < 0);
303 | assertFalse(lock3WasInitiallyAcquired.get());
304 |
305 | // All locks acquired should have been rolled back due to failure to acquire lock3...
306 | assertEquals(0, lock1.holdCount().value);
307 | assertEquals(0, lock2.holdCount().value);
308 | assertEquals(0, lock3.holdCount().value);
309 | }
310 | finally {
311 | executor.shutdown();
312 | }
313 | }
314 |
315 | @Test
316 | public void testConstructor() {
317 | assertNotNull(new Locks());
318 | }
319 |
320 | static class HoldCountLock extends ReentrantReadWriteUpdateLock.HoldCountLock {
321 |
322 | public HoldCountLock(Lock backingLock) {
323 | super(backingLock);
324 | }
325 |
326 | @Override
327 | void validatePreconditions() {
328 | // No op
329 | }
330 | }
331 | }
332 |
--------------------------------------------------------------------------------
/archive/googlecode-tags/1.0.0/src/test/java/com/googlecode/concurentlocks/LocksTest.java:
--------------------------------------------------------------------------------
1 | /**
2 | * Copyright 2013 Niall Gallagher
3 | *
4 | * Licensed under the Apache License, Version 2.0 (the "License");
5 | * you may not use this file except in compliance with the License.
6 | * You may obtain a copy of the License at
7 | *
8 | * http://www.apache.org/licenses/LICENSE-2.0
9 | *
10 | * Unless required by applicable law or agreed to in writing, software
11 | * distributed under the License is distributed on an "AS IS" BASIS,
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 | * See the License for the specific language governing permissions and
14 | * limitations under the License.
15 | */
16 | package com.googlecode.concurentlocks;
17 |
18 | import org.junit.Test;
19 |
20 | import java.util.concurrent.*;
21 | import java.util.concurrent.atomic.AtomicBoolean;
22 | import java.util.concurrent.atomic.AtomicLong;
23 | import java.util.concurrent.locks.Lock;
24 | import java.util.concurrent.locks.ReentrantLock;
25 |
26 | import static org.junit.Assert.*;
27 |
28 | /**
29 | * @author Niall Gallagher
30 | */
31 | public class LocksTest {
32 |
33 | @Test
34 | public void testLockAll() throws Exception {
35 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock());
36 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock());
37 |
38 | Locks.lockAll(lock1, lock2);
39 | assertEquals(1, lock1.holdCount().value);
40 | assertEquals(1, lock2.holdCount().value);
41 | }
42 |
43 | @Test
44 | public void testLockAll_Rollback() throws Exception {
45 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock());
46 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock()) {
47 | @Override
48 | public void lock() {
49 | throw new RuntimeException();
50 | }
51 | };
52 | Exception expected = null;
53 | try {
54 | Locks.lockAll(lock1, lock2);
55 | }
56 | catch (RuntimeException e) {
57 | expected = e;
58 | }
59 | assertNotNull(expected);
60 | assertEquals(0, lock1.holdCount().value);
61 | assertEquals(0, lock2.holdCount().value);
62 | }
63 |
64 | @Test
65 | public void testLockInterruptiblyAll() throws Exception {
66 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock());
67 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock());
68 |
69 | Locks.lockInterruptiblyAll(lock1, lock2);
70 | assertEquals(1, lock1.holdCount().value);
71 | assertEquals(1, lock2.holdCount().value);
72 | }
73 |
74 | @Test
75 | public void testLockInterruptiblyAll_RollbackOnRuntimeException() throws Exception {
76 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock());
77 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock()) {
78 | @Override
79 | public void lockInterruptibly() throws InterruptedException {
80 | throw new RuntimeException();
81 | }
82 | };
83 | Exception expected = null;
84 | try {
85 | Locks.lockInterruptiblyAll(lock1, lock2);
86 | }
87 | catch (RuntimeException e) {
88 | expected = e;
89 | }
90 | assertNotNull(expected);
91 | assertEquals(0, lock1.holdCount().value);
92 | assertEquals(0, lock2.holdCount().value);
93 | }
94 |
95 | @Test
96 | public void testLockInterruptiblyAll_RollbackOnInterruptedException() throws Exception {
97 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock());
98 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock()) {
99 | @Override
100 | public void lockInterruptibly() throws InterruptedException {
101 | throw new InterruptedException();
102 | }
103 | };
104 | Exception expected = null;
105 | try {
106 | Locks.lockInterruptiblyAll(lock1, lock2);
107 | }
108 | catch (InterruptedException e) {
109 | expected = e;
110 | }
111 | assertNotNull(expected);
112 | assertEquals(0, lock1.holdCount().value);
113 | assertEquals(0, lock2.holdCount().value);
114 | }
115 |
116 | @Test
117 | public void testTryLockAll() throws Exception {
118 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock());
119 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock());
120 |
121 | boolean acquired = Locks.tryLockAll(lock1, lock2);
122 | assertTrue(acquired);
123 | assertEquals(1, lock1.holdCount().value);
124 | assertEquals(1, lock2.holdCount().value);
125 | }
126 |
127 | @Test
128 | public void testTryLockAll_RollbackOnFailure() throws Exception {
129 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock());
130 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock()) {
131 | @Override
132 | public boolean tryLock() {
133 | return false;
134 | }
135 | };
136 |
137 | boolean acquired = Locks.tryLockAll(lock1, lock2);
138 | assertFalse(acquired);
139 | assertEquals(0, lock1.holdCount().value);
140 | assertEquals(0, lock2.holdCount().value);
141 | }
142 |
143 | @Test
144 | public void testTryLockAll_RollbackOnException() throws Exception {
145 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock());
146 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock()) {
147 | @Override
148 | public boolean tryLock() {
149 | throw new RuntimeException();
150 | }
151 | };
152 |
153 | Exception expected = null;
154 | try {
155 | Locks.tryLockAll(lock1, lock2);
156 | }
157 | catch (RuntimeException e) {
158 | expected = e;
159 | }
160 | assertNotNull(expected);
161 | assertEquals(0, lock1.holdCount().value);
162 | assertEquals(0, lock2.holdCount().value);
163 | }
164 |
165 | @Test
166 | public void testTryLockAllWithTimeout() throws Exception {
167 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock());
168 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock());
169 |
170 | boolean acquired = Locks.tryLockAll(1L, TimeUnit.MILLISECONDS, lock1, lock2);
171 | assertTrue(acquired);
172 | assertEquals(1, lock1.holdCount().value);
173 | assertEquals(1, lock2.holdCount().value);
174 | }
175 |
176 | @Test
177 | public void testTryLockAllWithTimeout_RollbackOnFailure() throws Exception {
178 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock());
179 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock()) {
180 | @Override
181 | public boolean tryLock(long time, TimeUnit unit) throws InterruptedException {
182 | return false;
183 | }
184 | };
185 |
186 | boolean acquired = Locks.tryLockAll(1L, TimeUnit.MILLISECONDS, lock1, lock2);
187 | assertFalse(acquired);
188 | assertEquals(0, lock1.holdCount().value);
189 | assertEquals(0, lock2.holdCount().value);
190 | }
191 |
192 | @Test
193 | public void testTryLockAllWithTimeout_RollbackOnRuntimeException() throws Exception {
194 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock());
195 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock()) {
196 | @Override
197 | public boolean tryLock(long time, TimeUnit unit) throws InterruptedException {
198 | throw new RuntimeException();
199 | }
200 | };
201 |
202 | Exception expected = null;
203 | try {
204 | Locks.tryLockAll(1L, TimeUnit.MILLISECONDS, lock1, lock2);
205 | }
206 | catch (RuntimeException e) {
207 | expected = e;
208 | }
209 | assertNotNull(expected);
210 | assertEquals(0, lock1.holdCount().value);
211 | assertEquals(0, lock2.holdCount().value);
212 | }
213 |
214 | @Test
215 | public void testTryLockAllWithTimeout_RollbackOnInterruptedException() throws Exception {
216 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock());
217 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock()) {
218 | @Override
219 | public boolean tryLock(long time, TimeUnit unit) throws InterruptedException {
220 | throw new InterruptedException();
221 | }
222 | };
223 |
224 | Exception expected = null;
225 | try {
226 | Locks.tryLockAll(1L, TimeUnit.MILLISECONDS, lock1, lock2);
227 | }
228 | catch (InterruptedException e) {
229 | expected = e;
230 | }
231 | assertNotNull(expected);
232 | assertEquals(0, lock1.holdCount().value);
233 | assertEquals(0, lock2.holdCount().value);
234 | }
235 |
236 | @Test
237 | public void testTryLockAllWithTimeout_TimeoutSpansAllAcquisitions() throws Exception {
238 | // Acquire a lock in a background thread so that it is never available to foreground thread...
239 | final ReentrantLock unavailableLock = new ReentrantLock();
240 | ExecutorService executor = Executors.newSingleThreadExecutor();
241 | assertTrue(executor.submit(new ReentrantReadWriteUpdateLockTest.TryLockTask(unavailableLock)).get());
242 | try {
243 | // Set up lock1.
244 | // Should acquire lock1, even though in doing so we use more time than timeout allows...
245 | final AtomicBoolean lock1WasInitiallyAcquired = new AtomicBoolean();
246 | final AtomicLong timeoutSuppliedToLock1 = new AtomicLong(Long.MIN_VALUE);
247 | HoldCountLock lock1 = new HoldCountLock(new ReentrantLock()){
248 | @Override
249 | public boolean tryLock(long time, TimeUnit unit) throws InterruptedException {
250 | timeoutSuppliedToLock1.set(unit.toNanos(time)); // A positive timeout should be supplied to this lock
251 | boolean acquired = super.tryLock(time, unit);
252 | lock1WasInitiallyAcquired.set(acquired);
253 | Thread.sleep(1000); // Sleep for longer than overall timeout
254 | return acquired;
255 | }
256 | };
257 |
258 | // Set up lock2.
259 | // Should acquire lock2, because even though timeout expired it's available without blocking...
260 | final AtomicBoolean lock2WasInitiallyAcquired = new AtomicBoolean();
261 | final AtomicLong timeoutSuppliedToLock2 = new AtomicLong(Long.MAX_VALUE);
262 | HoldCountLock lock2 = new HoldCountLock(new ReentrantLock()){
263 | @Override
264 | public boolean tryLock(long time, TimeUnit unit) throws InterruptedException {
265 | timeoutSuppliedToLock2.set(unit.toNanos(time)); // A negative timeout should be supplied to this lock
266 | boolean acquired = super.tryLock(time, unit); // Should succeed as no need to wait
267 | lock2WasInitiallyAcquired.set(acquired);
268 | return acquired;
269 | }
270 | };
271 |
272 | // Set up lock3.
273 | // Should fail to acquire lock3, because it's unavailable and it can't block as timeout expired...
274 | final AtomicBoolean lock3WasInitiallyAcquired = new AtomicBoolean();
275 | final AtomicLong timeoutSuppliedToLock3 = new AtomicLong(Long.MAX_VALUE);
276 | HoldCountLock lock3 = new HoldCountLock(unavailableLock) {
277 | @Override
278 | public boolean tryLock(long time, TimeUnit unit) throws InterruptedException {
279 | timeoutSuppliedToLock3.set(unit.toNanos(time)); // A negative timeout should be supplied to this lock
280 | boolean acquired = super.tryLock(time, unit); // Should fail as can't wait due to timeout <= 0
281 | lock3WasInitiallyAcquired.set(acquired);
282 | return acquired;
283 | }
284 | };
285 |
286 | // Now actually try to acquire the locks...
287 | boolean acquired = Locks.tryLockAll(1L, TimeUnit.NANOSECONDS, lock1, lock2, lock3);
288 | // Should fail...
289 | assertFalse(acquired);
290 |
291 | // Lock 1 should have been supplied a positive timeout and it should have been acquired...
292 | assertTrue(timeoutSuppliedToLock1.get() > 0);
293 | assertTrue(lock1WasInitiallyAcquired.get());
294 |
295 | // Lock 2 should have been supplied a negative timeout as lock1 used all of the available time,
296 | // but acquisition should have succeeded anyway because it was uncontended and available without blocking...
297 | assertTrue(timeoutSuppliedToLock2.get() < 0);
298 | assertTrue(lock2WasInitiallyAcquired.get());
299 |
300 | // Lock 3 should have been supplied a negative timeout as lock1 used all of the available time,
301 | // and acquisition should have failed because it was unavailable and could not block due to timeout expired...
302 | assertTrue(timeoutSuppliedToLock3.get() < 0);
303 | assertFalse(lock3WasInitiallyAcquired.get());
304 |
305 | // All locks acquired should have been rolled back due to failure to acquire lock3...
306 | assertEquals(0, lock1.holdCount().value);
307 | assertEquals(0, lock2.holdCount().value);
308 | assertEquals(0, lock3.holdCount().value);
309 | }
310 | finally {
311 | executor.shutdown();
312 | }
313 | }
314 |
315 | @Test
316 | public void testConstructor() {
317 | assertNotNull(new Locks());
318 | }
319 |
320 | static class HoldCountLock extends ReentrantReadWriteUpdateLock.HoldCountLock {
321 |
322 | public HoldCountLock(Lock backingLock) {
323 | super(backingLock);
324 | }
325 |
326 | @Override
327 | void validatePreconditions() {
328 | // No op
329 | }
330 | }
331 | }
332 |
--------------------------------------------------------------------------------