|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object util.concurrent.SyncCollection
SyncCollections wrap Sync-based control around java.util.Collections. They are similar in operation to those provided by java.util.Collection.synchronizedCollection, but have several extended capabilities.
The Collection interface is conceptually broken into two parts for purposes of synchronization control. The purely inspective reader operations are:synchronizationFailures()
.
Non-zero values may indicate serious program errors.
unprotectedIterator
that can be used in conjunction with the readerSync
or
writerSync
methods to perform locked traversals. For example,
to protect a block of reads:
Sync lock = coll.readerSync(); try { lock.acquire(); try { Iterator it = coll.unprotectedIterator(); while (it.hasNext()) System.out.println(it.next()); } finally { lock.release(); } } catch (InterruptedException ex) { ... }If you need to protect blocks of writes, you must use some form of reentrant lock (for example
ReentrantLock
or ReentrantWriterPreferenceReadWriteLock
) as the Sync
for the collection in order to allow mutative methods to proceed
while the current thread holds the lock. For example, you might
need to hold a write lock during an initialization sequence:
Collection c = new SyncCollection(new ArrayList(), new ReentrantWriterPreferenceReadWriteLock()); // ... c.writeLock().acquire(); try { for (...) { Object x = someStream.readObject(); c.add(x); // would block if writeLock not reentrant } } catch (IOException iox) { ... } finally { c.writeLock().release(); } catch (InterruptedException ex) { ... }(It would normally be better practice here to not make the collection accessible until initialization is complete.) This class does not specifically support use of timed synchronization through the attempt method. However, you can obtain this effect via the TimeoutSync class. For example:
Mutex lock = new Mutex(); TimeoutSync timedLock = new TimeoutSync(lock, 1000); // 1 sec timeouts Collection c = new SyncCollection(new HashSet(), timedlock);The same can be done with read-write locks:
ReadWriteLock rwl = new WriterPreferenceReadWriteLock(); Sync rlock = new TimeoutSync(rwl.readLock(), 100); Sync wlock = new TimeoutSync(rwl.writeLock(), 100); Collection c = new SyncCollection(new HashSet(), rlock, wlock);In addition to synchronization control, SyncCollections may be useful in any context requiring before/after methods surrounding collections. For example, you can use ObservableSync to arrange notifications on method calls to collections, as in:
class X { Collection c; static class CollectionObserver implements ObservableSync.SyncObserver { public void onAcquire(Object arg) { Collection coll = (Collection) arg; System.out.println("Starting operation on" + coll); // Other plausible responses include performing integrity // checks on the collection, updating displays, etc } public void onRelease(Object arg) { Collection coll = (Collection) arg; System.out.println("Finished operation on" + coll); } } X() { ObservableSync s = new ObservableSync(); c = new SyncCollection(new HashSet(), s); s.setNotificationArgument(c); CollectionObserver obs = new CollectionObserver(); s.attach(obs); } ... }
[ Introduction to this package. ]
LayeredSync
,
TimeoutSync
Nested Class Summary | |
class |
SyncCollection.SyncCollectionIterator
|
Field Summary | |
protected java.util.Collection |
c_
|
protected Sync |
rd_
|
protected SynchronizedLong |
syncFailures_
|
protected Sync |
wr_
|
Constructor Summary | |
SyncCollection(java.util.Collection collection,
ReadWriteLock rwl)
Create a new SyncCollection protecting the given collection, and using the given ReadWriteLock to control reader and writer methods. |
|
SyncCollection(java.util.Collection collection,
Sync sync)
Create a new SyncCollection protecting the given collection, and using the given sync to control both reader and writer methods. |
|
SyncCollection(java.util.Collection collection,
Sync readLock,
Sync writeLock)
Create a new SyncCollection protecting the given collection, and using the given pair of locks to control reader and writer methods. |
Method Summary | |
boolean |
add(java.lang.Object o)
|
boolean |
addAll(java.util.Collection coll)
|
protected void |
afterRead(boolean wasInterrupted)
Clean up after a reader operation * |
protected boolean |
beforeRead()
Try to acquire sync before a reader operation; record failure * |
void |
clear()
|
boolean |
contains(java.lang.Object o)
|
boolean |
containsAll(java.util.Collection coll)
|
boolean |
isEmpty()
|
java.util.Iterator |
iterator()
|
Sync |
readerSync()
Return the Sync object managing read-only operations |
boolean |
remove(java.lang.Object o)
|
boolean |
removeAll(java.util.Collection coll)
|
boolean |
retainAll(java.util.Collection coll)
|
int |
size()
|
long |
syncFailures()
Return the number of synchronization failures for read-only operations |
java.lang.Object[] |
toArray()
|
java.lang.Object[] |
toArray(java.lang.Object[] a)
|
java.util.Iterator |
unprotectedIterator()
Return the base iterator of the underlying collection * |
Sync |
writerSync()
Return the Sync object managing mutative operations |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Methods inherited from interface java.util.Collection |
equals, hashCode |
Field Detail |
protected final java.util.Collection c_
protected final Sync rd_
protected final Sync wr_
protected final SynchronizedLong syncFailures_
Constructor Detail |
public SyncCollection(java.util.Collection collection, Sync sync)
Collection c = new SyncCollection(new ArrayList(), new Mutex());
public SyncCollection(java.util.Collection collection, ReadWriteLock rwl)
Collection c = new SyncCollection(new HashSet(), new WriterPreferenceReadWriteLock());
public SyncCollection(java.util.Collection collection, Sync readLock, Sync writeLock)
Method Detail |
public Sync readerSync()
public Sync writerSync()
public long syncFailures()
protected boolean beforeRead()
protected void afterRead(boolean wasInterrupted)
public int size()
size
in interface java.util.Collection
public boolean isEmpty()
isEmpty
in interface java.util.Collection
public boolean contains(java.lang.Object o)
contains
in interface java.util.Collection
public java.lang.Object[] toArray()
toArray
in interface java.util.Collection
public java.lang.Object[] toArray(java.lang.Object[] a)
toArray
in interface java.util.Collection
public boolean containsAll(java.util.Collection coll)
containsAll
in interface java.util.Collection
public boolean add(java.lang.Object o)
add
in interface java.util.Collection
public boolean remove(java.lang.Object o)
remove
in interface java.util.Collection
public boolean addAll(java.util.Collection coll)
addAll
in interface java.util.Collection
public boolean removeAll(java.util.Collection coll)
removeAll
in interface java.util.Collection
public boolean retainAll(java.util.Collection coll)
retainAll
in interface java.util.Collection
public void clear()
clear
in interface java.util.Collection
public java.util.Iterator unprotectedIterator()
public java.util.Iterator iterator()
iterator
in interface java.util.Collection
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |