Skip to content

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.

media-driver Sender Publication Subscription Media Driver Conductor Client Conductor Receiver Client Application Volatile Fields & Queues Media Driver IPC Ring/Broadcast Buffers IPC/UDP IPC Log Buffer

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:

  1. the Sender (sender in thread dumps, uses senderIdleStrategy);
  2. the Receiver (receiver in thread dumps, uses receiverIdleStrategy);
  3. 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:

  1. the Sender and Receiver are scheduled in a composite agent ([sender-receiver] in thread dumps, uses sharedNetworkIdleStrategy);
  2. 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 parameters via the command line with the -D argument (the same as in Java), changing . to _. For example:
    • -Daeron.driver.timeout=30000 becomes
    • -Daeron_driver_timeout=30000