< prev index next >

src/java.base/share/classes/java/lang/ref/Reference.java

Print this page


   1 /*
   2  * Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any


 401     }
 402 
 403     /**
 404      * Ensures that the object referenced by the given reference remains
 405      * <a href="package-summary.html#reachability"><em>strongly reachable</em></a>,
 406      * regardless of any prior actions of the program that might otherwise cause
 407      * the object to become unreachable; thus, the referenced object is not
 408      * reclaimable by garbage collection at least until after the invocation of
 409      * this method.  Invocation of this method does not itself initiate garbage
 410      * collection or finalization.
 411      *
 412      * <p> This method establishes an ordering for
 413      * <a href="package-summary.html#reachability"><em>strong reachability</em></a>
 414      * with respect to garbage collection.  It controls relations that are
 415      * otherwise only implicit in a program -- the reachability conditions
 416      * triggering garbage collection.  This method is designed for use in
 417      * uncommon situations of premature finalization where using
 418      * {@code synchronized} blocks or methods, or using other synchronization
 419      * facilities are not possible or do not provide the desired control.  This
 420      * method is applicable only when reclamation may have visible effects,
 421      * which is possible for objects with finalizers (See Section 12.6
 422      * of <cite>The Java&trade; Language Specification</cite>) that
 423      * are implemented in ways that rely on ordering control for
 424      * correctness.
 425      *
 426      * @apiNote
 427      * Finalization may occur whenever the virtual machine detects that no
 428      * reference to an object will ever be stored in the heap: The garbage
 429      * collector may reclaim an object even if the fields of that object are
 430      * still in use, so long as the object has otherwise become unreachable.
 431      * This may have surprising and undesirable effects in cases such as the
 432      * following example in which the bookkeeping associated with a class is
 433      * managed through array indices.  Here, method {@code action} uses a
 434      * {@code reachabilityFence} to ensure that the {@code Resource} object is
 435      * not reclaimed before bookkeeping on an associated
 436      * {@code ExternalResource} has been performed; in particular here, to
 437      * ensure that the array slot holding the {@code ExternalResource} is not
 438      * nulled out in method {@link Object#finalize}, which may otherwise run
 439      * concurrently.
 440      *
 441      * <pre> {@code
 442      * class Resource {
 443      *   private static ExternalResource[] externalResourceArray = ...
 444      *


 491      * }
 492      * private ExternalResource getExternalResource() {
 493      *   ExternalResource ext = externalResourceArray[myIndex];
 494      *   Reference.reachabilityFence(this);
 495      *   return ext;
 496      * }}</pre>
 497      *
 498      * <p> Method {@code reachabilityFence} is not required in constructions
 499      * that themselves ensure reachability.  For example, because objects that
 500      * are locked cannot, in general, be reclaimed, it would suffice if all
 501      * accesses of the object, in all methods of class {@code Resource}
 502      * (including {@code finalize}) were enclosed in {@code synchronized (this)}
 503      * blocks.  (Further, such blocks must not include infinite loops, or
 504      * themselves be unreachable, which fall into the corner case exceptions to
 505      * the "in general" disclaimer.)  However, method {@code reachabilityFence}
 506      * remains a better option in cases where this approach is not as efficient,
 507      * desirable, or possible; for example because it would encounter deadlock.
 508      *
 509      * @param ref the reference. If {@code null}, this method has no effect.
 510      * @since 9
 511      * @jls 12.6 Finalization of Class Instances
 512      */
 513     @ForceInline
 514     public static void reachabilityFence(Object ref) {
 515         // Does nothing. This method is annotated with @ForceInline to eliminate
 516         // most of the overhead that using @DontInline would cause with the
 517         // HotSpot JVM, when this fence is used in a wide variety of situations.
 518         // HotSpot JVM retains the ref and does not GC it before a call to
 519         // this method, because the JIT-compilers do not have GC-only safepoints.
 520     }
 521 }
   1 /*
   2  * Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any


 401     }
 402 
 403     /**
 404      * Ensures that the object referenced by the given reference remains
 405      * <a href="package-summary.html#reachability"><em>strongly reachable</em></a>,
 406      * regardless of any prior actions of the program that might otherwise cause
 407      * the object to become unreachable; thus, the referenced object is not
 408      * reclaimable by garbage collection at least until after the invocation of
 409      * this method.  Invocation of this method does not itself initiate garbage
 410      * collection or finalization.
 411      *
 412      * <p> This method establishes an ordering for
 413      * <a href="package-summary.html#reachability"><em>strong reachability</em></a>
 414      * with respect to garbage collection.  It controls relations that are
 415      * otherwise only implicit in a program -- the reachability conditions
 416      * triggering garbage collection.  This method is designed for use in
 417      * uncommon situations of premature finalization where using
 418      * {@code synchronized} blocks or methods, or using other synchronization
 419      * facilities are not possible or do not provide the desired control.  This
 420      * method is applicable only when reclamation may have visible effects,
 421      * which is possible for objects with finalizers (See
 422      * <a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-12.html#jls-12.6">
 423      * Section 12.6 17 of <cite>The Java&trade; Language Specification</cite></a>)
 424      * that are implemented in ways that rely on ordering control for correctness.
 425      *
 426      * @apiNote
 427      * Finalization may occur whenever the virtual machine detects that no
 428      * reference to an object will ever be stored in the heap: The garbage
 429      * collector may reclaim an object even if the fields of that object are
 430      * still in use, so long as the object has otherwise become unreachable.
 431      * This may have surprising and undesirable effects in cases such as the
 432      * following example in which the bookkeeping associated with a class is
 433      * managed through array indices.  Here, method {@code action} uses a
 434      * {@code reachabilityFence} to ensure that the {@code Resource} object is
 435      * not reclaimed before bookkeeping on an associated
 436      * {@code ExternalResource} has been performed; in particular here, to
 437      * ensure that the array slot holding the {@code ExternalResource} is not
 438      * nulled out in method {@link Object#finalize}, which may otherwise run
 439      * concurrently.
 440      *
 441      * <pre> {@code
 442      * class Resource {
 443      *   private static ExternalResource[] externalResourceArray = ...
 444      *


 491      * }
 492      * private ExternalResource getExternalResource() {
 493      *   ExternalResource ext = externalResourceArray[myIndex];
 494      *   Reference.reachabilityFence(this);
 495      *   return ext;
 496      * }}</pre>
 497      *
 498      * <p> Method {@code reachabilityFence} is not required in constructions
 499      * that themselves ensure reachability.  For example, because objects that
 500      * are locked cannot, in general, be reclaimed, it would suffice if all
 501      * accesses of the object, in all methods of class {@code Resource}
 502      * (including {@code finalize}) were enclosed in {@code synchronized (this)}
 503      * blocks.  (Further, such blocks must not include infinite loops, or
 504      * themselves be unreachable, which fall into the corner case exceptions to
 505      * the "in general" disclaimer.)  However, method {@code reachabilityFence}
 506      * remains a better option in cases where this approach is not as efficient,
 507      * desirable, or possible; for example because it would encounter deadlock.
 508      *
 509      * @param ref the reference. If {@code null}, this method has no effect.
 510      * @since 9

 511      */
 512     @ForceInline
 513     public static void reachabilityFence(Object ref) {
 514         // Does nothing. This method is annotated with @ForceInline to eliminate
 515         // most of the overhead that using @DontInline would cause with the
 516         // HotSpot JVM, when this fence is used in a wide variety of situations.
 517         // HotSpot JVM retains the ref and does not GC it before a call to
 518         // this method, because the JIT-compilers do not have GC-only safepoints.
 519     }
 520 }
< prev index next >