Aeron.NET
A .NET port of the Aeron Client.
Aeron is an efficient reliable UDP unicast, UDP multicast, and IPC message transport.
Performance is the key focus. Aeron is designed to have the highest throughput with the lowest and most predictable latency possible of any messaging system. Aeron is designed not to perform any allocations after the initial set-up, this means less time will be spent garbage collecting and as a result, latency will be kept down.
Getting Started
Aeron comes in two parts: the media driver and the client.
Media Driver
The driver runs in its own process and communicates with the client directly via shared memory. It sends and receives messages across the network to other drivers or routes messages to other clients on the same host.
To run the media driver, you will need Java 8 JRE installed.
There is a nuget package that contains the driver:
PM> Install-Package Aeron.Driver
It will create a directory in your project with a bat file to launch the driver.
Or if you've got the source, run:
driver/start-media-driver.bat
Client
The client can be built from source or installed from nuget: https://www.nuget.org/packages/Aeron.Client/
PM> Install-Package Aeron.Client
Usage
The full example is here.
Publisher
Used to send messages to a specified channel & stream.
const string channel = "aeron:ipc";
const int streamId = 42;
UnsafeBuffer buffer = new UnsafeBuffer(new byte[256]);
using(Aeron aeron = Aeron.Connect())
using(Publication publisher = aeron.AddPublication(channel, streamId)) {
int messageLength = buffer.PutStringWithoutLengthUtf8(0, "Hello World!");
publisher.Offer(buffer, 0, messageLength);
}
Fragment Handler
A fragment handler is a delegate used for processing data that is has been received. The buffer will either contain a whole message or a fragment of a message to be reassembled.
static void PrintMessage(IDirectBuffer buffer, int offset, int length, Header header)
{
var message = buffer.GetStringWithoutLengthUtf8(offset, length);
Console.WriteLine($"Message Received: '{message}'");
}
Subscriber
A subscriber is used to register interest in messages from a publisher on a specific channel & stream. It uses a fragment handler to process the received messages.
using(Subscription subscriber = aeron.AddSubscription(channel, streamId)) {
while(subscriber.Poll(PrintMessage, 1) == 0) {
Thread.Sleep(10);
}
}
Samples
Here are some of the samples that come with Aeron. Before running the samples, they need to be built (you will need Visual Studio 2017 installed). Run:
scripts/build.bat
Hello World
This samples sends and receives a hello world message. Make sure the media driver is running and run the following batch script:
scripts/hello-world.bat
You should see something like:
Received message (Hello World!) to stream 42 from session 42d2f651 term id de97c9e0 term offset 0 (11@32)
Press any key to continue...
The source code is here.
Throughput
This sample shows the overall throughput of the client and driver. It sends messages via aeron:ipc
which is designed for interprocess communication. Make sure the media driver is running and run the sample:
scripts/throughput.bat
It runs 2 threads which publish and subscribe 32-byte messages and every second prints out the number of messages & total number of bytes that were sent/received.
Duration 1,001ms - 14,047,600 messages - 449,523,200 bytes
Duration 1,000ms - 14,031,801 messages - 449,017,632 bytes
Duration 1,001ms - 15,054,055 messages - 481,729,760 bytes
Duration 1,000ms - 14,678,982 messages - 469,727,424 bytes
The source code is here.
Ping/Pong
This sample show the latencies for a batch of messages. Make sure the media driver is running and start pong
which listens for messages and will reply back to each message:
scripts/pong.bat
Then start ping
which send messages with the current time to pong
and then records the latency when it receives a response to that message.
scripts/ping.bat
After 1,000,000 messages have been sent, you'll be presented with a histogram.
Histogram of RTT latencies in microseconds.
Value Percentile TotalCount 1/(1-Percentile)
9.391 0.000000000000 1 1.00
11.383 0.100000000000 11404 1.11
11.663 0.200000000000 25421 1.25
11.951 0.300000000000 43399 1.43
11.951 0.400000000000 43399 1.67
15.647 0.500000000000 52070 2.00
15.935 0.550000000000 57140 2.22
16.215 0.600000000000 64190 2.50
16.511 0.650000000000 68864 2.86
17.071 0.700000000000 71236 3.33
17.647 0.750000000000 82369 4.00
17.647 0.775000000000 82369 4.44
17.647 0.800000000000 82369 5.00
17.935 0.825000000000 90885 5.71
...
5013.503 0.999989318848 99999 93622.86
5021.695 0.999990844727 100000 109226.67
5021.695 1.000000000000 100000
#[Mean = 15.195, StdDeviation = 46.974]
#[Max = 5021.695, Total count = 100000]
#[Buckets = 24, SubBuckets = 2048]
Which you can upload to http://hdrhistogram.github.io/HdrHistogram/plotFiles.html to create a nice chart:
The source code is here and here.
Building from Source
You will need Visual Studio 2017 Update 3 installed. Also, as the tooling hasn't caught up yet you'll need the last .NET Core SDK
- Open
src/Adaptive.Aeron.sln
. - Click
Build -> Build Solution
.
Note: For best performance, build in x64 release mode and run without the debugger attached.
Running tests
As Aeron.NET now supports multitargeting, the only way to properly run tests for all framework versions is from dotnet cli issuing dotnet test
on the test project folders, Visual Studio 2017 will only detect one project when launching the test runner
Packing NuGets
Run dotnet pack src\Adaptive.Aeron\Adaptive.Aeron.csproj /p:Configuration=Release
If there are also changes in Agrona run src\Adaptive.Agrona\Adaptive.Agrona.csproj /p:Configuration=Release
Aeron depends on it so both should be published at the same time
More Information
The best place for more information is the Aeron Wiki