OpenJDK 1.23 · jdk.internal.ref.Cleaner · APIdia, the JavaDoc alternative

General-purpose phantom-reference-based cleaners.

Cleaners are a lightweight and more robust alternative to finalization. They are lightweight because they are not created by the VM and thus do not require a JNI upcall to be created, and because their cleanup code is invoked directly by the reference-handler thread rather than by the finalizer thread. They are more robust because they use phantom references, the weakest type of reference object, thereby avoiding the nasty ordering problems inherent to finalization.

A cleaner tracks a referent object and encapsulates a thunk of arbitrary cleanup code. Some time after the GC detects that a cleaner's referent has become phantom-reachable, the reference-handler thread will run the cleaner. Cleaners may also be invoked directly; they are thread safe and ensure that they run their thunks at most once.

Cleaners are not a replacement for finalization. They should be used only when the cleanup code is extremely simple and straightforward. Nontrivial cleaners are inadvisable since they risk blocking the reference-handler thread and delaying further cleanup and finalization.

Field Summary

Modifier and Type	Field and Description
private static final ReferenceQueue<Object>	dummyQueue
private static Cleaner	first
private Cleaner	next Hides java.lang.ref.Reference.next.
private Cleaner	prev
private final Runnable	thunk

Access	Constructor and Description
private	Cleaner(Object referent, Runnable thunk)

Method Summary

Modifier and Type	Method and Description
private static synchronized Cleaner	add(Cleaner cl)
public void	clean() Runs this cleaner, if it has not been run before.
public static Cleaner	Returns: The new cleaner create(Object the referent object to be cleaned ob, Runnable The cleanup code to be run when the cleaner is invoked. The cleanup code is run directly from the reference-handler thread, so it should be as simple and straightforward as possible. thunk) Creates a new cleaner.
private static synchronized boolean	remove(Cleaner cl)

Inherited from java.lang.ref.PhantomReference:: get

Field Detail

dummyQueue	back to summary
private static final ReferenceQueue<Object> dummyQueue

first	back to summary
private static Cleaner first

next	back to summary
private Cleaner next Hides java.lang.ref.Reference.next.

prev	back to summary
private Cleaner prev

thunk	back to summary
private final Runnable thunk

Cleaner	back to summary
private Cleaner(Object referent, Runnable thunk)

Method Detail

add	back to summary
private static synchronized Cleaner add(Cleaner cl)

clean	back to summary
public void clean() Runs this cleaner, if it has not been run before. Annotations @SuppressWarnings:removal

clean

back to summary

public void clean()

Runs this cleaner, if it has not been run before.

Annotations

@SuppressWarnings:removal

create	back to summary
public static Cleaner create(Object ob, Runnable thunk) Creates a new cleaner. Parameters ob:Object the referent object to be cleaned thunk:Runnable The cleanup code to be run when the cleaner is invoked. The cleanup code is run directly from the reference-handler thread, so it should be as simple and straightforward as possible. Returns:Cleaner The new cleaner

create

back to summary

public static Cleaner create(Object ob, Runnable thunk)

Creates a new cleaner.

Parameters

ob:Object: the referent object to be cleaned
thunk:Runnable: The cleanup code to be run when the cleaner is invoked. The cleanup code is run directly from the reference-handler thread, so it should be as simple and straightforward as possible.

Returns:Cleaner

The new cleaner

remove	back to summary
private static synchronized boolean remove(Cleaner cl)

public Class Cleaner

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail