-
Notifications
You must be signed in to change notification settings - Fork 894
Multiple Destinations
Both Publications and Subscriptions in Aeron can support the concept of multiple simultaneous destinations. For Publications, this means the outgoing stream is sent to each destination individually. For subscriptions, this means the incoming stream(s) may be received by a number of individual endpoints.
Aeron Publications can be configured to operate in a multiple destination mode separate from UDP multicast. Whereas multicast sends to an IP multicast address, Multi-Destination-Cast (MDC) sends a UDP unicast stream to each Receiver individually. This behaviour mimics UDP multicast operation for purposes of Flow and Congestion Control. Each destination is treated as a normal multicast receiver would be handled with respect to flow and congestion control.
An MDC Publication operates in one of two modes. It either dynamically allows destinations to be added and removed or manually controls the add and remove of destinations.
In dynamic control mode, the Publication uses a control address, see Channel Configuration, to specify the address and port that the publication will use for receiving Status Messages and NAKs, as well as be the point of contact for the Publication to add and remove destinations dynamically. Multi-Destination-Cast dynamic publication using control port of 40456.
aeron:udp?control=localhost:40456|control-mode=dynamic
The Subscriptions will need to specify this control address and port, in addition to their own endpoint address. Multi-Destination-Cast dynamic subscription using local endpoint port of 40457 and control port at 192.168.0.1 and port 40456
aeron:udp?endpoint=localhost:40457|control=192.168.0.1:40456|control-mode=dynamic
Subscriptions that go away will be timed out by the Publication and the Publication will stop sending data to them and accounting for them with flow control.
In control-mode=manual operation. The user application calls Publication.addDestination(endpoint) to add specific destination endpoints, and removes them explicitly with Publication.removeDestination(endpoint). Multi-Destination-Cast manual publication using control port of 40456.
aeron:udp?control=localhost:40456|control-mode=manual
In manual mode subscriptions do not need to specify control address and port. Normal endpoint specification is adequate.
The destination channel used with Publication.addDestination(endpoint) and Publication.removeDestination(endpoint) should only include endpoint specification. All else will be ignored. Below is an example of adding a subscription endpoint at localhost and port 30567.
Publication.addDestination("aeron:udp?endpoint=localhost:30567")A Subscription may be initialised without an endpoint so that multiple endpoints may be added or removed later. For this to occur. A Subscription needs to provide a control-mode=manual parameter.
aeron:udp?control-mode=manual
In order for another Subscription to share the same driver Subscription, Tags may be used. If multiple client Subscriptions map to the same driver Subscription, then any adding or removing of destinations is shared by all client instances.
Once a Subscription has been created that allows manual control of destinations, the API methods Subscription.addDestination(endpoint) and Subscription.removeDestination(endpoint) may be used to add and remove specific destination endpoints for the Subscription to listen on. These endpoints follow the normal channel rules for operation. It is possible for a Subscription to mix, UDP unicast, UDP multicast, and dynamic/manual MDC endpoints as desired.
MDS subscriptions can be session-specific to reduce the scope of joined images. In this case the session-id param is added to the subscription and not to each of the destinations. If a session-id param is added to a destination then it is ignored.
UDP unicast destination with endpoint of localhost and port 54325.
Subscription.addDestination("aeron:udp?endpoint=localhost:54325")UDP multicast destination with endpoint of 224.20.30.39, port 54326, and interface on localhost.
Subscription.addDestination("aeron:udp?endpoint=224.20.30.39:54326|interface=localhost")Dynamic MDC Publication using the following specification.
aeron:udp?control=localhost:54325|control-mode=dynamic
Subscription can listen to this Publication on endpoint localhost and port 54326.
Subscription.addDestination("aeron:udp?endpoint=localhost:54326|control=localhost:54325")Channels, Publications, and Subscriptions may be tagged with 64-bit integers and referenced later. A tag is specified by the parameter tags. The value may be of two forms. A single value indicates the channel identifier tag, e.g. tags=1001 refers to tag 1001 for a channel. A double value separated by a comma indicates the channel tag and the Subscription, or Publication, tag. e.g. tags=1001,105 refers to tag 1001 for channel and a tag 105 for identifying a Publication or Subscription.
Subscription using endpoint of localhost and port 4000 and set a tag of 1001 for the channel, this is the original for identity.
aeron:udp?endpoint=localhost:4000|tags=1001
The channel may be referenced by tag of 1001 without needing to specify the endpoint.
aeron:udp?tags=1001
Subscription using multi-destination control for identity.
aeron:udp?control-mode=manual|tags=3,4
The channel and Subscription may be referenced by tags of 3,4 by another Subscription so that config of the original can be referenced and reused.
aeron:udp?tags=3,4