Package au.net.zeus.collection

See:
          Description

Interface Summary
Referrer<T> The public API of package private Reference implementations, it defines the equals and hashCode contracts as well as methods identical to Reference.
 

Class Summary
RC This class contains static methods for decorating collections with reference capability.
 

Enum Summary
Ref Ref enum represents types of references available for use in java collection framework implementations.
 

Package au.net.zeus.collection Description

Reference Collections 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 reference collections the garbage collection thread may not see timestamp updates on soft references when reading objects from the collection, 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 Reference Collections, which have been 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 Reference Collections 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 2010-2012, Zeus Project Services Pty Ltd.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.