Media Driver

The reader should be familiar with the section on Agents & Idle Strategies before continuing.

The Media Driver component is responsible for managing the sending and receiving of data over the media (UDP or IPC) in use for any active publications and/or subscriptions. The Media Driver is flexible and can be configured to fit most scenarios, ranging from high performance with minimal latency all the way too relaxed, low resource environments. While the Media Driver is conceptually similar to a distributed message broker, it lacks several features one might expect of a message broker. Aeron's Media Driver is best thought of as being distinct from a message broker.

The diagram below shows the core components that make up a Media Driver embedded within an application.

Components¶

Driver Conductor¶

The Driver Conductor accepts commands from publishers and subscribers within the Aeron Client and orchestrates the actions of the Media Driver. Additionally, the Driver Conductor is responsible for name resolution tasks.

Receiver¶

The Receiver manages all data reception for the connected media. The Data Transport Poller receives UDP data, and uses Java NIO to interact with the operating system's network stack.

In addition to receiving data from the media, the Receiver manages the received images, sending NAK and Status messages as required.

Sender¶

The Sender manages the transmission of data over the media.

Client Conductor¶

The Client Conductor is responsible for communicating with the Driver Conductor

Media Driver Folder¶

Note

For production, this folder should reside on \dev\shm. You will need to ensure that the file system has sufficient storage space for all of the images and publications. For more details, see Publications & Subscriptions.

Tree

The above shows a Media Driver folder with a single IPC Publication open. The Media Driver folder contains:

Path	Notes
blank.template	An empty Log Buffer file, ready to be copied for a new publication
cnc.dat	This is the command-and-control memory mapped file shared between the Aeron Client and Media Driver. It is also the home of the Aeron counters as read by AeronStat.
images (folder)	This folder holds any open images of remote publications
loss-report.dat	This file stores all details of packet loss by Aeron. Useful for understanding the network behavior over time. The LossStat tool is used to read it.
publications (folder)	This folder holds all open publication log buffers.

Configuration & Runtime Deployment options¶

The Media Driver can either be run embedded or out of process. When running out of process, you can use either the Java or C Media Driver.

Other than the Media Driver, there are two other variants found in the Aeron source code:

Type	Notes
LowLatencyMediaDriver	Found in the samples folder. Sets up the Media Driver with optimum settings for low latency
JavaTestMediaDriver	Found in the test folder. Sets up a Media Driver with the ability to introduce loss

Configuration approaches¶

There are two alternative approaches available to configure the Media Driver:

via system properties. In this model, configuration is typically applied using -D arguments to the JVM; or
via the MediaDriver Context object. In this model, configuration is applied directly to the Media Driver Configuration object.

Key configuration items¶

Configuration value	Notes
`errorHandler`	Must be set in the Media Driver Context to allow your code to be notified of Media Driver errors. Without this set, the Media Driver may appear to fail silently, with errors only visable via the `ErrorStat` tool.
`aeronDirectoryName`	This is the folder shared across the Media Driver and Aeron client. Multiple Aeron clients (across processes) can access the share the same Media Driver
`idleStrategies`	There are a number of Idle Strategies that should be set for your specific requirements. See below on Media Driver Threading Mode
`deleteDirOnStart`	The `aeronDirectoryName` folder is always recreated on start, assuming there is not an existing active Media Driver and you have set this value to `false`. If `deleteDirOnStart` was set to `false`, and if there is an active (or recently active) Media Driver, then an `ActiveDriverException` exception will be thrown. If this value is set to `true`, and there is a running Media Driver, the other Media Driver will fail.
`deleteDirOnShutdown`	This clears the `aeronDirectoryName` folder on Media Driver exit.

Media Driver Threading Mode¶

Selecting the right resource allocation in the Media Driver should consider both the resources available to the process and the performance requirements. It can be highly detrimental to application stability and performance to over allocate resources to the Aeron process beyond those available.

Dedicated¶

In the dedicated threading mode (ThreadingMode.DEDICATED), the Media Driver will use 3 threads, each with a specific idle strategy:

the Sender (sender in thread dumps, uses senderIdleStrategy);
the Receiver (receiver in thread dumps, uses receiverIdleStrategy);
the Driver Conductor (driver-conductor in thread dumps, uses conductorIdleStrategy)

This is the default mode, and best used when performance is a concern and the system has sufficient resources. To further improve performance, pin the threads to specific CPU cores.

Shared Network¶

Running with shared network mode (ThreadingMode.SHARED_NETWORK) reduces the thread count to two:

the Sender and Receiver are scheduled in a composite agent ([sender-receiver] in thread dumps, uses sharedNetworkIdleStrategy);
the Driver Conductor (driver-conductor in thread dumps, uses conductorIdleStrategy)

Shared¶

Running with shared mode (ThreadingMode.SHARED), reduces the thread count to one.

A composite agent hosts the Sender, Receiver and Conductor agents. This can be seen as [sender-receiver-driver-conductor] in thread dumps, and makes use of the sharedIdleStrategy defined in the Media Driver Context. This is best suited for development or environments with lower resources available.

Invoker¶

When running with invoker mode (ThreadingMode.INVOKER), there is no thread started. An AgentInvoker hosts the Sender, Receiver and Conductor agents, and it is up to the caller to manage the duty cycle.

C Media Driver¶

By writing the driver in C, Real Logic have as much control as is possible given the hardware and operating systems they run on, and it allows the team to remove the performance sensitive components from the Java Virtual Machine and Garbage Collector.

From the Java side, using the C Media Driver is generally transparent. All you need to do is point your Aeron client to the C Media Driver's folder and, in theory, all will work as before.

As with the Java Media Driver running in the standalone mode, the C Media Driver can run with multiple Aeron clients if they are all on the same physical machine.

Getting the C Media Driver¶

The C Media Driver must be built from source (instructions will vary by your operating system):

Several C versions of Aeron Sample Tools (AeronStat, ErrorStat, LossStat) are built at the same time.

Configuring the C Media Driver¶

By default, the C Media Driver runs with:

three threads (sender, receiver, driver conductor) with a busy spin thread priority,
ten second driver timeout,
a 16mb term buffer length.

If you need to override the settings, you have two options:

load parameters from either a file or URL
pass in properties via the command line with the -D argument (the same as in Java), For example:
- -Daeron.driver.timeout=30000
pass in properties via environment variables by capitalising the property name and replacing '.' with '_'. For example:
- -Daeron.driver.timeout=30000 becomes AERON_DRIVER_TIMEOUT=30000