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
As a part of the sample we will construct 4 items:
- the Aeron API;
- the Media Driver;
- a Subscription;
- a Publication.
Full source code¶
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
sending:my message received:my message
Dissecting the code¶
Constructing support objects¶
1 2 3 4
- 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
SleepingIdleStrategywhich 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¶
1 2 3 4
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¶
1 2 3 4 5 6 7 8 9 10
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¶
1 2 3 4 5 6 7
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
FragmentHandlerto accept the message.
FragmentAssemblershould 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