LazyWeakReference<T extends Object> class final

A reference that starts strong and automatically degrades to weak after a period (See LazyWeakReferenceManager.weakenDelay).

This is useful for caches:

  • Recently accessed objects remain strongly reachable (cannot be GC'ed)
  • Old objects become weak and can be garbage-collected

The reference lifecycle: strong → weak → lost/disposed

⚡ Performance note: This design avoids the immediate cost of creating a WeakReference and accessing its WeakReference.target on every use. Instances start as purely strong references, making creation and access lightweight. The weak reference is created lazily and only when needed, delaying the overhead of weak-reference allocation and GC tracking.

The transition from strong → weak is controlled by LazyWeakReferenceManager.

Implemented types

Properties

hashCode → int
The hash code for this object.
no setterinherited
id → int
Unique sequence identifier assigned by the owning manager.
final
isAlive → bool
Whether the object is still reachable.
no setter
isDisposed → bool
True after manual or automatic disposal.
no setter
isLost → bool
True if GC has collected the object.
no setter
isQueued → bool
Whether this reference is currently enqueued in the manager’s strong-reference queue.
no setter
isStrong → bool
Whether this currently holds a strong reference.
no setter
isWeak → bool
Whether this reference is marked as weak (not strong). See isStrong.
no setter
manager → LazyWeakReferenceManager<T>?
Current manager.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
target → T?
Returns the object if still reachable.
no setter
targetIfStrong → T?
Returns the object only if currently held strongly.
no setter
unixTimeMs → int
Unix timestamp (milliseconds) of creation or of the most recent transition to a strong reference.
no setter

Methods

compareTo(LazyWeakReference<Object> other) → int
Orders instances first by _unixTimeMs and then by the unique id to guarantee a strict total order.
override
dispose() → void
Permanently releases all references.
elapsedMs(int nowUnixTime) → int
Returns the elapsed time (in milliseconds) since creation or since the most recent transition to a strong reference.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
strong({bool keepWeakRef = true}) → T?
Promotes this reference to strong.
toString() → String
A string representation of this object.
override
weak({bool checkWeakRefTarget = true}) → T?
Converts this reference into a weak reference.

Operators

operator ==(Object other) → bool
The equality operator.
inherited