モジュール java.base
パッケージ java.lang.ref

クラスCleaner

  • public final class Cleaner
extends Object
    Cleanerは、一連のオブジェクト参照と対応するクリーニング・アクションを管理します。

    クリーナは、オブジェクトが有線で到達可能になったことがクリーナに通知された後で実行するために、クリーニング動作はregisteredです。 クリーナは、PhantomReferenceとReferenceQueueを使用して、reachabilityが変更されたときに通知を受け取ります。

    各クリーナは、独立して動作し、保留中のクリーニング動作を管理し、クリーナがすでに使用されていないときにスレッドおよび終了を処理します。 オブジェクト参照と対応するクリーニング・アクションを登録すると、Cleanableが返されます。 最も効率的な使用法は、オブジェクトが閉じられたり不要になったときに、cleanメソッドを明示的に呼び出すことです。 クリーニング・アクションは、すでに明示的にクリーニングされていない限り、オブジェクトがファントム到達可能になったときに呼び出されるRunnableです。 クリーニング動作は、登録されているオブジェクトを参照してはならないことに注意してください。 そうであれば、オブジェクトは想像を絶するものにならず、クリーニング動作は自動的に呼び出されません。

    クリーニング・アクションの実行は、クリーナに関連するスレッドによって実行されます。 クリーニング・アクションによってスローされたすべての例外は無視されます。 クリーナおよびその他のクリーニング・アクションは、クリーニング・アクションの例外の影響を受けません。 スレッドは、登録されているすべてのクリーニング処理が完了し、クリーナ自体がガベージ・コレクタによって再利用されるまで実行されます。

    System.exit中のクリーナの動作は実装固有です。 クリーニング動作の呼び出しの有無は保証されていません。

    ほかで指定がない場合、null引数をコンストラクタまたはこのクラスのメソッドへ渡すと、NullPointerExceptionがスローされます。

    APIの注:
    クリーニング・アクションは、関連付けられたオブジェクトにファントム到達可能になった後にのみ呼び出されるため、クリーニング・アクションを実装するオブジェクトにオブジェクトへの参照が保持されていないことが重要です。 この例では、静的クラスはクリーニング状態とアクションをカプセル化します。 "inner"クラスは、暗黙的に外部インスタンスへの参照を含んでいるため、匿名であるかどうかにかかわらず、使用しないでください。 新しいクリーナの選択または既存のクリーナの共有は、ユースケースによって決まります。

    CleaningExampleがtry-finallyブロックで使用されている場合、closeメソッドはクリーニング・アクションを呼び出します。 closeメソッドが呼び出されていない場合は、CleaningExampleインスタンスがファントムに到達可能になったときに、Cleanerによって呼び出されます。 

    
 public class CleaningExample implements AutoCloseable {
        // A cleaner, preferably one shared within a library
        private static final Cleaner cleaner = <cleaner>;

        static class State implements Runnable {

            State(...) {
                // initialize State needed for cleaning action
            }

            public void run() {
                // cleanup action accessing State, executed at most once
            }
        }

        private final State;
        private final Cleaner.Cleanable cleanable

        public CleaningExample() {
            this.state = new State(...);
            this.cleanable = cleaner.register(this, state);
        }

        public void close() {
            cleanable.clean();
        }
    }
    クリーニング動作はラムダになる可能性がありますが、クリーニングされるオブジェクトのフィールドを参照することで、オブジェクト参照を取得することが容易になり、オブジェクトがファントム到達可能にならないようになります。 上記のように、静的ネストされたクラスを使用すると、誤ってオブジェクト参照を保持することがなくなります。

    クリーニング・アクションは、他のクリーニング・アクションと並行して呼び出されるように準備されている必要があります。 通常は、クリーニング・アクションは実行するのが非常に速く、ブロックしないようにすべきです。 クリーニング動作がブロックされると、同じクリーナに登録された他のクリーニング動作の処理が遅れることがあります。 クリーナに登録されているすべてのクリーニング・アクションは、相互に互換性があります。

    導入されたバージョン:
    9

    • メソッドの詳細

      • create

        public static Cleaner create()
        新しいCleanerを返します。

        クリーナは、ファントム到達可能オブジェクトを処理し、クリーニング・アクションを呼び出すdaemon threadを作成します。 スレッドの「コンテキスト・クラス・ローダー」はsystem class loaderに設定されます。 スレッドはパーミッションを持たず、SecurityManager is setの場合にのみ実行されます。

        ファントムに到達し、登録されたすべてのクリーニング動作が完了すると、クリーナは終了します。

        戻り値:
        新しいCleaner
        例外:
        SecurityException - 現在のスレッドがスレッドの作成または開始を許可されていない場合。

      • create

        public static Cleaner create​(ThreadFactory threadFactory)
        ThreadFactoryからThreadを使用して新しいCleanerを返します。

        スレッド・ファクトリのnewThreadメソッドからのスレッドはdaemon threadに設定され、ファントム到達可能オブジェクトを処理し、クリーン・アクションを起動します。 各呼び出しで、thread factoryは、クリーニング・アクションを実行するのに適したスレッドを提供する必要があります。

        ファントムに到達し、登録されたすべてのクリーニング動作が完了すると、クリーナは終了します。

        パラメータ:
        threadFactory - 新しいThreadを返してクリーニング・アクションを処理するThreadFactory
        戻り値:
        新しいCleaner
        例外:
        IllegalThreadStateException - スレッド・ファクトリからのスレッドがnot a new threadの場合。
        SecurityException - 現在のスレッドがスレッドの作成または開始を許可されていない場合。

      • register

        public Cleaner.Cleanable register​(Object obj,
                                  Runnable action)
        オブジェクトにファントム到達可能になったときに実行するオブジェクトとクリーニング・アクションを登録します。 クリーニング動作の動作については、上記の「APIノート」を参照してください。
        パラメータ:
        obj - 監視するオブジェクト
        action - オブジェクトがファントム到達可能になったときに呼び出すRunnable
        戻り値:
        Cleanableインスタンス