stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8311290: Improve java.lang.ref.Cleaner rendered documentation

Browse Source 
Reviewed-by: rriggs
This commit is contained in:
Pavel Rappo 2023-07-05 14:10:44 +00:00
parent 22e17c29a2
commit 2cffef2120
1 changed files with 9 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
src/java.base/share/classes/java/lang/ref/Cleaner.java
View File

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 2015, 2023, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -34,7 +34,7 @@ import java.util.function.Function;
/** /**
* {@code Cleaner} manages a set of object references and corresponding cleaning actions. * {@code Cleaner} manages a set of object references and corresponding cleaning actions.
* <p> * <p>
* Cleaning actions are {@link #register(Object object, Runnable action) registered} * Cleaning actions are {@linkplain #register(Object object, Runnable action) registered}
* to run after the cleaner is notified that the object has become * to run after the cleaner is notified that the object has become
* phantom reachable. * phantom reachable.
* The cleaner uses {@link PhantomReference} and {@link ReferenceQueue} to be * The cleaner uses {@link PhantomReference} and {@link ReferenceQueue} to be
@ -87,7 +87,7 @@ import java.util.function.Function;
* <pre>{@code * <pre>{@code
* public class CleaningExample implements AutoCloseable { * public class CleaningExample implements AutoCloseable {
* // A cleaner (preferably one shared within a library, * // A cleaner (preferably one shared within a library,
// but for the sake of example, a new one is created here) * // but for the sake of example, a new one is created here)
* private static final Cleaner cleaner = Cleaner.create(); * private static final Cleaner cleaner = Cleaner.create();
* *
* // State class captures information necessary for cleanup. * // State class captures information necessary for cleanup.
@ -162,9 +162,10 @@ public final class Cleaner {
* to process the phantom reachable objects and to invoke cleaning actions. * to process the phantom reachable objects and to invoke cleaning actions.
* The {@linkplain java.lang.Thread#getContextClassLoader context class loader} * The {@linkplain java.lang.Thread#getContextClassLoader context class loader}
* of the thread is set to the * of the thread is set to the
* {@link ClassLoader#getSystemClassLoader() system class loader}. * {@linkplain ClassLoader#getSystemClassLoader() system class loader}.
* The thread has no permissions, enforced only if a * The thread has no permissions, enforced only if a
* {@link java.lang.System#setSecurityManager(SecurityManager) SecurityManager is set}. * {@linkplain java.lang.System#setSecurityManager(SecurityManager)
* {@code SecurityManager} is set}.
* <p> * <p>
* The cleaner terminates when it is phantom reachable and all of the * The cleaner terminates when it is phantom reachable and all of the
* registered cleaning actions are complete. * registered cleaning actions are complete.
@ -184,9 +185,9 @@ public final class Cleaner {
* Returns a new {@code Cleaner} using a {@code Thread} from the {@code ThreadFactory}. * Returns a new {@code Cleaner} using a {@code Thread} from the {@code ThreadFactory}.
* <p> * <p>
* A thread from the thread factory's {@link ThreadFactory#newThread(Runnable) newThread} * A thread from the thread factory's {@link ThreadFactory#newThread(Runnable) newThread}
* method is set to be a {@link Thread#setDaemon(boolean) daemon thread} * method is set to be a {@linkplain Thread#setDaemon(boolean) daemon thread}
* and started to process phantom reachable objects and invoke cleaning actions. * and started to process phantom reachable objects and invoke cleaning actions.
* On each call the {@link ThreadFactory#newThread(Runnable) thread factory} * On each call the {@linkplain ThreadFactory#newThread(Runnable) thread factory}
* must provide a Thread that is suitable for performing the cleaning actions. * must provide a Thread that is suitable for performing the cleaning actions.
* <p> * <p>
* The cleaner terminates when it is phantom reachable and all of the * The cleaner terminates when it is phantom reachable and all of the
@ -197,7 +198,7 @@ public final class Cleaner {
* @return a new {@code Cleaner} * @return a new {@code Cleaner}
* *
* @throws IllegalThreadStateException if the thread from the thread * @throws IllegalThreadStateException if the thread from the thread
* factory was {@link Thread.State#NEW not a new thread}. * factory was {@linkplain Thread.State#NEW not a new thread}.
* @throws SecurityException if the current thread is not allowed to * @throws SecurityException if the current thread is not allowed to
* create or start the thread. * create or start the thread.
*/ */