Join GitHub today
The Aeron URI, which is the channel specification provided when adding a publication or subscription, has the following format:
aeron-uri = ["aeron-spy:"] "aeron:" media [ "?" param *( "|" param ) ] media = *( "[^?:]" ) param = key "=" value key = *( "[^=]" ) value = *( "[^|]" )
All Media Transports
The following parameters are available on all media transports when applied to a Publication:
term-length - (optional) The term length to be applied to the log when adding a Publication. This parameter overrides the
sparse - (optional) Boolean value to indicate if a sparse file should be used to back the log buffers. This parameter overrides the
session-id - (optional) 32-bit signed integer value that is assigned for the session id to override the default generation for publications, or to restrict the scope of a subscription to a single session.
The following 3 parameters can be applied as a group to an Exclusive Publication for replay purposes:
- init-term-id - (optional) The initial term id which can be applied to an Exclusive Publication.
- term-id - (optional) The current term id which can be applied to an Exclusive Publication.
- term-offset - (optional) The current term id which can be applied to an Exclusive Publication.
IPC Media - Inter Process Communication
If shared memory is to be used for communications on the same machine between threads or processes then the IPC media value can be applied. This is the highest throughput and lowest latency means of communicating between two process or threads on the same machine.
The Aeron URI uses a media value of
udp to determine that messages will be sent via the UDP protocol. To distinguish between Unicast and Multicast, the UdpChannel will look at the specific parameters supplied and infer the appropriate choice.
Many of the values options are network addresses, in this case they can take for the form of a host name, IPv4, or IPv6 address enclosed in square brackets.
Both Unicast and Multicast channel configuration uses the same set of properties. Distinguishing between unicast and multicast is done by examining the endpoint address of the channel. The important configuration options are:
endpoint - (required unless MDC) The socket address to which publications will send messages and from which subscriptions will receive messages. This takes the
<host>:<port>format, where both the
interface - (optional) The socket address that identifies that local interface that will be used for receiving messages (and sending messages in the multicast case). The value can take the form
<host>[:<port>][/<subnet mask>]. When specified the system will scan the local interfaces for one that matches the specified pattern. The default value for this field is
[::]:0/0for IPv6). With a unicast configuration this will simply map to any local address and will listen for messages from all local network interfaces. This setting will only impact the behaviour of subscriptions for multicast, unicast publications will effectively ignore this value. With a multicast configuration this will scan all of the local network interfaces and will use the first non-loopback network interface that supports multicast, falling back to the local loopback if none are found.
control - (optional) Multi-Destination-Cast (MDC) control address to be used for dynamically allocating new destination streams. The value will be an IP address and port, e.g.
control-mode - (optional) Valid value is
manualif using the
dynamic, the default, if initiated by connections to the control address.
ttl - (optional) The TTL used for multicast traffic. Only used when the endpoint specified is a multicast address. This value is passed directly as the
IP_MULTICAST_TTLand should be within the range
0 - 255. A value outside this range will generate an exception set as the socket option.
mtu - (optional) The MTU is the Maximum Transmission Unit which sets the length limit for a UDP datagram payload on this stream. This overrides the
aeron.mtu.lengthproperty for the driver when adding a new Publication.
reliable - (optional) The reliable property when applied to a Subscription disables the NAK'ing of lost packets on the stream. The lost packets are gap filled so the stream can progress. Valid values are
falsewith the default being
linger - (optional) Timeout in nanoseconds a network publication should linger around to service NAKs. This parameter overrides the
tags - (optional) Identity and references for associating channels in simplifying configuration. See tags for more details.
Simple Unicast, with any local address used for binding subscriptions:
Unicast with a specific address to receive messages:
Unicast with a search pattern to identify an address to receive messages. This is especially useful if you have a large number of machines on the same network and want to reuse the same configuration string across all of them.
Use host names instead of addresses:
Or use IPv6:
It is also possible to specify an IPv6 address, but the IPv6 address portion needs to placed inside square brackets
To specify which interface to use, add the interface parameter. It will find the interface with that matches whose bound address matches the one specified. For an interface config, such as the following:
en0: flags=8863<UP,BROADCAST,SMART,RUNNING,SIMPLEX,MULTICAST> mtu 1500 ether 04:0c:ce:e3:c8:c0 inet6 fe80::60c:ceff:fee3:c8c0%en0 prefixlen 64 scopeid 0x4 inet 192.168.1.4 netmask 0xffffff00 broadcast 192.168.1.255 nd6 options=1<PERFORMNUD> media: autoselect status: active
Then the following configuration will ensure that the 'en0' interface is used.
Or similarly for IPv6.
However, having to specify a full IP for the interface can be difficult. Especially if you want to share the configuration throughout a number of machines in the same network. Therefore with the interface specification you specify a subnet mask to allow Aeron to search for an appropriate interface. The following will find an interface on the 192.168.1.x network. If there are multiple interfaces that match the criteria, the result will be undefined. The first interface returned from
NetworkInterface.getNetworkInterfaces() that matches the IP address pattern and supports multicast will be used.
/24 means that the first 24 bits of the IP address will be used when comparing against the IP addresses on the interface. Similarly for IPv6.
Hostnames can be used instead of IP addresses for both the group and interface parameters.
Simple multicast with specified TTL of 16.
Multi-Destination-Cast dynamic publication using control port of 40456.
Multi-Destination-Cast dynamic subscription using local endpoint port of 40457 and control port at 192.168.0.1 and port 40456
Multi-Destination-Cast manual publication using control port of 40456.
Outgoing Channel Spy
If you wish to subscribe to a local Publication without receiving the packets back in the network interface, for which they are being sent out, then this is possible by spying on a network publication as an optimisation. A spy Subscription will receive the messages over IPC without a copy.
- Spy subscriptions are not applicable to IPC media.
- Spy subscriptions do not affect the Publication connected status by default. They can simulate a connected publication if the
aeron.spies.simulate.connectionproperty is set, in which case the publication can progress if it only has spies.
- Spy subscriptions apply back-pressure like normal Subscriptions.