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™ 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 {
|
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 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 {
|