net.openhft.chronicle.core.io

Class AbstractReferenceCounted

java.lang.Object

net.openhft.chronicle.core.io.AbstractReferenceCounted

All Implemented Interfaces:

Monitorable, ReferenceCounted, ReferenceCountedTracer, ReferenceOwner, SingleThreadedChecked

Direct Known Subclasses:

AbstractCloseableReferenceCounted

public abstract class AbstractReferenceCounted
extends Object
implements ReferenceCountedTracer, ReferenceOwner, SingleThreadedChecked, Monitorable

Abstract base class for managing reference-counted resources.

This class provides the common functionality required for implementing reference counting mechanisms in resources, such as managing the number of references and releasing resources when they are no longer needed.

Field Summary

Fields

Modifier and Type	Field and Description
protected MonitorReferenceCounted	referenceCounted
protected static int	WARN_COUNT
protected static long	WARN_NS

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	AbstractReferenceCounted() Constructs an AbstractReferenceCounted with default monitoring.
protected	AbstractReferenceCounted(boolean monitored) Constructs an AbstractReferenceCounted.

Method Summary

Modifier and Type	Method and Description
void	addReferenceChangeListener(ReferenceChangeListener referenceChangeListener) Adds a ReferenceChangeListener that will be notified whenever the reference count changes.
static void	assertReferencesReleased() Asserts that all references have been released.
protected void	backgroundPerformRelease() Performs the release operation in the background.
protected boolean	canReleaseInBackground() Returns whether the resource can be released in the background.
StackTrace	createdHere() Returns the stack trace for where this resource was created.
static void	disableReferenceTracing() Disables reference tracing.
static void	enableReferenceTracing() Enables reference tracing.
protected abstract void	performRelease() Releases the resource.
int	refCount() Retrieves the current reference count.
void	referenceCountedUnmonitored(boolean unmonitored)
int	referenceId() Returns the unique reference ID for this resource.
void	release(ReferenceOwner id) Decrements the reference count by one.
void	releaseLast(ReferenceOwner id) Releases the last reference to the resource.
void	removeReferenceChangeListener(ReferenceChangeListener referenceChangeListener) Removes a ReferenceChangeListener previously added via ReferenceCounted.addReferenceChangeListener(ReferenceChangeListener).
void	reserve(ReferenceOwner id) Increments the reference count by one, indicating that the resource is now shared among multiple owners.
void	reserveTransfer(ReferenceOwner from, ReferenceOwner to) Transfers a reference from one owner to another.
void	singleThreadedCheckDisabled(boolean singleThreadedCheckDisabled) Sets the flag to disable the single-threaded check.
void	singleThreadedCheckReset() Resets the thread-safety check state.
protected boolean	threadSafetyCheck(boolean isUsed)
void	throwExceptionIfNotReleased() Throws an exception if the resource has already been released.
void	throwExceptionIfReleased() Throws an exception if the resource has been released.
@NotNull String	toString() Returns a string representation of the object including its reference name.
boolean	tryReserve(ReferenceOwner id) Attempts to reserve the resource without throwing an exception if it is already released.
void	unmonitor() Stops monitoring the resource.
static void	unmonitor(ReferenceCounted counted) Marks a reference-counted resource as unmonitored.
void	warnAndReleaseIfNotReleased() If not released, logs a warning and releases the resource.

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.ReferenceCountedTracer

onReleased

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

releaseLast

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

referenceName, temporary

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

unmonitor

Field Detail

WARN_NS

protected static final long WARN_NS

WARN_COUNT

protected static final int WARN_COUNT

referenceCounted

protected final transient MonitorReferenceCounted referenceCounted

Constructor Detail

AbstractReferenceCounted

protected AbstractReferenceCounted()

Constructs an AbstractReferenceCounted with default monitoring.

AbstractReferenceCounted

protected AbstractReferenceCounted(boolean monitored)

Constructs an AbstractReferenceCounted.

Parameters:

monitored - If true, the resource will be monitored for reference counted release.

Method Detail

enableReferenceTracing

public static void enableReferenceTracing()

Enables reference tracing.

disableReferenceTracing

public static void disableReferenceTracing()

Disables reference tracing.

NOTE: The resources will still be released appropriately, however if detailed tracing won't be recorded

assertReferencesReleased

public static void assertReferencesReleased()

Asserts that all references have been released.

unmonitor

public static void unmonitor(ReferenceCounted counted)

Marks a reference-counted resource as unmonitored.

NOTE: The resource will still be released appropriately, however it won't give a warning if it is not.

Parameters:

counted - the resource to unmonitor.

referenceId

public int referenceId()

Returns the unique reference ID for this resource.

Specified by:

referenceId in interface ReferenceOwner

Returns:

The reference ID.

createdHere

public StackTrace createdHere()

Returns the stack trace for where this resource was created.

Specified by:

createdHere in interface ReferenceCountedTracer

Returns:

The stack trace.

throwExceptionIfNotReleased

public void throwExceptionIfNotReleased()
                                 throws IllegalStateException

Throws an exception if the resource has already been released.

Specified by:

throwExceptionIfNotReleased in interface ReferenceCountedTracer

Throws:

ClosedIllegalStateException - If the resource has been released or closed.

ThreadingIllegalStateException - If this resource was accessed by multiple threads in an unsafe way

IllegalStateException - If the object has not been released (i.e., its reference count is greater than 0).

backgroundPerformRelease

protected void backgroundPerformRelease()

Performs the release operation in the background.

canReleaseInBackground

protected boolean canReleaseInBackground()

Returns whether the resource can be released in the background.

Returns:

true if the resource can be released in the background, false otherwise.

performRelease

protected abstract void performRelease()
                                throws IllegalStateException

Releases the resource. Subclasses should provide the specific implementation.

Throws:

IllegalStateException - if the resource cannot be released.

reserve

public void reserve(ReferenceOwner id)
             throws ClosedIllegalStateException,
                    ThreadingIllegalStateException

Increments the reference count by one, indicating that the resource is now shared among multiple owners.

When tracing is enabled, it checks the same owner doesn't try to reserve it twice (without releasing it in the meantime)

Specified by:

reserve in interface ReferenceCounted

Parameters:

id - The reference owner.

Throws:

ClosedIllegalStateException - If the resource has been released or closed.

ThreadingIllegalStateException - If this resource was accessed by multiple threads in an unsafe way

release

public void release(ReferenceOwner id)
             throws ClosedIllegalStateException

Decrements the reference count by one. If the reference count drops to 0, the resource will be released.

When tracing is enabled, it checks the resource was an owner, and doesn't attempt to release twice.

Specified by:

release in interface ReferenceCounted

Parameters:

id - The reference owner.

Throws:

ClosedIllegalStateException - If the resource has been released or closed.

releaseLast

public void releaseLast(ReferenceOwner id)
                 throws ClosedIllegalStateException

Releases the last reference to the resource.

When tracing is enabled, it checks the resource was an owner, and doesn't attempt to release twice.

Specified by:

releaseLast in interface ReferenceCounted

Parameters:

id - The reference owner.

Throws:

ClosedIllegalStateException - If the resource has been released or closed.

tryReserve

public boolean tryReserve(ReferenceOwner id)
                   throws ClosedIllegalStateException,
                          IllegalArgumentException

Attempts to reserve the resource without throwing an exception if it is already released.

Specified by:

tryReserve in interface ReferenceCounted

Parameters:

id - The reference owner.

Returns:

true if the reservation was successful, false otherwise.

Throws:

ClosedIllegalStateException - If the resource has been released or closed.

IllegalArgumentException - If the reference owner is not valid.

reserveTransfer

public void reserveTransfer(ReferenceOwner from,
                            ReferenceOwner to)
                     throws ClosedIllegalStateException,
                            ThreadingIllegalStateException

Transfers a reference from one owner to another.

Specified by:

reserveTransfer in interface ReferenceCounted

Parameters:

from - The current reference owner.

to - The new reference owner.

Throws:

ClosedIllegalStateException - If the resource has been released or closed.

ThreadingIllegalStateException - If this resource was accessed by multiple threads in an unsafe way

refCount

public int refCount()

Retrieves the current reference count.

Specified by:

refCount in interface ReferenceCounted

Returns:

The current reference count.

throwExceptionIfReleased

public void throwExceptionIfReleased()
                              throws ClosedIllegalStateException

Throws an exception if the resource has been released.

Specified by:

throwExceptionIfReleased in interface ReferenceCountedTracer

Throws:

ClosedIllegalStateException - If the resource has been released or closed.

warnAndReleaseIfNotReleased

public void warnAndReleaseIfNotReleased()
                                 throws IllegalStateException

If not released, logs a warning and releases the resource.

Specified by:

warnAndReleaseIfNotReleased in interface ReferenceCountedTracer

Throws:

IllegalStateException - If the resource hadn't been released.

singleThreadedCheckDisabled

public void singleThreadedCheckDisabled(boolean singleThreadedCheckDisabled)

Description copied from interface: SingleThreadedChecked

Sets the flag to disable the single-threaded check. When set to true, this resource can be shared between threads as long as the users ensure that it is used in a thread-safe manner.

Specified by:

singleThreadedCheckDisabled in interface SingleThreadedChecked

Parameters:

singleThreadedCheckDisabled - true to turn off the thread safety check, false to enable it.

addReferenceChangeListener

public void addReferenceChangeListener(ReferenceChangeListener referenceChangeListener)

Description copied from interface: ReferenceCounted

Adds a ReferenceChangeListener that will be notified whenever the reference count changes. This can be used to monitor the usage of the resource and execute code when certain conditions are met.

Specified by:

addReferenceChangeListener in interface ReferenceCounted

Parameters:

referenceChangeListener - The listener that will receive notifications of reference count changes.

removeReferenceChangeListener

public void removeReferenceChangeListener(ReferenceChangeListener referenceChangeListener)

Description copied from interface: ReferenceCounted

Removes a ReferenceChangeListener previously added via ReferenceCounted.addReferenceChangeListener(ReferenceChangeListener).

Note: Object equality is used to determine which listener to remove, so be cautious if the listener implements the equals method in a non-standard way.

Specified by:

removeReferenceChangeListener in interface ReferenceCounted

Parameters:

referenceChangeListener - The listener to remove.

threadSafetyCheck

protected boolean threadSafetyCheck(boolean isUsed)
                             throws ThreadingIllegalStateException

Throws:

ThreadingIllegalStateException

singleThreadedCheckReset

public void singleThreadedCheckReset()

Resets the thread-safety check state. This is typically used to indicate that the resource can be used again by a different thread.

Specified by:

singleThreadedCheckReset in interface SingleThreadedChecked

toString

@NotNull
public @NotNull String toString()

Returns a string representation of the object including its reference name.

Overrides:

toString in class Object

Returns:

A string representation of the object.

referenceCountedUnmonitored

public void referenceCountedUnmonitored(boolean unmonitored)

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