CloseGuard

Kotlin |Java

class CloseGuard

kotlin.Any
↳	android.util.CloseGuard

CloseGuard is a mechanism for flagging implicit finalizer cleanup of resources that should have been cleaned up by explicit close methods (aka "explicit termination methods" in Effective Java).

A simple example:

<code>class Foo {
 
        private final CloseGuard guard = new CloseGuard();
 
        ...
 
        public Foo() {
            ...;
            guard.open("cleanup");
        }
 
        public void cleanup() {
           guard.close();
           ...;
           if (Build.VERSION.SDK_INT &gt;= 28) {
               Reference.reachabilityFence(this);
           }
           // For full correctness in the absence of a close() call, other methods may also need
           // reachabilityFence() calls.
        }
 
        protected void finalize() throws Throwable {
            try {
                // Note that guard could be null if the constructor threw.
                if (guard != null) {
                    guard.warnIfOpen();
                }
                cleanup();
            } finally {
                super.finalize();
            }
        }
    }
  </code>

In usage where the resource to be explicitly cleaned up is allocated after object construction, CloseGuard protection can be deferred. For example:

<code>class Bar {
 
        private final CloseGuard guard = new CloseGuard();
 
        ...
 
        public Bar() {
            ...;
        }
 
        public void connect() {
           ...;
           guard.open("cleanup");
        }
 
        public void cleanup() {
           guard.close();
           ...;
           if (Build.VERSION.SDK_INT &gt;= 28) {
               Reference.reachabilityFence(this);
           }
           // For full correctness in the absence of a close() call, other methods may also need
           // reachabilityFence() calls.
        }
 
        protected void finalize() throws Throwable {
            try {
                // Note that guard could be null if the constructor threw.
                if (guard != null) {
                    guard.warnIfOpen();
                }
                cleanup();
            } finally {
                super.finalize();
            }
        }
    }
  </code>

When used in a constructor, calls to open should occur at the end of the constructor since an exception that would cause abrupt termination of the constructor will mean that the user will not have a reference to the object to cleanup explicitly. When used in a method, the call to open should occur just after resource acquisition.

Summary

Public constructors
`CloseGuard()` Constructs a new CloseGuard instance.

Public methods
Unit	`close()` Marks this CloseGuard instance as closed to avoid warnings on finalization.
Unit	`open(closeMethodName: String)` Initializes the instance with a warning that the caller should have explicitly called the `closeMethodName` method instead of relying on finalization.
Unit	`warnIfOpen()` Logs a warning if the caller did not properly cleanup by calling an explicit close method before finalization.

Public constructors

CloseGuard

Added in API level 30

CloseGuard()

Constructs a new CloseGuard instance. open(java.lang.String) can be used to set up the instance to warn on failure to close.

Public methods

close

Added in API level 30

fun close(): Unit

Marks this CloseGuard instance as closed to avoid warnings on finalization.

open

Added in API level 30

fun open(closeMethodName: String): Unit

Initializes the instance with a warning that the caller should have explicitly called the closeMethodName method instead of relying on finalization.

Parameters
`closeMethodName`	String: non-null name of explicit termination method. Printed by warnIfOpen.

Exceptions
`java.lang.NullPointerException`	if closeMethodName is null.

warnIfOpen

Added in API level 30

fun warnIfOpen(): Unit

Logs a warning if the caller did not properly cleanup by calling an explicit close method before finalization.