Package org.apache.river.concurrent

This package provides a decorating 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.

See: Description

Interface Summary

Interface	Description
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

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

Enum Summary

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

Package org.apache.river.concurrent Description

This package provides a decorating 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 RC 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.

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 RC 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.