Name Resolution

Name Resolution and Re-Resolution

Channel parameter endpoint, for Publications, and control, for Subscriptions, point to remote entities. And thus when set with a string value must be resolved into IP addresses. The driver does this resolution when the Publication or Subscription is added via the API, In addition, if the driver determines that no data is flowing on a channel, it will attempt to re-resolve these parameters after a timeout. Currently 5 seconds. The driver checks for re-resolution on the re-resolution check interval.

aeron.driver.reresolution.check.interval=1s

or via the MediaDriver.Context.reResolutionCheckIntervalNs. This interval may be set to 0 to disable re-resolution checks and re-resolution attempts.

Starting with Aeron 1.44.0 release the address resolution is performed asynchronously. The number of async helper threads defaults to 1 and can set via the following property:

aeron.driver.async.executor.threads=1

or via MediaDriver.Context#asyncTaskExecutorThreads(int) method. It is also possible to set a custom ExecutorService in the Java driver (MediaDriver.Context#asyncTaskExecutor(java.util.concurrent.Executor)).

Note: C media driver is currently limited to a single helper thread as of 1.44.0 release, i.e. setting aeron.driver.async.executor.threads to a value larger than one would fail with an error.

When a resolution is attempted, the driver calls into the configured MediaDriver.Context.nameResolver. This is totally customizable. However, the default behavior will attempt to use the hosts name resolution features as configured by the operating system. For more information see the NameResolver javadoc or C driver doxygen.

Driver Names and Name Resolver

In addition to the default resolution behavior, it is possible to configure a MediaDriver instance with a name. This can be set by the system property.

aeron.driver.resolver.name=DriverName

or via MediaDriver.Context.resolverName. By default, the driver name is the canonical name of the host.

Media drivers can be configured to communicate with one another on a resolver interface and find each other via a specialized gossip protocol. This is disabled by default, but can be enabled by setting the following.

aeron.driver.resolver.interface=0.0.0.0:8050

or via MediaDriver.Context.resolverInterface. The format of the string is the same format used for the interface Channel URI parameter. This is the interface and UDP port that the resolver will use to listen for other media drivers. A value of 0 for the port means the driver will use an ephemeral port.

In addition, a media driver may be configured to point to a potential initial neighbor media driver, a "bootstrap neighbor" via the following.

aeron.driver.resolver.bootstrap.neighbor=192.168.0.45:8051

or via MediaDriver.Context.resolverBootstrapNeighbor. The format of this string is the same format used for the endpoint Channel URI parameter. Name resolution for this string always uses the hosts name resolver.

Once configured, the media drivers will gossip and find one another. As this happens, the names of media drivers may be used for hostname parameters within the endpoint and control channel URI parameters. For example,

Aeron.addPublication("aeron:udp?endpoint=DriverName:4030", 10)

The relative location of the driver will be used as the resolver name. If the driver moves to a new machine, the re-resolution logic mentioned above combined with the driver gossip protocol should within 10s of seconds be re-resolved with the new location of the driver.

When in use, driver names take precedent over hostnames. Thus when attempting to resolve a name, the driver will first try to find the name as a driver name. Failing that, the driver will then use the hosts name resolver.

Driver Name Resolver Counters

When in use, the driver maintains two counters relating to the driver name resolver. The first counter is the number of entries in the name cache. The label of this counter contains the name of the driver. The second counter is the number of neighbor media drivers the driver has discovered. The label for this counter includes the bound interface and UDP port and the bootstrap neighbor IP address and UDP port.

For more information please see the relevant Javadoc and C driver doxygen documentation as well as the relevant source code.