# Phantom reference

> Mediated Wiki article. Canonical URL: https://mediated.wiki/source/Phantom_reference
> Markdown URL: https://mediated.wiki/source/Phantom_reference.md
> Source: https://en.wikipedia.org/wiki/Phantom_reference
> Source revision: 1334339403
> License: Creative Commons Attribution-ShareAlike 4.0 International (https://creativecommons.org/licenses/by-sa/4.0/)

{{More citations needed|date=May 2009}}

A '''phantom reference''' is a kind of reference in [Java](/source/Java_(programming_language)), where the memory can be reclaimed. The class is <code>java.lang.ref.PhantomReference</code>. The phantom reference is one of the strengths or levels of 'non [strong](/source/strong_reference)' reference defined in the Java programming language; the others being [weak](/source/weak_reference) and [soft](/source/soft_reference).<ref>{{cite web|title=java.lang.ref (Java Platform SE 8 )|url=https://docs.oracle.com/javase/8/docs/api/java/lang/ref/package-summary.html|website=Java™ Platform, Standard Edition 8 API Specification|publisher=Oracle|accessdate=6 August 2016}}</ref> Phantom reference are the weakest level of reference in Java; in order from strongest to weakest, they are: strong, soft, weak, ''phantom.''

An object is phantomly referenced after it has been [finalized](/source/finalizer).

In Java 8 and earlier versions, the reference needs to be cleared before the memory for a finalized referent can be reclaimed. A change in Java 9<ref>{{cite web|last1=oracle.com|first1=kim barrett at|title=hg: jdk9/hs-rt/jdk: 8071507: (ref) Clear phantom reference as soft and weak references do|url=https://mail.openjdk.java.net/pipermail/jdk9-hs-rt-changes/2015-December/001914.html|date=28 December 2015}}</ref> will allow memory from a finalized referent to be reclaimable immediately.

==Use==
Phantom references are of limited use, primarily narrow technical uses.<ref>{{cite web |last=Nicholas |first=Ethan |url=http://weblogs.java.net/blog/2006/05/04/understanding-weak-references |title=Understanding Weak References |website=www.java.net|date=May 4, 2006 |accessdate=October 1, 2010 |url-status=dead |archiveurl=https://web.archive.org/web/20100819115659/http://weblogs.java.net/blog/2006/05/04/understanding-weak-references |archivedate=August 19, 2010 }}</ref> First, it can be used instead of a <code>finalize</code> method, guaranteeing that the object is not resurrected during finalization. This allows the object to be garbage collected in a single cycle, rather than needing to wait for a second GC cycle to ensure that it has not been resurrected. A second use is to detect exactly when an object has been removed from memory (by using in combination with a <code>java.lang.ref.ReferenceQueue</code> object), ensuring that its memory is available, for example deferring allocation of a large amount of memory (e.g., a large image) until previous memory is freed.

==Example==
<syntaxhighlight lang="java">
import java.lang.ref.PhantomReference;
import java.lang.ref.ReferenceQueue;

class Resource {
    private final String name;

    public Resource(String name) {
        this.name = name;
    }

    public String getName() {
        return name;
    }
}

public class PhantomReferenceExample {
    public static void main(String[] args) throws InterruptedException {
        Resource resource = new Resource("My resource");
        ReferenceQueue<Resource> queue = new ReferenceQueue<>();
        PhantomReference<Resource> phantomRef = new PhantomReference<>(resource, queue);

        resource = null;

        System.gc();

        Reference<? extends Resource> ref = queue.poll();
        if (ref != null) {
            System.out.printf("Object is ready to be collected: %s%n", ((PhantomReference<?>)ref).get());
        }
    }
}
</syntaxhighlight>

== See also ==
{{Portal|Computer programming}}
* [Ephemeron](/source/Ephemeron)
* [Weak reference](/source/Weak_reference)
* [Soft reference](/source/Soft_reference)
* [Circular reference](/source/Circular_reference)

==References==
{{Reflist}}

{{Java (Sun)}}

Category:Programming constructs
Category:Memory management

{{compu-lang-stub}}

---
Adapted from the Wikipedia article [Phantom reference](https://en.wikipedia.org/wiki/Phantom_reference) by Wikipedia contributors ([contributor history](https://en.wikipedia.org/wiki/Phantom_reference?action=history)). Available under [Creative Commons Attribution-ShareAlike 4.0 International](https://creativecommons.org/licenses/by-sa/4.0/). Changes may have been made.