Skip to content

IPC Publications - Connecting to a Subscription

IPC Publications are simpler than Network Publications. They're essentially a subset of Network Publication functionality, but it's worth pointing out the similarities and differences to avoid any confusion. I'll rattle though this quickly, so see the Network Publications pages if you want more details.

1) Creating an IPC Publication

Here's how an IPC Publication and its associated log buffer file is created. We'll create the Publication before the Subscription.

Aeron Client cnc.dat (shared memory) counters to-driver buffer to-clients buffer Receiver Driver Conductor Sender Media Driver Client Conductor Application Logic Concurrent / Exclusive Publication 23 create read PublicationBuffersReady write IPC Publication 23 create pub-pos, pub-lmt publications/23.logbuffer Metadata Term 0 Term 1 Term 2 isConnected=false create read nextCorrelationId() PublicationMessage write addPublication()

Use the tabs above to step through the animation.



The application calls into the Aeron Client API to create a Publication, using a Channel URI that starts with aeron:ipc. As per Network Publications, it writes a message into cnc.dat's to-driver buffer.

The Driver Conductor reads the message.

As per Network Publications, it creates a Publication log buffer. isConnected is false in the metadata. This is used in IPC Publications to track whether a Subscription has been created for the Publication, but it's not done by sending messages over the network.

The Driver Conductor then creates counters in the cnc.dat file that are specific to the publishing part of this Publication (pub-pos and pub-lmt). There are no Sending related counters.

The Driver Conductor creates an IpcPublication object to manage everything to do with this Publication within the Media Driver. It is given a reference to the Publication's counters and log buffer.

The Driver Conductor writes a PublicationBuffersReady message to the to-clients buffer using a BroadcastTransmitter. This contains, among other things, correlationId 23, a registrationId (also 23), and the log buffer filename.

At this stage, the Driver Conductor checks if any Subscriptions have already been created for this Publication. That's not the case in this example. If it was, the Subscriptions would be linked to the Publication. This process is similar to what we're about to see in the next section, when we create the Subscription and it connects to this Publication.

When the Client Conductor next polls the to-clients buffer, it reads the PublicationBuffersReady response containing correlationId 23, which it was waiting for.

The Client Conductor creates a ConcurrentPublication or ExclusivePublication API object (depending on the method invoked in step 1) with registrationId 23. The Publication API object opens the log buffer file and maps it into memory. The Publication API object is returned to the application, which can use it to publish messages (once connected to the Subscription).

2) Creating a Subscription

Here's how a Subscription to an IPC Publication is created. It's on the same machine as the IPC Publication, so the Publication log buffer created in the previous section is on the diagram.

Aeron Client cnc.dat (shared memory) counters to-driver buffer to-clients buffer Receiver Driver Conductor Sender Media Driver Client Conductor Application Logic publications/23.logbuffer Metadata Term 0 Term 1 Term 2 isConnected=false set create read Image 51 ImageReady (47, 23) write isConnected=true sub-pos (47) create Subscription 47 create read SubscriptionReady write IPC Subscription Link 47 read SubscriptionMessage write nextCorrelationId() addSubscription() pub-pos, pub-lmt

Use the tabs above to step through the animation.



Creating a Subscription starts as per creating a Publication. The application calls into the Aeron Client API using Aeron.addSubscription(channel, streamId), the Client Conductor puts this into a message in the to-driver buffer, then waits for a response. Let's say the correlationId is 47.

The Driver Conductor reads the SubscriptionMessage and creates an IpcSubscriptionLink. Whenever a new Publication is created, this is used to find matching Subscribers. The correlationId 47 is used as the registrationId for the IpcSubscriptionLink.

The Driver Conductor sends a SubscriptionReady response to the ClientConductor to say the Subscription is ready. It contains registrationId 47.

The Client Conductor reads the SubscriptionReady response, creates a Subscription API object and returns it to the application. The application can poll the Subscription for messages, but it won't receive anything. The Subscription still needs linking to one or more Publication log buffer files.

The Driver Conductor looks for any IpcPublications that match the Subscription and finds the IpcPublication created in the previous section. It creates a sub-pos counter and sets isConnected to true in the Publication log buffer metadata.

The Driver Conductor tells the Client Conductor that an Image (Publication 23) is ready for Subscription 47. The Subscription doesn't care that it is reading directly from the Publication log buffer - it is identical in content to an Image log buffer. The message also contains the Publication log buffer filename and the id of the sub-pos counter.

The Client Conductor polls the to-clients buffer for unsolicited messages and reads the ImageReady message. It creates an Image object to manage the Publication log buffer and sub-pos counter. Note that this Image object is specific to Subscription 47. If there were more than one Subscription, there would be an Image object for each of them, even though there's only one Publication log buffer.

The Image is then added to the Subscription. At this point, if the application polled the Subscription, it would be returned any fragments in the Publication log buffer.

Now that isConnected is true, next time the Driver Conductor performs its duty cycle and checks on the IpcPublication, the IpcPublication sets pub-lmt to min(sub-pos) + termWindowLength (0 + half a term). The IpcPublication can now be used to publish messages, as pub-lmt is higher than pub-pos and isConnected is true. The IpcPublication has direct access to the sub-pos counters, because everything is on the same machine.