See: Description
Interface | Description |
---|---|
ReferenceQueuingFactory<O,R> |
An interface for processing ReferenceQueue's and encapsulating Objects
in references and for making references appear as their referent.
|
Referrer<T> |
The public API of package private Reference implementations, it defines the equals
and hashCode contracts as well as methods identical to Reference.
|
RefQueue<T> |
This interface defines the only ReferenceQueue method used,
to not depend directly on ReferenceQueue, allowing the use of other Queue
implementations.
|
TimeBomb | |
UntouchableReferrer<T> |
Class | Description |
---|---|
AbstractReferenceComparator<T> |
Implements equals and hashCode, subclass ReferenceComparator implements
Serializable and contains serial data.
|
AbstractReferrerDecorator<T> |
This class exists purely for allowing a client with their own Collection
implementation or Collection wrapper to perform custom serialisation of the
References by replacing the standard Referrer's with their own implementation.
|
CollectionDecorator<T> | |
ComparableReferrerDecorator<T> | |
EntryFacadeConverter<K,V> | |
EntryIteratorFacade<O,R> | |
EntrySetFacade<O,R> | |
NullIterator<T> | |
RC |
This class contains static methods for decorating collections
with reference capability.
|
ReadResolveFixCollectionCircularReferences<T> |
The purpose of this class is to implement all the possible interfaces
that subclasses of ReferenceCollection may implement.
|
ReadResolveFixForMapCircularReferences<K,V> | |
ReferenceBlockingDeque<T> | |
ReferenceBlockingQueue<T> | |
ReferenceCollection<T> |
A Collection of Reference Objects, the developer may chose any Collection
implementation to store the References, which is passed in a runtime.
|
ReferenceCollectionRefreshAfterSerialization<T> | |
ReferenceCollectionSerialData<T> |
This class is the serial form of ReferenceCollection and all it's subclasses.
|
ReferenceComparator<T> | |
ReferenceConcurrentMap<K,V> |
A referenced hash map, that encapsulates and utilises any ConcurrentMap
implementation passed in at construction.
|
ReferenceConcurrentNavigableMap<K,V> | |
ReferenceDeque<T> | |
ReferencedQueue<T> | |
ReferenceEntryFacade<K,V> | |
ReferenceFactory<T> |
ReferenceFactory creates References, representing the various subclasses
of Reference, such as WEAK, SOFT and STRONG for
use in collections.
|
ReferenceIterator<T> | |
ReferenceList<T> |
A List implementation that uses References.
|
ReferenceMap<K,V> |
ReferenceMap is a wrapper object that encapsulates another Map implementation
which it uses to store references.
|
ReferenceMapSerialData<K,V> | |
ReferenceNavigableMap<K,V> | |
ReferenceNavigableSet<T> | |
ReferenceProcessor<T> |
ReferenceProcessor is responsible for creation and collection of References
on behalf of Reference Collection implementations.
|
ReferenceProcessor.CleanerTask | |
ReferenceProcessor.CreateThread | |
ReferenceProcessor.EnqueGarbageTask | |
ReferenceProcessor.FinalizerTask | |
ReferenceProcessor.SystemThreadFactory | |
ReferenceProcessor.ThreadGroupAction | |
ReferenceSerializationFactory<T> | |
ReferenceSerializedForm<T> |
A temporary but functional replacement for ReferenceKey's.
|
ReferenceSet<T> |
A Referenced Set.
|
ReferenceSortedMap<K,V> | |
ReferenceSortedSet<T> |
Referenced set supports sorting Object based on their natural ordering
or a Comparator, which must be wrapped in a ReferenceComparator.
|
ReferrerDecorator<T> |
I've thought about refactoring so the equals and comparator behaviour is
implemented by the wrapper classes and only accepting References in
constructors as this would allow the use of standard java Reference classes
without extension, reducing the number of classes created,
however that would create serial form lock in.
|
RefReferenceQueue<T> |
A ReferenceQueue that implements RefQueue
|
SerializationOfReferenceCollection<T> | |
SerializationOfReferenceMap<K,V> | |
SoftEqualityReference<T> |
Implemented as per Ref.SOFT
|
SoftIdentityReference<T> |
Implementation as per Ref.SOFT_IDENTITY
|
StrongReference<T> |
Implemented as per Ref.STRONG
|
TempComparableReferrer<T> | |
TempEqualReferrer<T> | |
TempIdentityReferrer<T> | |
TimedComparableReferrerDecorator<T> | |
TimedReferrer<T> | |
TimedReferrerDecorator<T> | |
TimedRefQueue | |
WeakEqualityReference<T> |
Implemented as per Ref.WEAK
|
WeakIdentityReference<T> |
Implemented as per Ref.WEAK_IDENTITY
|
Enum | Description |
---|---|
Ref |
Ref enum represents types of references available for use in java
collection framework implementations.
|
Custard-apple is a utility that enables weak, soft, strong or time references to be used in any collection implementing standard Java Framework Interfaces
Expected behaviour of reference types may vary between platforms and should not be depended upon other than; weak references will be collected when no further strong references remain and soft references may be collected at any time the JVM's available memory is under pressure and the referent is softly reachable. Time references should exhibit identical behaviour on all platforms and will be collected after a period of inactivity, even while strong references to those objects remain.
Due to the multi threaded nature of Custard-apple the garbage collection thread may not see timestamp updates on soft references when reading objects from collections, possibly causing those soft references to be collected earlier than expected.
Large memory heaps cause issues with soft references in the Oracle jvm, in this case use -XX:SoftRefLRUPolicyMSPerMB=1 to minimise GC issues. At least until bug 6912889 is fixed.
Cliff Click's highly scalable hash map has been tested with Custard-apple, also designed with scalability in mind. Cleaning of garbage collected objects from collections is performed by a background executor periodically. Internal implementations produce significant quantities of short lived objects during read operations that die young. These objects only ever live in CPU cache, are not written back to shared memory and are never shared between threads.
Although Custard-apple is intended to be scalable it has not been tested on highly scalable hardware, if you have access to such hardware, feel free to write tests and contribute back performance improvements.
Timed references are provided for caching purposes and also support cancellation of Future's, for example timed references can be used in Queue's as a throttling mechanism, similar to a network dropping packets. Referent Future tasks will be cancelled by the cleaning thread when enqueued.
Serialization support for Map's will be implemented in a future release. Serialization of other collection types is supported, provided the underlying collection also supports Serialization.
Serialized form has been implemented as a separate concern using the Serialization Builder Pattern with the readResolve() workaround.
Package private implementation classes are not tied to serial form. These classes are not published by implementing Serializable. Future versions of this library, may utilise a completely different class or classes upon deserialisation. The serial form may also change between releases in ways that would normally break compatibility, multiple serial forms may exist for one class in multiple versions of it, without ever breaking compatibility. Currently all classes that implement Collection share an identical serial form.
Serialization compatibility is guaranteed between different releases.
Copyright 2007-2013, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.