net.openhft.chronicle.core.io

Class AbstractCloseable

java.lang.Object

net.openhft.chronicle.core.io.AbstractCloseable

All Implemented Interfaces:

Closeable, AutoCloseable, ManagedCloseable, Monitorable, QueryCloseable, ReferenceOwner, SingleThreadedChecked

Direct Known Subclasses:

UnsafeCloseable

public abstract class AbstractCloseable
extends Object
implements ReferenceOwner, ManagedCloseable, SingleThreadedChecked, Monitorable

An abstract class that represents a closeable resource with additional utilities for managing the resource lifecycle.

The class provides base functionalities for resources that require proper management, especially when being closed. This includes ensuring that close operations are thread-safe, providing hooks for custom cleanup logic, and supporting diagnostic features for tracking resource usage. It supports resource tracing, thread safety checks, and ensures that close operations are performed properly.

The AbstractCloseable class implements the ReferenceOwner, ManagedCloseable, and SingleThreadedChecked interfaces. The ReferenceOwner interface allows the class to have a unique reference identifier. The ManagedCloseable interface ensures that this class provides mechanisms for proper resource management during close operations. The SingleThreadedChecked interface ensures that the close operation is executed in a thread-safe manner.

Implementations of this abstract class should override the performClose() method to include the specific cleanup logic needed for the resource. This ensures that custom cleanup logic is executed exactly once during the closing of the resource.

Additionally, AbstractCloseable supports resource tracing, which can be enabled or disabled to monitor and diagnose resource allocation and deallocation. Resource tracing can help in identifying resource leaks and ensure resources are properly managed.

Subclasses can also control the behavior of thread safety checks and background closing through provided methods.

Field Summary

Fields

Modifier and Type	Field and Description
protected StackTrace	closedHere
protected static boolean	DISABLE_DISCARD_WARNING Flag indicating whether discard warning is disabled.
protected static long	WARN_NS The number of nanoseconds to warn before closing a resource.

Fields inherited from interface net.openhft.chronicle.core.io.ReferenceOwner

INIT, TMP

Fields inherited from interface net.openhft.chronicle.core.io.SingleThreadedChecked

DISABLE_SINGLE_THREADED_CHECK

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractCloseable() Constructs a new instance.

Method Summary

Modifier and Type	Method and Description
protected void	assertCloseable() Asserts that this resource can be closed, throwing an IllegalStateException if it cannot.
static void	assertCloseablesClosed() Asserts that all closeable resources are closed.
void	close() Closes this resource and releases any associated system resources.
StackTrace	createdHere() Returns the stack trace at the point this closeable resource was created.
static void	disableCloseableTracing() Disables tracing of closeable resources.
static void	enableCloseableTracing() Enables tracing of closeable resources.
static void	gcAndWaitForCloseablesToClose() Performs garbage collection and waits for closeables to close.
boolean	isClosed() Checks if the resource is closed.
boolean	isClosing() Checks if the resource is in the process of being closed.
protected boolean	isInUserThread() Checks if the current thread is a user thread.
protected abstract void	performClose() Contains the actual logic for closing the resource.
int	referenceId() Returns the unique reference ID of this closeable resource.
protected boolean	shouldPerformCloseInBackground() Determines if this component should be closed asynchronously in the background.
protected boolean	shouldWaitForClosed() Determines if this component should wait for the close operation to complete before returning from the close() method.
protected boolean	singleThreadedCheckDisabled() Determines if the single-threaded safety check is disabled for this component.
void	singleThreadedCheckDisabled(boolean singleThreadedCheckDisabled) Disables or enables the single-threaded safety check.
void	singleThreadedCheckReset() Resets the state of the thread safety check.
protected void	threadSafetyCheck(boolean isUsed) Performs a thread safety check on the component.
void	throwExceptionIfClosed() Throws an exception if the resource is closed.
void	throwExceptionIfClosedInSetter() Throws an exception if the resource is closed during a setter operation.
String	toString() Returns a string representation of this component, typically used for debugging purposes.
void	unmonitor() Stops monitoring the resource.
static boolean	waitForCloseablesToClose(long millis) Waits for closeable resources to be closed within a specified timeout period.
protected void	waitForClosed() Waits for the resource to transition to the closed state.
void	warnAndCloseIfNotClosed() Checks if the resource is not closed, and if so, logs a warning and closes it.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface net.openhft.chronicle.core.io.ReferenceOwner

referenceName, temporary

Methods inherited from interface net.openhft.chronicle.core.io.Closeable

closeQuietly, closeQuietly

Methods inherited from interface net.openhft.chronicle.core.io.Monitorable

unmonitor

Field Detail

DISABLE_DISCARD_WARNING

protected static final boolean DISABLE_DISCARD_WARNING

Flag indicating whether discard warning is disabled.

WARN_NS

protected static final long WARN_NS

The number of nanoseconds to warn before closing a resource.

closedHere

protected transient volatile StackTrace closedHere

Constructor Detail

AbstractCloseable

protected AbstractCloseable()

Constructs a new instance. Registers the instance for resource tracing and monitoring if enabled.

Method Detail

enableCloseableTracing

public static void enableCloseableTracing()

Enables tracing of closeable resources. When enabled, instances of resources that are not yet closed are stored in a set for tracking and debugging purposes.

disableCloseableTracing

public static void disableCloseableTracing()

Disables tracing of closeable resources. Tracked resources will no longer be stored in the set. This method should be called to disable tracing when no longer needed.

gcAndWaitForCloseablesToClose

public static void gcAndWaitForCloseablesToClose()

Performs garbage collection and waits for closeables to close. This method is useful for ensuring that closeable resources are properly closed before continuing. It performs the following steps: 1. Performs cleanup on the current thread. 2. Performs garbage collection. 3. Waits for closeables to close with a specified timeout. 4. Checks if the finalizer thread has finalized any objects. If not, it throws an AssertionError.

NOTE: This is slower than waitForCloseablesToClose and it can clean up resources that should have be released deterministically.

Throws:

AssertionError - If the finalizer does not complete within the specified timeout.

waitForCloseablesToClose

public static boolean waitForCloseablesToClose(long millis)

Waits for closeable resources to be closed within a specified timeout period.

Parameters:

millis - the maximum time in milliseconds to wait for closeables to close.

Returns:

true if all closeable resources were closed within the specified timeout, false otherwise.

assertCloseablesClosed

public static void assertCloseablesClosed()

Asserts that all closeable resources are closed. If any closeable resource is not closed, this method throws an AssertionError.

Throws:

AssertionError - if any closeable resource is not closed.

referenceId

public int referenceId()

Returns the unique reference ID of this closeable resource.

Specified by:

referenceId in interface ReferenceOwner

Returns:

the unique reference ID.

createdHere

public StackTrace createdHere()

Returns the stack trace at the point this closeable resource was created.

Specified by:

createdHere in interface ManagedCloseable

Returns:

the stack trace at the point of creation.

close

public final void close()

Closes this resource and releases any associated system resources.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

See Also:

performClose()

assertCloseable

protected void assertCloseable()

Asserts that this resource can be closed, throwing an IllegalStateException if it cannot.

This can be useful for resources that have outstanding guarantees such as acquired update locks or open contexts.

Electing to throw an Exception might cause memory-leaks as there is no guarantee that the close methods will ever be invoked again in the general case.

Throws:

IllegalStateException - if the resource cannot be closed.

isInUserThread

protected boolean isInUserThread()

Checks if the current thread is a user thread.

Returns:

true if the current thread is a user thread; false otherwise.

waitForClosed

protected void waitForClosed()

Waits for the resource to transition to the closed state. This is useful for scenarios where close operations might be asynchronous and the caller needs to wait until the resource is effectively closed.

throwExceptionIfClosed

public void throwExceptionIfClosed()
                            throws ClosedIllegalStateException,
                                   ThreadingIllegalStateException

Throws an exception if the resource is closed. This method is used to ensure that the resource is open before attempting an operation that requires it to be open.

Specified by:

throwExceptionIfClosed in interface ManagedCloseable

Throws:

ClosedIllegalStateException - If the resource has been released or closed.

ThreadingIllegalStateException - If the thread safety check fails.

throwExceptionIfClosedInSetter

public void throwExceptionIfClosedInSetter()
                                    throws ClosedIllegalStateException,
                                           ThreadingIllegalStateException

Throws an exception if the resource is closed during a setter operation. This method is used to ensure that the resource is open before attempting to modify its state.

Throws:

ClosedIllegalStateException - If the resource has been released or closed.

ThreadingIllegalStateException - If the thread safety check fails.

warnAndCloseIfNotClosed

public void warnAndCloseIfNotClosed()

Checks if the resource is not closed, and if so, logs a warning and closes it. This method is typically called from the finalizer to ensure that resources are not garbage collected without being properly closed.

Called from finalise() implementations.

Specified by:

warnAndCloseIfNotClosed in interface ManagedCloseable

performClose

protected abstract void performClose()

Contains the actual logic for closing the resource. This method is intended to be overridden by subclasses to provide specific close logic.

Note: This method is called exactly once through callPerformClose().

isClosing

public boolean isClosing()

Checks if the resource is in the process of being closed.

Specified by:

isClosing in interface QueryCloseable

Returns:

true if the resource is either closed or in the process of being closed; false otherwise.

isClosed

public boolean isClosed()

Checks if the resource is closed.

Specified by:

isClosed in interface QueryCloseable

Returns:

true if the resource is closed; false otherwise.

shouldPerformCloseInBackground

protected boolean shouldPerformCloseInBackground()

Determines if this component should be closed asynchronously in the background. Subclasses may override this method to change the default behavior, which is to close synchronously.

Returns:

true if this component should be closed in the background; false otherwise.

shouldWaitForClosed

protected boolean shouldWaitForClosed()

Determines if this component should wait for the close operation to complete before returning from the close() method. Subclasses may override this method to change the default behavior.

Returns:

true if this component should wait for the close to complete; false otherwise.

threadSafetyCheck

protected void threadSafetyCheck(boolean isUsed)
                          throws ThreadingIllegalStateException

Performs a thread safety check on the component. If the component is not thread-safe and is accessed by multiple threads, an ThreadingIllegalStateException is thrown. This method is intended to be called before operations that require thread safety.

Parameters:

isUsed - flag indicating whether the component is being used in the current operation.

Throws:

ThreadingIllegalStateException - If the component is not thread-safe and accessed by multiple threads.

singleThreadedCheckReset

public void singleThreadedCheckReset()

Resets the state of the thread safety check. After calling this method, the component's thread safety check state will be cleared, and it will no longer remember which thread it was last accessed by.

Specified by:

singleThreadedCheckReset in interface SingleThreadedChecked

toString

public String toString()

Returns a string representation of this component, typically used for debugging purposes. By default, this returns the reference name of the component.

Overrides:

toString in class Object

Returns:

the string representation of this component.

singleThreadedCheckDisabled

protected boolean singleThreadedCheckDisabled()

Determines if the single-threaded safety check is disabled for this component. If disabled, the component will not perform checks to ensure that it is being accessed by a single thread.

Returns:

true if single-threaded safety check is disabled; false otherwise.

singleThreadedCheckDisabled

public void singleThreadedCheckDisabled(boolean singleThreadedCheckDisabled)

Disables or enables the single-threaded safety check. If disabled, the component will not perform checks to ensure that it is being accessed by a single thread.

Specified by:

singleThreadedCheckDisabled in interface SingleThreadedChecked

Parameters:

singleThreadedCheckDisabled - true to disable single-threaded safety check; false to enable it.

unmonitor

public void unmonitor()

Description copied from interface: Monitorable

Stops monitoring the resource.

Implementations of this method should ensure that the resource and any resources it uses are no longer being tracked for any purpose such as cleanup, resource management, or debugging. This is particularly important for resources that are explicitly managed to avoid leaks.

Specified by:

unmonitor in interface Monitorable