Home

See the Change Log for what has gone into each release.

How do I use Aeron?

1. Java Programming Guide
2. C++11 Programming Guide
3. Running Samples
4. Best Practices Guide
5. Monitoring and Debugging
6. Configuration Options
7. Channel Specific Configuration
8. Response Channels
9. Client Concurrency Model
10. Thread Utilisation
11. Message Delivery Assurances
12. Aeron Archive (Durable/Persistent Streams)
13. Multiple Destination Publications & Subscriptions
14. Name Resolution
15. Cluster Tutorial
16. Troubleshooting

How does Aeron work?

1. Transport Protocol Specification
2. Design Overview
3. Data Structures
4. Design Principles
5. Flow and Congestion Control
6. Media Driver Operation
7. C Media Driver Operation

How do I hack on Aeron?

1. Hacking on Aeron
2. Performance Testing
3. Building Aeron

Guides and Blogs

1. Aeron Docs.
2. Aeron Guide by Mark Raynsford.
3. Flow Control in Aeron by Mike Barker.
4. Aeron Driver Name Resolution by Mike Barker.

FAQ

1. Q: What does the name, Aeron, mean?

   A: In Celtic mythology, Aeron is the god of battle or slaughter. It can be given as a name to a girl or a boy and means “battle ending”. It's the name of this project... and the name of a chair.

2. Q: Why? Isn't TCP enough for anyone?

   A: There is a need for low latency transport protocols for capital markets use cases. TCP is not suitable for low latency due to the tradeoff between bandwidth usage after loss and responsiveness. In addition, modifying TCP congestion control to make a different tradeoff is fraught with peril. The API provided by TCP in the form of BSD sockets is not suited well to applications that require message boundaries to be preserved as is most non-file transfer use cases, which is, well, pretty much everything in a low latency environment. Also, TCP does not support reliable multicast communication. All these combine to make TCP a very very poor choice as a transport protocol for low latency applications.

3. Q: Isn't this a brokered architecture? Isn't that bad for latency?

   A: Yes, it is a brokered architecture. However, it is unlike traditional brokered architectures in a number of ways. First, the driver only communicates via shared memory with clients. Secondly, the driver uses dedicated threads on lock-free & wait-free data structures for sending and receiving. Third, the use case primarily is one of those threads being pinned to dedicated CPUs to avoid cache pollution and scheduling jitter. And Fourth, the driver can be embedded into an application if desired. Fundamentally, the difference is that whether isolated by threads or processes, the application is separated from the protocol driver logic via core-to-core communication over lock-free & wait-free data structures.

4. Q: The protocol specification says that Little Endian is used for byte order of fields. Network order is always Big Endian. Why doesn't Aeron use Big Endian?

   A: The primary latency sensitive systems in use today are Little Endian. Adding unnecessary byte reversal would be wasteful. Adding conditional checks for byte ordering to frames would be wasteful. If the need arises in the future, highly doubtful, to be conditionally Big Endian, then the Version field would be used to hold a Big Endian field bit flag.

5. Q: Why aren't streams identified with Strings instead of numbers?

   A: This is pure efficiency. Handling of strings in some languages is prohibitively expensive. Aeron tries to be as efficient as possible and provide the basic functionality that more complex systems can be composed with. If desired, the application, or a library, could provide String to Stream ID lookup.

6. Q: When using the built in fragmentation support, is there a maximum limit to the message length?

   A: Messages need to be contiguous when stored in the log/term buffers. Therefore message length must be less than the term length. We have chosen a limit of 1/8th the term buffer length for maximum message length. This is a compromise to limit fragmentation under concurrent publication. Messages larger than this should be chunked before publication to Aeron.

7. Q: Why only support for Java 8?

   A: Some of the core algorithms for the log and broadcast buffers require access to the Fences API and the new Unsafe intrinsics for getAndAdd() that are implemented as LOCK XADD on x86.

8. Q: How does release numbering work?

   A: Aeron will follow a <Major>.<Minor>.<Patch> release numbering scheme.
   Major Release: Major API change that can possibly be breaking.
   Minor Release: Significant new features that are API extending and preserving.
   Patch Release: Bugfixes and feature refinement.

9. Q: My build is failing, what can be wrong?

   A: Early versions of Java 8 have bugs that can generate incorrect code. Please use the latest version of Java 8 with an absolute minimum of 1.8.0_65. Aeron is tested and supported on Java 8, 11, and 17.

10. Q: Aeron seems slow on Mac OS, why is that?

    A: Mac OS does not have a concept of /dev/shm so the Aeron directory is created on a normal disc. Which means that access to the metadata requires disc access whereas on Linux /dev/shm is used by default and therefore no disc access occurs.

    You can create a RAM disc in Mac OS and place Aeron directory there. See Best-Practices-Guide#macdarwin on how to do that.