net.openhft.chronicle.bytes

Interface RandomCommon

All Superinterfaces:

net.openhft.chronicle.core.io.ReferenceCounted, net.openhft.chronicle.core.io.ReferenceOwner

All Known Subinterfaces:

Bytes<U>, BytesIn<U>, BytesOut<U>, BytesStore<B,U>, ByteStringAppender<B>, ByteStringParser<B>, RandomDataInput, RandomDataOutput<R>, StreamingCommon<S>, StreamingDataInput<S>, StreamingDataOutput<S>

All Known Implementing Classes:

AbstractBytes, net.openhft.chronicle.bytes.internal.AbstractBytesStore, GuardedNativeBytes, HexDumpBytes, MappedBytes, MappedBytesStore, NativeBytes, net.openhft.chronicle.bytes.internal.NativeBytesStore, OnHeapBytes, PointerBytesStore, SubBytes, UncheckedBytes, UncheckedNativeBytes, VanillaBytes

public interface RandomCommon
extends net.openhft.chronicle.core.io.ReferenceCounted

A foundational interface for random access to a byte sequence or buffer. It defines start position, capacity and cursor operations. Extends ReferenceCounted for lifecycle management and underpins RandomDataInput and RandomDataOutput.

Field Summary

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

INIT, TMP

Method Summary

Modifier and Type	Method and Description
long	addressForRead(long offset) Retrieves the underlying memory address for reading.
default long	addressForRead(long offset, int buffer) Retrieves the underlying memory address for reading.
long	addressForWrite(long offset) Retrieves the underlying memory address for writing.
long	addressForWritePosition() Retrieves the underlying memory address for writing at the current write position.
default ByteOrder	byteOrder() Retrieves the byte order used by the buffer.
@NotNull Bytes<?>	bytesForRead()
@NotNull Bytes<?>	bytesForWrite() Retrieves a Bytes object for writing.
default long	capacity()
boolean	isDirectMemory() Checks if the buffer uses direct memory.
default long	lengthWritten(long startPosition) Calculates the length of data written from the given start position.
default long	readLimit() If the resource is closed, the returned value is unspecified.
default long	readPosition() /**
default long	readRemaining() Calculates the number of bytes remaining that can be read from the current read position.
default long	realCapacity()
default long	realReadRemaining() Calculates the number of bytes that can be safely read directly.
default long	realWriteRemaining() Calculates the number of bytes remaining that can be written from the current write position with resizing.
boolean	sharedMemory() Checks if the Bytes use shared memory.
default long	start()
default long	writeLimit() Retrieves the maximum writable position within the buffer.
default long	writePosition()
default long	writeRemaining() Calculates the number of bytes remaining that can be written from the current write position.

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

addReferenceChangeListener, refCount, release, releaseLast, releaseLast, removeReferenceChangeListener, reserve, reserveTransfer, tryReserve

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

referenceId, referenceName, temporary

Method Detail

start

default long start()

Returns:

The smallest position allowed in this buffer.

capacity

default long capacity()

Returns:

the maximum addressable capacity. May be as large as Bytes.MAX_CAPACITY for virtual mappings.

realCapacity

default long realCapacity()

Returns:

the current allocated capacity of the underlying storage. For elastic buffers this may be less than capacity() and can grow on demand.

readPosition

default long readPosition()

/**

Returns:

the current read position. Typically start() <= readPosition() <= writePosition() and readPosition() <= readLimit().

writePosition

default long writePosition()

Returns:

the current write position. Typically readPosition() <= writePosition() <= writeLimit().

lengthWritten

default long lengthWritten(long startPosition)

Calculates the length of data written from the given start position.

Typically this calculates the difference however for HexDumpBytes it's not as simple.

If the resource is closed, the returned value is unspecified.

Parameters:

startPosition - The position to calculate the length from.

Returns:

The length of data written from the given start position.

readRemaining

default long readRemaining()

Calculates the number of bytes remaining that can be read from the current read position.

If the resource is closed, the returned value is unspecified.

Returns:

The number of bytes that can still be read.

realReadRemaining

default long realReadRemaining()

Calculates the number of bytes that can be safely read directly.

If the resource is closed, the returned value is unspecified.

Returns:

The number of bytes that can be safely read directly.

writeRemaining

default long writeRemaining()

Calculates the number of bytes remaining that can be written from the current write position.

If the resource is closed, the returned value is unspecified.

Returns:

The number of bytes that can still be written.

realWriteRemaining

default long realWriteRemaining()

Calculates the number of bytes remaining that can be written from the current write position with resizing.

If the resource is closed, the returned value is unspecified.

Returns:

The number of bytes that can still be written with resizing.

readLimit

default long readLimit()

If the resource is closed, the returned value is unspecified.

Returns:

the highest offset or position allowed for this buffer.

writeLimit

default long writeLimit()

Retrieves the maximum writable position within the buffer.

If the resource is closed, the returned value is unspecified.

Returns:

the write limit

addressForRead

long addressForRead(long offset)
             throws UnsupportedOperationException,
                    BufferUnderflowException,
                    net.openhft.chronicle.core.io.ClosedIllegalStateException,
                    net.openhft.chronicle.core.io.ThreadingIllegalStateException

Retrieves the underlying memory address for reading. This is for expert users only.

Parameters:

offset - within this buffer. addressForRead(start()) is the actual addressForRead of the first byte.

Returns:

the underlying addressForRead of the buffer

Throws:

UnsupportedOperationException

BufferUnderflowException

net.openhft.chronicle.core.io.ClosedIllegalStateException

net.openhft.chronicle.core.io.ThreadingIllegalStateException

addressForRead

default long addressForRead(long offset,
                            int buffer)
                     throws UnsupportedOperationException,
                            BufferUnderflowException,
                            net.openhft.chronicle.core.io.ClosedIllegalStateException,
                            net.openhft.chronicle.core.io.ThreadingIllegalStateException

Retrieves the underlying memory address for reading. This is for expert users only.

Parameters:

offset - the logical offset within this buffer relative to start().

buffer - the buffer index if this store is backed by multiple buffers.

Returns:

the native address for the specified offset.

Throws:

UnsupportedOperationException - if the buffer uses heap memory.

BufferUnderflowException - if the offset is outside the allowed range.

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

net.openhft.chronicle.core.io.ThreadingIllegalStateException - if accessed concurrently in an unsafe way.

addressForWrite

long addressForWrite(long offset)
              throws UnsupportedOperationException,
                     BufferOverflowException,
                     net.openhft.chronicle.core.io.ClosedIllegalStateException,
                     net.openhft.chronicle.core.io.ThreadingIllegalStateException

Retrieves the underlying memory address for writing. This is for expert users only.

Parameters:

offset - within this buffer. addressForRead(start()) is the actual addressForRead of the first byte.

Returns:

the underlying addressForRead of the buffer

Throws:

UnsupportedOperationException - If the underlying buffer is on the heap

BufferOverflowException - If the offset is before the start() or the after the capacity()

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

addressForWritePosition

long addressForWritePosition()
                      throws UnsupportedOperationException,
                             BufferOverflowException,
                             net.openhft.chronicle.core.io.ClosedIllegalStateException

Retrieves the underlying memory address for writing at the current write position. This is for expert users only.

Returns:

The underlying memory address for writing at the current write position.

Throws:

UnsupportedOperationException - If the underlying buffer is on the heap.

BufferOverflowException - If the current write position is before the start or after the capacity.

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

byteOrder

default ByteOrder byteOrder()

Retrieves the byte order used by the buffer.

Returns:

The byte order used by the buffer.

bytesForRead

@NotNull
@NotNull Bytes<?> bytesForRead()
                                 throws net.openhft.chronicle.core.io.ClosedIllegalStateException,
                                        net.openhft.chronicle.core.io.ThreadingIllegalStateException

Returns:

a Bytes view for reading from this buffer. The returned view reflects the current positions and limits.

Throws:

net.openhft.chronicle.core.io.ClosedIllegalStateException

net.openhft.chronicle.core.io.ThreadingIllegalStateException

bytesForWrite

@NotNull
@NotNull Bytes<?> bytesForWrite()
                                  throws net.openhft.chronicle.core.io.ClosedIllegalStateException

Retrieves a Bytes object for writing.

Returns:

A Bytes object for writing.

Throws:

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

sharedMemory

boolean sharedMemory()

Checks if the Bytes use shared memory.

Returns:

True if the Bytes use shared memory, false otherwise.

isDirectMemory

boolean isDirectMemory()

Checks if the buffer uses direct memory.

Returns:

True if the buffer uses direct memory, false otherwise.