net.openhft.chronicle.queue

Interface ChronicleQueue

All Superinterfaces:

AutoCloseable, Closeable

All Known Implementing Classes:

AbstractChronicleQueue

public interface ChronicleQueue
extends Closeable

Chronicle (in a generic sense) is a Java project focused on building a persisted low latency messaging framework for high performance and critical applications.

Using non-heap storage options Chronicle provides a processing environment where applications does not suffer from GarbageCollection. GarbageCollection (GC) may slow down your critical operations non-deterministically at any time.. In order to avoid non-determinism and escape from GC delays off-heap memory solutions are addressed. The main idea is to manage your memory manually so does not suffer from GC. Chronicle behaves like a management interface over off-heap memory so you can build your own solutions over it.

Chronicle uses RandomAccessFiles while managing memory and this choice brings lots of possibility. Random access files permit non-sequential, or random, access to a file's contents. To access a file randomly, you open the file, seek a particular location, and read from or writeBytes to that file. RandomAccessFiles can be seen as "large" C-type byte arrays that you can access any random index "directly" using pointers. File portions can be used as ByteBuffers if the portion is mapped into memory.

ChronicleQueue (now in the specific sense) is the main interface for management and can be seen as the "Collection class" of the Chronicle environment. You will reserve a portion of memory and then put/fetch/update records using the ChronicleQueue interface.

Excerpt is the main data container in a ChronicleQueue, each Chronicle is composed of Excerpts. Putting data to a queue means starting a new Excerpt, writing data into it and finishing the Excerpt at the upper.

While Excerpt is a generic purpose container allowing for remote access, it also has more specialized counterparts for sequential operations. See ExcerptTailer and ExcerptAppender

Author:

peter.lawrey

Field Summary

Fields

Modifier and Type	Field and Description
static long	MINUS_1_40BIT

Method Summary

Modifier and Type	Method and Description
void	clear() Remove all the entries in the queue.
ExcerptAppender	createAppender() An Appender can be used to writeBytes new excerpts sequentially to the upper.
Excerpt	createExcerpt() An Excerpt can be used access entries randomly and optionally change them.
ExcerptTailer	createTailer() A Tailer can be used to read sequentially from the lower of a given position.
long	firstIndex()
static long	index(long cycle, long sequenceNumber)
long	lastIndex()
String	name()
long	size()
static long	toCycle(long index)
static long	toSequenceNumber(long index)
net.openhft.chronicle.wire.WireType	wireType()

Methods inherited from interface java.io.Closeable

close

Field Detail

MINUS_1_40BIT

static final long MINUS_1_40BIT

Method Detail

name

@NotNull
String name()

Returns:

A descriptive name for this queue which can be used for logging.

createExcerpt

@NotNull
Excerpt createExcerpt()

An Excerpt can be used access entries randomly and optionally change them.

Returns:

Excerpt

createTailer

@NotNull
ExcerptTailer createTailer()
                             throws IOException

A Tailer can be used to read sequentially from the lower of a given position.

Returns:

ExcerptTailer

Throws:

IOException - if an IO problem occurs

createAppender

@NotNull
ExcerptAppender createAppender()

An Appender can be used to writeBytes new excerpts sequentially to the upper.

Returns:

ExcerptAppender

Throws:

IOException - if an IO problem occurs

size

long size()

Returns:

The current estimated number of entries.

clear

void clear()

Remove all the entries in the queue.

firstIndex

long firstIndex()

Returns:

the lowest valid index available, or sequenceNumber=0 if none are found

lastIndex

long lastIndex()

Returns:

the highest valid index immediately available. Or -1 if none available. The lowest 40bits of the index refer to the sequence number with the cycle, giving a maximum of 1099511627776 excerpt per cycle. Each cycle has its own file. Each file holds its own index. You can discard the old files ( if they are no longer used ). The other highest 24 bits
 of the index are used for the cycle number (this equates to the filename), giving a maximum
 of 16777216 cycles ( aka files )

wireType

@NotNull
net.openhft.chronicle.wire.WireType wireType()

Returns:

the type of wire used, for example TEXT_WIRE or BINARY WIRE

toSequenceNumber

static long toSequenceNumber(long index)

toCycle

static long toCycle(long index)

index

static long index(long cycle,
                  long sequenceNumber)