Skip to content

Channels, Streams and Sessions

When you create a Publication & Subscription pair, you must define both the Channel and Stream ID. The channel feels much like a standard TCP/IP configuration - it includes an IP Address and Port, at minimum. However, Aeron is not TCP/IP, and you can optionally use the same channel to move different streams of data - this is the Stream ID.

When you receive data from an Aeron Channel on a specific Stream ID and there is a single source of data, then the source is obvious. But what if there are multiple senders on that Channel and Stream ID? This is where Session ID helps - you can identify each source of data in a Subscription using the header.sessionId() in the FragmentHandler method onFragment.

channel-stream-session Channel: server1:686 Client Process 1 Server Process 1 Subscription 1 Subscription 2 Client Process 2 Client Process 3 server1:686 Stream 1 server1:686 Stream 1 server1:686 Stream 2 server1:686 Stream 1 server1:686 Stream 2

From the subscriptions on the Server Process 1, the following information is available within a FragmentHandler:

Source subscription.channel() header.streamId() header.sessionId()
Client Process 1 server1:686 1 Session 213897
Client Process 2 server1:686 1 Session -421387
Client Process 3 server1:686 2 Session 2378636

The FragmentHandler cannot read the subscription channel - therefor FragmentHandler objects don't do well when shared across different channels, but can work fine for sharing across different stream Id's on the same channel. You cannot construct different FragmentHandler objects per session.

The developer should be aware that sessionId values are integers, and can appear to be random with both positive and negative values found.

Impact on Ordering

Within Aeron, ordering is guaranteed only within the same Image. When a subscription receives data, it aggregates the data of 0..m Image objects. Each Image is constructed per channel, stream and session. Note that if you have multiple ExclusivePublication objects on the same channel and stream, they will each get their own sessionId. This means that when multiple remote (or local, if ExclusivePublication) sessions are sending to the same channel and stream ID, ordering is only guaranteed at a channel/stream/session level.

There is no total ordering across multiple sessions on the same channel and stream.

Using the Session ID with client-server operations

It's common to construct a protocol on top of Aeron, with the initial phase being some kind of connect request operation (see RPC Server). One way to manage multiple client sessions within the same Subscription is to keep track of client connections via an Agrona Long2ObjectHashMap which has the sessionId as the key.

Back to top