Aeron: Efficient reliable UDP unicast, UDP multicast, and IPC message transport

Aeron

To chat with other Aeron users and the contributors.

Efficient reliable UDP unicast, UDP multicast, and IPC message transport. Java and C++ clients are available in this repository via a third party.NET client. All three clients can exchanges messages across machines or on the same machine via IPC very efficiently.

Performance is the key focus. Aeron is designed to be the highest throughput with the lowest and most predictable latency possible of any messaging system. Aeron integrates with Simple Binary Encoding (SBE) for the best possible performance in message encoding and decoding. Many of the data structures used in the creation of Aeron have been factored out to theAgrona project.

For details of usage, protocol specification, FAQ, etc. please check out theWiki.

For those who prefer to watch a video then try Aeron Messaging from StrangeLoop 2014. Things have moved on quite a bit with performance and some features but the basic design still applies.

For the latest version information and changes see theChange Log with downloads at Maven Central .

How do I use Aeron? Java Programming Guide C++11 Programming Guide Best Practices Guide Monitoring and Debugging Configuration Options Channel Specific Configuration How does Aeron work? Protocol Specification Design Overview Design Principles Flow Control Semantics Media Driver Operation How do I hack on Aeron? Hacking on Aeron Performance Testing License (See LICENSE file for full license)

Copyright 2014 - 2016 Real Logic Limited

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Directory Structure

Client API and common classes

aeron-client

Samples

aeron-samples

Media Driver

aeron-driver Build Java Build

The project is built with Gradle using thisbuild.gradle file.

You require the following to build Aeron:

Latest stable Oracle JDK 8

You must first build and installAgrona into the local maven repository

$ ./gradlew

After Agrona is compiled and installed, then you can build Aeron.

Full clean and build of all modules

$ ./gradlew C++ Build

You require the following to build the C++ API for Aeron:

3.0.2 or higher of CMake C++11 supported compiler for the supported platform Requirements to buildHdrHistogram_c. HdrHistogram requires zlib.h currently.

NOTE: Aeron is supported on linux, Mac, and windows. Windows builds require Visual Studio and are being developed with Visual Studio 2013 and 2015 with 64-bit builds only. Cygwin, MSys, etc. may work, but are not maintained at this time.

For convenience, a script is provided that does a full clean, build, and test of all targets as a Release build.

$ ./cppbuild/cppbuild

If you are comfortable with using CMake, then a full clean, build, and test looks like:

$ mkdir -p cppbuild/Debug $ cd cppbuild/Debug $ cmake ../.. $ cmake --build . --clean-first $ ctest Documentation

If you have doxygen installed and want to build the Doxygen doc, there is a nice doc target that can be used.

$ make doc Packaging

If you would like a packaged version of the compiled API, there is the package target that uses CPack. If the doc has been built previous to the packaging, it will be included. Packages created are "TGZ;STGZ", but can be changed by running cpack directly.

$ make package C++ Driver

WARNING: The C++ media driver is currently in development. Any C++ code in aeron-driver should be considered experimental and may not build or work correctly at this time.

The driver can be added to the build and tests by enabling the CMake variable BUILD_AERON_DRIVER to ON .

Running Samples

Start up a media driver which will create the data and conductor directories. On Linux, this will probably be in /dev/shm/aeron or /tmp/aeron .

$ java -cp aeron-samples/build/libs/samples.jar io.aeron.driver.MediaDriver

Alternatively, specify the data and conductor directories. The following example uses the shared memory 'directory' on Linux, but you could just as easily point to the regular filesystem.

$ java -cp aeron-samples/build/libs/samples.jar -Daeron.dir=/dev/shm/aeron io.aeron.driver.MediaDriver

You can run the BasicSubscriber from a command line. On Linux, this will be pointing to the /dev/shm shared memory directory, so be sure your MediaDriver is doing the same!

$ java -cp aeron-samples/build/libs/samples.jar io.aeron.samples.BasicSubscriber

You can run the BasicPublisher from a command line. On Linux, this will be pointing to the /dev/shm shared memory directory, so be sure your MediaDriver is doing the same!

$ java -cp aeron-samples/build/libs/samples.jar io.aeron.samples.BasicPublisher

You can run the AeronStat utility to read system counters from a command line

$ java -cp aeron-samples/build/libs/samples.jar io.aeron.samples.AeronStat Media Driver Packaging

The Media Driver is packaged by the default build into an application that can be found here

aeron-driver/build/distributions/aeron-driver-${VERSION}.zip Troubleshooting

On linux, the subscriber sample throws an exception java.lang.InternalError(a fault occurred in a recent unsafe memory access operation in compiled Java code)

This is actually an out of disk space issue.

To alleviate, check to make sure you have enough disk space.

In the samples, on Linux, this will probably be either at /dev/shm/aeron or /tmp/aeron (depending on your settings).

See this thread for a similar problem.

Note: if you are trying to run this inside a Linux Docker, be aware that, by default, Docker only allocates 64 MB to the shared memory space at /dev/shm . However, the samples will quickly outgrow this.

You can work around this issue by running your Docker container in privileged mode and running this command:

mount -t tmpfs -o remount,rw,nosuid,nodev,noexec,relatime,size=1024M tmpfs /dev/shm

This will increase the size of /dev/shm to 1 GB. Hopefully you have enough memory :)