net.openhft.chronicle.core.io

Interface ReferenceCounted

All Superinterfaces:

ReferenceOwner

All Known Subinterfaces:

MonitorReferenceCounted, ReferenceCountedTracer

All Known Implementing Classes:

AbstractCloseableReferenceCounted, AbstractReferenceCounted, DualReferenceCounted, TracingReferenceCounted, VanillaReferenceCounted

public interface ReferenceCounted
extends ReferenceOwner

Represents a resource that is reference counted. The resource is freed when the reference count drops to 0. This can be used for efficiently managing resources, such as memory buffers or file handles, by ensuring that they are not released until they are no longer in use.

Field Summary

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

INIT, TMP

Method Summary

Modifier and Type	Method and Description
void	addReferenceChangeListener(ReferenceChangeListener referenceChangeListener) Adds a ReferenceChangeListener that will be notified whenever the reference count changes.
int	refCount() Returns the current reference count of the resource.
void	release(ReferenceOwner id) Releases the resource by decrementing its reference count by one.
default void	releaseLast() Releases the resource for the initial owner and ensures that this release is the last usage of the resource.
void	releaseLast(ReferenceOwner id) Releases the resource and ensures that this release is the last usage of the resource.
void	removeReferenceChangeListener(ReferenceChangeListener referenceChangeListener) Removes a ReferenceChangeListener previously added via addReferenceChangeListener(ReferenceChangeListener).
void	reserve(ReferenceOwner id) Reserves the resource by incrementing its reference count by one.
boolean	reservedBy(ReferenceOwner owner) Deprecated. This method is deprecated and may be removed in future versions.
default void	reserveTransfer(ReferenceOwner from, ReferenceOwner to) Atomically transfers a reservation from one owner to another by incrementing the reference count for the new owner and decrementing it for the old owner.
boolean	tryReserve(ReferenceOwner id) Attempts to reserve the resource and returns true if successful.

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

referenceId, referenceName, temporary

Method Detail

reserve

void reserve(ReferenceOwner id)
      throws ClosedIllegalStateException,
             ThreadingIllegalStateException

Reserves the resource by incrementing its reference count by one.

It is required to reserve a resource before using it to prevent it from being freed.

Parameters:

id - The unique identifier representing the owner reserving the resource.

Throws:

ClosedIllegalStateException - If the resource has been released or closed. I.e. its reference counter has as some point reached zero.

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

reserveTransfer

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

Atomically transfers a reservation from one owner to another by incrementing the reference count for the new owner and decrementing it for the old owner.

Parameters:

from - The unique identifier representing the owner releasing the reservation.

to - The unique identifier representing the owner acquiring the reservation.

Throws:

ClosedIllegalStateException - If the resource has been released or closed.

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

tryReserve

boolean tryReserve(ReferenceOwner id)
            throws ClosedIllegalStateException,
                   IllegalArgumentException

Attempts to reserve the resource and returns true if successful. Unlike reserve(ReferenceOwner), this method will not throw an exception if the resource is already freed.

Parameters:

id - The unique identifier representing the owner attempting to reserve the resource.

Returns:

true if the resource was successfully reserved, false otherwise.

Throws:

IllegalArgumentException - If the reference owner is invalid.

ClosedIllegalStateException - If the resource has been released or closed.

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

reservedBy

@Deprecated
boolean reservedBy(ReferenceOwner owner)
                        throws ClosedIllegalStateException

Deprecated. This method is deprecated and may be removed in future versions.

Checks if the resource is reserved by the specified owner. Returns true if unsure.

This method provides a best-effort check and may not be accurate.

Parameters:

owner - The unique identifier representing the owner to check.

Returns:

false if it is certain that the owner does not have the resource reserved; true otherwise.

Throws:

ClosedIllegalStateException - If the resource has been released or closed.

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

release

void release(ReferenceOwner id)
      throws ClosedIllegalStateException

Releases the resource by decrementing its reference count by one. When the reference count reaches zero, the resource is freed.

Parameters:

id - The unique identifier representing the owner releasing the resource.

Throws:

ClosedIllegalStateException - If the resource has been released or closed. I.e. its reference counter has as some point reached zero.

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

releaseLast

void releaseLast(ReferenceOwner id)
          throws ClosedIllegalStateException

Releases the resource and ensures that this release is the last usage of the resource. The reference count is decremented and checked to be zero after this release.

Parameters:

id - The unique identifier representing the owner releasing the resource.

Throws:

ClosedIllegalStateException - If the resource has been released or closed.

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

releaseLast

default void releaseLast()
                  throws ClosedIllegalStateException

Releases the resource for the initial owner and ensures that this release is the last usage of the resource. The reference count is decremented and checked to be zero after this release.

Throws:

ClosedIllegalStateException - If the resource has been released or closed.

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

refCount

int refCount()

Returns the current reference count of the resource. The reference count indicates the number of owners currently holding reservations to the resource.

Returns:

The current reference count of the resource.

addReferenceChangeListener

void addReferenceChangeListener(ReferenceChangeListener referenceChangeListener)

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.

Parameters:

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

removeReferenceChangeListener

void removeReferenceChangeListener(ReferenceChangeListener referenceChangeListener)

Removes a ReferenceChangeListener previously added via 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.

Parameters:

referenceChangeListener - The listener to remove.