WeakRef

interface WeakRef<out T>

A weak reference holds a reference to another object, without preventing that object from being garbage-collected.

The value referenced by this class is eligible for garbage-collection, meaning that it could disappear at any time. Garbage collectors are complex machinery. One should take care not to write code that depends on the behavior of a specific garbage collector, as that behavior can change between future versions.

Storing null is technically allowed for convenience reasons, but doesn't make much sense. It is not possible to distinguish between a weak reference that stores null and one that used store a value but has been cleared. Therefore, implementations are free to not store null values at all.

Obtain instances

The default implementations are available via the top-level WeakRef and SoftRef functions. Other implementations are available in the algorithms subpackage.

Not stable for inheritance

This interface is not stable for inheritance. We may add new methods at any time.

Inheritors

• FakeWeakRef

Constructors

WeakRef

common

@ExperimentalNativeApi
expect fun <TTTTT> WeakRef(value: T): WeakRef<T>

js

@ExperimentalNativeApi
actual fun <TTTTT> WeakRef(value: T): WeakRef<T>

jvmnativewasmJs

@ExperimentalNativeApi
actual fun <TTTTT> WeakRef(value: T): WeakRef<T>

@ExperimentalNativeApi
actual fun <TTTTT> WeakRef(value: T): WeakRef<T>

@ExperimentalNativeApi
actual fun <TTTTT> WeakRef(value: T): WeakRef<T>

commonjsjvmnativewasmJs

Instantiates a weak reference: a reference to a value that doesn't stop the garbage collector from collecting it.

The value may be accessed with WeakRef.read. However, it could disappear at any time.

When should you use a weak reference?

The runtime is encouraged to clear the value as soon as possible.

This makes implementations ideal for writing mappers from an object to a more expensive one, when we know that we don't need the result of the mapping as soon as the initial object becomes unavailable.

The exact behavior of the returned object is platform-specific.

Thread-safety

The reference returned by this function is thread-safe.

See also

• SoftRef: For implementing caches

Implementation of WeakRef backed by a JS WeakRef.

JS doesn't make a difference between weak and soft references.

Implementation of WeakRef backed by a JVM WeakReference.

Implementation of WeakRef backed by a native WeakReference.

Kotlin Native doesn't make a difference between weak and soft references.

Implementation of WeakRef backed by a JS WeakRef.

JS doesn't make a difference between weak and soft references.

Types

Companion

object Companion

Functions

isEmpty

@ExperimentalWeakApi
open fun isEmpty(): Boolean

Checks whether this weak reference has been cleared.

If this function returns true, calling read will return null.

See also

• read: Read the current value.

isNotEmpty

@ExperimentalWeakApi
open fun isNotEmpty(): Boolean

Checks whether this weak reference still contains some data.

If this function returns true, the weak reference still contained some data at the moment where the function was called. Note that this does not guarantee that a subsequent call to read will return any data, as the data could have been cleared in between.

If you need to write an algorithm that depends on the data and its presence, prefer using read and a null-check to ensure that the data doesn't disappear between the test and the access.

See also

• read: Read the current value.

read

abstract fun read(): T?

Attempts to read the value held by this reference.

If the value was garbage-collected, which may happen at any time, this accessor returns null.

One should not assume any additional behavior. In particular, the value may continue to be returned long after it has become unreachable from anywhere else in the program, or disappear sooner than one expected.

Native limitations

On Kotlin Native, values can only be freed by the GC in a different frame than the one they were created in. This means that if you call read within the body of a function, the weak reference cannot be cleared anymore until the end of the function.

Be careful of this limitation when using weak references inside a single expensive function.

To learn more, follow KT-79985.

See also

• isEmpty: Test if the reference has been cleared.