Basic Sample

The following is a complete method to send a message across IPC. To keep it as simple as possible, the publisher and subscriber are on the same thread - but this would not make sense in a real world application. Despite this, it is useful as it shows the full setup of a minimal Aeron application. The code can be found in the aeron-ipc project, in the SimplestCase.java file.

As a part of the sample we will construct 4 items:

• the Aeron API;
• the Media Driver;
• a Subscription;
• a Publication.

Full source code

public static void main(String[] args)
{
    final String channel = "aeron:ipc";
    final String message = "my message";
    final IdleStrategy idle = new SleepingIdleStrategy();
    final UnsafeBuffer unsafeBuffer = new UnsafeBuffer(ByteBuffer.allocate(256));
    try (MediaDriver driver = MediaDriver.launch();
        Aeron aeron = Aeron.connect();
        Subscription sub = aeron.addSubscription(channel, 10);
        Publication pub = aeron.addPublication(channel, 10))
    {
        while (!pub.isConnected())
        {
            idle.idle();
        }
        unsafeBuffer.putStringAscii(0, message);
        System.out.println("sending:" + message);
        while (pub.offer(unsafeBuffer) < 0)
        {
            idle.idle();
        }
        FragmentHandler handler = (buffer, offset, length, header) ->
            System.out.println("received:" + buffer.getStringAscii(offset));
        while (sub.poll(handler, 1) <= 0)
        {
            idle.idle();
        }
    }
}

Execution Output

sending:my message
received:my message

Dissecting the code

Constructing support objects

final String channel = "aeron:ipc";
final String message = "my message";
final IdleStrategy idle = new SleepingIdleStrategy();
final UnsafeBuffer unsafeBuffer = new UnsafeBuffer(ByteBuffer.allocate(256));

• Line 1 specifies the channel over which the Aeron Publisher and Subscriber will communicate. This is defined using the Aeron URL scheme, and the channel in this example is given as an IPC channel. See also the Aeron Wiki on channel configuration
• Line 2 specifies the message to offer over the publication.
• Line 3 specifies the idle strategy to use, in this case the SleepingIdleStrategy which parks the thread for 1 microsecond, the default value.
• Line 4 provides an off heap $and thus unsafe$ buffer to hold the message to be sent. 256 bytes are allocated for simplicity, however, this could be reduced.

See also: Agents & Idle Strategies

Constructing Aeron objects

try (MediaDriver driver = MediaDriver.launch();
    Aeron aeron = Aeron.connect();
    Subscription sub = aeron.addSubscription(channel, 10);
    Publication pub = aeron.addPublication(channel, 10))

These next four lines of code create the key Aeron objects used to send and receive the data.

• Line 1 creates the Media Driver. The Media Driver is responsible for all IPC and network activity, and is discussed in detail later
• Line 2 creates the Aeron object. This is the primary API used in an application to interact with Aeron
• Line 3 creates the Subscription which will be polled in order to receive message
• Line 4 creates the Publication from which the message will be sent

See also: Media Driver

Sending the message

while (!pub.isConnected())
{
    idle.idle();
}
unsafeBuffer.putStringAscii(0, message);
System.out.println("sending:" + message);
while (pub.offer(unsafeBuffer) < 0)
{
    idle.idle();
}

These lines are responsible for publishing the message. First the application awaits the publication reaching a connected state. Then, the message is written to the unsafe buffer and finally, the buffer is offered to the publication. Key lines described below:

• Line 1 returns true only once the publication is connected. This is polled in a while loop, with a 1 microsecond pause between iterations until it is connected.
• Line 7 offers the buffer to the publication. When the value returned is less than zero, something is preventing the publication from accepting the buffer. Again the idle strategy polls until it is accepted

Receiving the message

FragmentHandler handler = (buffer, offset, length, header) ->
    System.out.println("received:" + buffer.getStringAscii(offset));

while (sub.poll(handler, 1) <= 0)
{
    idle.idle();
}

The final part of the code is responsible for accepting the message from a subscription. First, a FragmentHandler to accept the message, and then the subscription is polled until the message is delivered by Aeron. Key lines below:

• Lines 1-2 construct the FragmentHandler. In this case we know it is a simple, small message so we can use the most basic FragmentHandler to accept the message. FragmentAssembler should be used to reassemble larger messages.
• Line 4 polls the subscription for data. As with the publication, a value at or less than zero has a specific meaning. The code then polls the subscription with a microsecond idle between iterations