Introduction to Chronicle Queue – 编年史队列简介

最后修改: 2017年 7月 15日

中文/混合/英文(键盘快捷键：t)

1. Overview

1.概述

Chronicle Queue persists every single message using a memory-mapped file. This allows us to share messages between processes.

Chronicle Queue使用一个内存映射文件来持久化每一条消息。这使我们能够在进程之间共享消息。

It stores data directly to off-heap memory, therefore, making it free of GC overhead. It is designed for providing low-latency message framework for high-performance applications.

它直接将数据存储到堆外内存，因此，使其没有GC开销。它被设计用来为高性能应用程序提供低延迟的消息框架。

In this quick article, we will look into the basic set of operations.

在这篇快速的文章中，我们将研究一下基本的操作集。

2. Maven Dependencies

2.Maven的依赖性

We need to add the following dependency:

我们需要添加下面的依赖关系。

<dependency>
    <groupId>net.openhft</groupId>
    <artifactId>chronicle</artifactId>
    <version>3.6.4</version>
</dependency>

We can always check the latest versions hosted by the Maven Central with the link provided before.

我们可以通过之前提供的链接随时查看Maven中心托管的最新版本。

3. Building Blocks

3.积木式建筑

There are three concepts characteristic for Chronicle Queue:

Chronicle Queue有三个概念的特点。

  • Excerpt – is a data container
  • Appender – appender is used for writing data
  • Trailer – is used for sequentially reading data

We’ll reserve the portion of memory for read-write operations using Chronicle interface.

我们将使用Chronicle接口为读写操作保留这部分内存。

Here is the example code for creating an instance:

下面是创建一个实例的示例代码。

File queueDir = Files.createTempDirectory("chronicle-queue").toFile();
Chronicle chronicle = ChronicleQueueBuilder.indexed(queueDir).build();

We will need a base directory where the queue will persist records in memory-mapped files.

我们将需要一个基础目录，队列将在内存映射的文件中持久保存记录。

ChronicleQueueBuilder class provides different types of queues. In this case, we used IndexedChronicleQueue which uses the sequential index to maintain memory offsets of records in a queue.

ChronicleQueueBuilder类提供不同类型的队列。在这种情况下，我们使用了IndexedChronicleQueue，它使用顺序索引来维护队列中记录的内存偏移。

4. Writing to the Queue

4.向队列写东西

To write the items to a queue, we’ll need to create an object of ExcerptAppender class using Chronicle instance. Here is example code for writing the messages to the queue:

为了将项目写入队列，我们需要使用Chronicle实例创建一个ExcerptAppender类的对象。下面是向队列中写入消息的示例代码。

Here is example code for writing the messages to the queue:

下面是向队列中写入消息的示例代码。

ExcerptAppender appender = chronicle.createAppender();
appender.startExcerpt();

String stringVal = "Hello World";
int intVal = 101;
long longVal = System.currentTimeMillis();
double doubleVal = 90.00192091d;

appender.writeUTF(stringValue);
appender.writeInt(intValue);
appender.writeLong(longValue);
appender.writeDouble(doubleValue);
appender.finish();

After creating the appender, we will start the appender using a startExcerpt method. It starts an Excerpt with the default message capacity of 128K. We can use an overloaded version of startExcerpt to provide a custom capacity.

创建appender后，我们将使用startExcerpt方法启动appender。它以默认的消息容量128K启动一个Excerpt。我们可以使用startExcerpt的重载版本来提供一个自定义容量。

Once started, we can write any literal or object value to the queue using a wide range of write methods provided by the library.

一旦启动，我们可以使用库中提供的各种写法将任何文字或对象值写到队列中。

Finally, when we’re done with writing, we’ll finish the excerpt, save the data to a queue, and later to disc.

最后，当我们写完后，我们将完成摘录，把数据保存到队列中，以后再保存到光盘中。

5. Reading from the Queue

5.从队列中读取信息

Reading the values from the queue can easily be done using the ExcerptTrailer instance.

使用ExcerptTrailer实例可以轻松地从队列中读取值。

It is just like an iterator we use to traverse a collection in Java.

它就像我们在Java中用来遍历一个集合的迭代器。

Let’s read values from the queue:

让我们从队列中读取数值。

ExcerptTailer tailer = chronicle.createTailer();
while (tailer.nextIndex()) {
    tailer.readUTF();
    tailer.readInt();
    tailer.readLong();
    tailer.readDouble();
}
tailer.finish();

After creating the trailer, we use the nextIndex method to check if there is a new excerpt to read.

在创建完预告片后，我们使用nextIndex方法来检查是否有新的摘录可以阅读。

Once ExcerptTailer has a new Excerpt to read, we can read messages from it using a range of read methods for literal and object type values.

一旦ExcerptTailer有一个新的Excerpt要读取，我们可以使用一系列的read方法来读取字面和对象类型值的信息。

Finally, we finish the reading with the finish API.

最后，我们用finish API完成阅读。

6. Conclusion

6.结论

In this tutorial, we gave a brief introduction to the Chronicle Queue and its building blocks. We saw how to create a queue, write and read data. Using it offers many benefits including low latency, durable interprocess communication (IPC) as well as no Garbage Collection overhead.

在本教程中，我们简要介绍了Chronicle Queue及其构建模块。我们看到了如何创建一个队列，写入和读取数据。使用它有很多好处，包括低延迟、持久的进程间通信（IPC）以及没有垃圾回收的开销。

The solution provides data persistence through memory mapped files – with no data loss. It also allows concurrent read-writes from multiple processes; however, writes are handled synchronously.

该解决方案通过内存映射的文件提供数据持久性–没有数据损失。它还允许从多个进程中同时进行读-写；但是，写是同步处理的。

As always, all code snippets can be found over on GitHub.

一如既往，所有的代码片段都可以在GitHub上找到。