net.openhft.chronicle.bytes.util

Class AbstractInterner<T>

java.lang.Object

net.openhft.chronicle.bytes.util.AbstractInterner<T>

Type Parameters:

T - the type of the object being interned

Direct Known Subclasses:

Bit8StringInterner, UTF8StringInterner

public abstract class AbstractInterner<T>
extends Object

This class provides a caching mechanism that returns a value which matches the decoded bytes. It does not guarantee the return of the same object across different invocations or from different threads, but it guarantees that the contents will be the same. Although not strictly thread-safe, it behaves correctly under concurrent access.

The main usage is to reduce the amount of memory used by creating new objects when the same byte sequence is repeatedly decoded into an object.

This cache only guarantees it will provide a String which matches the decoded bytes.

It doesn't guarantee it will always return the same object, nor that different threads will return the same object, though the contents should always be the same.

While not technically thread safe, it should still behave correctly.

Abstract base class for implementing an interning mechanism, which helps in reusing instances of immutable objects. This class is designed to store objects and return previously stored instances that are equal to the required instance.

Note: The interning cache may not always return the same object instance, but the contents of the instances will be equal. *

Field Summary

Fields

Modifier and Type	Field and Description
protected net.openhft.chronicle.bytes.util.AbstractInterner.InternerEntry<T>[]	entries The array storing InternerEntry objects.
protected int	mask Mask used to hash into entries, typically capacity - 1.
protected int	shift Shift value used when computing the secondary hash index.
protected boolean	toggle Flag toggled when choosing between the two hash slots for new entries.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractInterner(int capacity) Constructor for creating an intern cache with the given capacity.

Method Summary

Modifier and Type	Method and Description
protected abstract T	getValue(BytesStore<?,?> bs, int length) Converts the bytes from bs into an instance of T.
T	intern(@NotNull Bytes<?> cs) Interns the specified Bytes object.
T	intern(@NotNull Bytes<?> cs, int length) Interns the specified Bytes object of a given length.
T	intern(@NotNull BytesStore<?,?> cs) Interns the specified BytesStore object.
T	intern(@NotNull BytesStore<?,?> cs, int length) Interns the specified Bytes.
protected boolean	toggle() Toggles the internal toggle state and returns its new value.
int	valueCount() Returns the number of non-null values in the interner entries.

Methods inherited from class java.lang.Object

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

Field Detail

entries

protected final net.openhft.chronicle.bytes.util.AbstractInterner.InternerEntry<T>[] entries

The array storing InternerEntry objects. Concurrent modifications should be externally synchronised as no locking is performed here.

mask

protected final int mask

Mask used to hash into entries, typically capacity - 1.

shift

protected final int shift

Shift value used when computing the secondary hash index.

toggle

protected boolean toggle

Flag toggled when choosing between the two hash slots for new entries. It approximates a round-robin placement to avoid hot spots.

Constructor Detail

AbstractInterner

protected AbstractInterner(int capacity)

Constructor for creating an intern cache with the given capacity. The capacity will be adjusted to the next power of 2 if it is not already a power of 2, to a limit of 1 << 30. The resulting structure is not inherently thread safe.

Parameters:

capacity - the desired capacity for the intern cache

Throws:

IllegalArgumentException - if capacity is negative

Method Detail

intern

public T intern(@NotNull
                @NotNull Bytes<?> cs)
         throws net.openhft.chronicle.core.io.IORuntimeException,
                BufferUnderflowException,
                IllegalStateException

Interns the specified Bytes object. If the Bytes object is already in the cache, this method returns the cached instance; otherwise, it adds the Bytes object to the cache and returns the newly cached instance. The length of Bytes object for interning is determined by the remaining readable bytes.

Parameters:

cs - the Bytes object to intern

Returns:

the interned instance

Throws:

net.openhft.chronicle.core.io.IORuntimeException - If an I/O error occurs

NullPointerException - if cs is null

BufferUnderflowException - If there is not enough data in the buffer

net.openhft.chronicle.core.io.ClosedIllegalStateException - If the resource has been released or closed.

net.openhft.chronicle.core.io.ThreadingIllegalStateException - If this resource was accessed by multiple threads in an unsafe way

IllegalStateException

intern

public T intern(@NotNull
                @NotNull BytesStore<?,?> cs)
         throws net.openhft.chronicle.core.io.IORuntimeException,
                BufferUnderflowException,
                IllegalStateException

Interns the specified BytesStore object. If the BytesStore object is already in the cache, this method returns the cached instance; otherwise, it adds the BytesStore object to the cache and returns the newly cached instance. The length of BytesStore object for interning is determined by the remaining readable bytes.

Parameters:

cs - the BytesStore object to intern

Returns:

the cached object instance

Throws:

NullPointerException - if cs is null

net.openhft.chronicle.core.io.IORuntimeException - If an I/O error occurs

BufferUnderflowException - If there is not enough data in the buffer

net.openhft.chronicle.core.io.ClosedIllegalStateException - If the resource has been released or closed.

net.openhft.chronicle.core.io.ThreadingIllegalStateException - If this resource was accessed by multiple threads in an unsafe way

IllegalStateException

intern

public T intern(@NotNull
                @NotNull Bytes<?> cs,
                int length)
         throws net.openhft.chronicle.core.io.IORuntimeException,
                BufferUnderflowException,
                IllegalStateException

Interns the specified Bytes object of a given length. If the Bytes object is already in the cache, this method returns the cached instance; otherwise, it adds the Bytes object to the cache and returns the newly cached instance.

Parameters:

cs - the Bytes object to intern

length - the length of the Bytes object to intern

Returns:

the cached object instance

Throws:

NullPointerException - if cs is null

net.openhft.chronicle.core.io.IORuntimeException - If an I/O error occurs

BufferUnderflowException - If there is not enough data in the buffer

net.openhft.chronicle.core.io.ClosedIllegalStateException - If the resource has been released or closed.

net.openhft.chronicle.core.io.ThreadingIllegalStateException - If this resource was accessed by multiple threads in an unsafe way

IllegalStateException

intern

public T intern(@NotNull
                @NotNull BytesStore<?,?> cs,
                int length)
         throws net.openhft.chronicle.core.io.IORuntimeException,
                BufferUnderflowException,
                IllegalStateException

Interns the specified Bytes. If the Bytes are already in the cache, this method returns the cached instance; otherwise, it adds the Bytes to the cache and returns the newly cached instance.

Parameters:

cs - the Bytes to intern

length - number of bytes to read from cs

Returns:

the cached object instance

Throws:

NullPointerException - if cs is null

net.openhft.chronicle.core.io.IORuntimeException - If an I/O error occurs

BufferUnderflowException - If there is not enough data in the buffer

net.openhft.chronicle.core.io.ClosedIllegalStateException - If the resource has been released or closed.

net.openhft.chronicle.core.io.ThreadingIllegalStateException - If this resource was accessed by multiple threads in an unsafe way

IllegalStateException

getValue

@NotNull
protected abstract T getValue(BytesStore<?,?> bs,
                                       int length)
                                throws net.openhft.chronicle.core.io.IORuntimeException,
                                       IllegalStateException,
                                       BufferUnderflowException

Converts the bytes from bs into an instance of T. The implementation must read exactly length bytes starting from bs.readPosition() without modifying that position.

Parameters:

bs - the bytes store supplying the data

length - the number of bytes to read

Returns:

the value derived from the byte sequence

Throws:

net.openhft.chronicle.core.io.IORuntimeException - if an I/O error occurs

BufferUnderflowException - if there is insufficient data available

net.openhft.chronicle.core.io.ClosedIllegalStateException - if the resource has been released or closed

net.openhft.chronicle.core.io.ThreadingIllegalStateException - if accessed by multiple threads unsafely

IllegalStateException

toggle

protected boolean toggle()

Toggles the internal toggle state and returns its new value.

Returns:

the new state of the toggle

valueCount

public int valueCount()

Returns the number of non-null values in the interner entries.

Returns:

the count of non-null values