Developers may use this class as a drop-in replacement for the {@link java.util.HashSet} class for use in a {@link ManagedObject}. A {@code HashSet} will typically perform better than this class when the number ofmappings is small, the objects being stored are small, and minimal concurrency is required. As the size of the serialized {@code HashSet}increases, this class will perform significantly better. Developers are encouraged to profile the serialized size of their set to determine which implementation will perform better. Note that {@code HashSet} does notprovide any concurrency for {@code Task}s running in parallel that attempt to modify the set at the same time, so this class may perform better in situations where multiple tasks need to modify the set concurrently, even if the total number of elements is small. Also note that, unlike {@code HashSet}, this class can be used to store {@code ManagedObject} instancesdirectly.
This implementation requires that all non- {@code null} elements implement{@link Serializable}. Attempting to add elements to the set that do not implement {@code Serializable} will result in an {@link IllegalArgumentException} being thrown. If an element is an instance of{@code Serializable} but does not implement {@code ManagedObject}, this class will persist the element as necessary; when such an element is removed from the set, it is also removed from the {@code DataManager}. If an element is an instance of {@code ManagedObject}, the developer will be responsible for removing these objects from the {@code DataManager} whendone with them. Developers should not remove these object from the {@code DataManager} prior to removing them from the set.
Applications must make sure that objects used as elements in sets of this class have {@code equals} and {@code hashCode} methods that return the samevalues after the elements have been serialized and deserialized. In particular, elements that use {@link Object#equals Object.equals} and {@link Object#hashCode Object.hashCode} will typically not be equal, and will havedifferent hash codes, each time they are deserialized, and so are probably not suitable for use with this class.
This class marks itself for update as necessary; no additional calls to the {@link DataManager} are necessary when modifying the map. Developers do notneed to call {@code markForUpdate} or {@code getForUpdate} on this set, asthis will eliminate all the concurrency benefits of this class. However, calling {@code getForUpdate} or {@code markForUpdate} can be used if aoperation needs to prevent all access to the set.
This class offers constant-time implementations of the {@code add}, {@code remove} and {@code contains} methods. Note that, unlike most collections,the {@code size} and {@code isEmpty} methods for this class are notconstant-time operations. Because of the asynchronous nature of the set, these operations may require accessing all of the entries in the set.
An instance of {@code ScalableHashSet} offers one parameter for performancetuning: {@code minConcurrency}, which specifies the minimum number of write operations to support in parallel. This parameter acts as a hint to the backing map on how to perform resizing. As the set grows, the number of supported parallel operations will also grow beyond the specified minimum. Setting the minimum concurrency too high will waste space and time, while setting it too low will cause conflicts until the map grows sufficiently to support more concurrent operations.
Since the expected distribution of objects in the set is essentially random, the actual concurrency will vary. Developers are strongly encouraged to use hash codes that provide a normal distribution; a large number of collisions will likely reduce the performance.
The {@code Iterator} for this class implements{@code Serializable}. A single iterator may be saved by different {@code ManagedObject} instances, which will create distinct copies of the originaliterator. A copy starts its iteration from where the state of the original was at the time of the copy. However, each copy maintains a separate, independent state from the original and will therefore not reflect any changes to the original iterator. To share a single {@code Iterator}between multiple {@code ManagedObject} and have the iterator use aconsistent view for each, the iterator should be contained within a shared {@code ManagedObject}.
The iterator do not throw {@link java.util.ConcurrentModificationException}. The iterator for this class is stable with respect to the concurrent changes to the associated collection, but may ignore additions and removals made to the set during iteration.
If a call to the {@link Iterator#next next} method on the iterator causes a{@link ObjectNotFoundException} to be thrown because the return value hasbeen removed from the {@code DataManager}, the iterator will still have successfully moved to the next entry in its iteration. In this case, the {@link Iterator#remove remove} method may be called on the iterator toremove the current object even though that object could not be returned.
This class and its iterator implement all optional operations and support {@code null} elements. This set provides no guarantees on the order ofelements when iterating. @param < E> the type of elements maintained by this set @see Object#hashCode Object.hashCode @see java.util.Set @see java.util.HashSet @see ScalableHashMap @see Serializable @see ManagedObject
| |
| |