io.aeron

Class Aeron

java.lang.Object

io.aeron.Aeron

All Implemented Interfaces:

java.lang.AutoCloseable

public class Aeron
extends java.lang.Object
implements java.lang.AutoCloseable

Aeron entry point for communicating to the Media Driver for creating Publications and Subscriptions. Use an Aeron.Context to configure the Aeron object.

A client application requires only one Aeron object per Media Driver.

Note: If Aeron.Context.errorHandler(ErrorHandler) is not set and a DriverTimeoutException occurs then the process will face the wrath of System.exit(int). See Aeron.Configuration.DEFAULT_ERROR_HANDLER.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Aeron.Configuration Configuration options for the Aeron client.
static class	Aeron.Context This class provides configuration for the Aeron class via the connect(Aeron.Context) method and its overloads.

Field Summary

Fields

Modifier and Type	Field and Description
static int	NULL_VALUE Used to represent a null value for when some value is not yet set.

Method Summary

Modifier and Type	Method and Description
Counter	addCounter(int typeId, org.agrona.DirectBuffer keyBuffer, int keyOffset, int keyLength, org.agrona.DirectBuffer labelBuffer, int labelOffset, int labelLength) Allocate a counter on the media driver and return a Counter for it.
Counter	addCounter(int typeId, java.lang.String label) Allocate a counter on the media driver and return a Counter for it.
ExclusivePublication	addExclusivePublication(java.lang.String channel, int streamId) Add an ExclusivePublication for publishing messages to subscribers from a single thread.
ConcurrentPublication	addPublication(java.lang.String channel, int streamId) Add a Publication for publishing messages to subscribers.
Subscription	addSubscription(java.lang.String channel, int streamId) Add a new Subscription for subscribing to messages from publishers.
Subscription	addSubscription(java.lang.String channel, int streamId, AvailableImageHandler availableImageHandler, UnavailableImageHandler unavailableImageHandler) Add a new Subscription for subscribing to messages from publishers.
long	clientId() Get the client identity that has been allocated for communicating with the media driver.
void	close() Clean up and release all Aeron client resources and shutdown conductor thread if not using Aeron.Context.useConductorAgentInvoker(boolean).
org.agrona.concurrent.AgentInvoker	conductorAgentInvoker() Get the AgentInvoker for the client conductor.
static Aeron	connect() Create an Aeron instance and connect to the media driver with a default Aeron.Context.
static Aeron	connect(Aeron.Context ctx) Create an Aeron instance and connect to the media driver.
Aeron.Context	context() Get the Aeron.Context that is used by this client.
org.agrona.concurrent.status.CountersReader	countersReader() Get the CountersReader for the Aeron media driver counters.
boolean	isClosed() Has the client been closed? If not then the CnC file may not be unmapped.
long	nextCorrelationId() Generate the next correlation id that is unique for the connected Media Driver.
void	printCounters(java.io.PrintStream out) Print out the values from countersReader() which can be useful for debugging.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NULL_VALUE

public static final int NULL_VALUE

Used to represent a null value for when some value is not yet set.

See Also:

Constant Field Values

Method Detail

connect

public static Aeron connect()

Create an Aeron instance and connect to the media driver with a default Aeron.Context.

Threads required for interacting with the media driver are created and managed within the Aeron instance.

Returns:

the new Aeron instance connected to the Media Driver.

connect

public static Aeron connect(Aeron.Context ctx)

Create an Aeron instance and connect to the media driver.

Threads required for interacting with the media driver are created and managed within the Aeron instance.

If an exception occurs while trying to establish a connection then the Aeron.Context.close() method will be called on the passed context.

Parameters:

ctx - for configuration of the client.

Returns:

the new Aeron instance connected to the Media Driver.

printCounters

public void printCounters(java.io.PrintStream out)

Print out the values from countersReader() which can be useful for debugging.

Parameters:

out - to where the counters get printed.

isClosed

public boolean isClosed()

Has the client been closed? If not then the CnC file may not be unmapped.

Returns:

true if the client has been explicitly closed otherwise false.

context

public Aeron.Context context()

Get the Aeron.Context that is used by this client.

Returns:

the Aeron.Context that is use by this client.

clientId

public long clientId()

Get the client identity that has been allocated for communicating with the media driver.

Returns:

the client identity that has been allocated for communicating with the media driver.

conductorAgentInvoker

public org.agrona.concurrent.AgentInvoker conductorAgentInvoker()

Get the AgentInvoker for the client conductor.

Returns:

the AgentInvoker for the client conductor.

close

public void close()

Clean up and release all Aeron client resources and shutdown conductor thread if not using Aeron.Context.useConductorAgentInvoker(boolean).

This will close all currently open Publications, Subscriptions, and Counters created from this client.

Specified by:

close in interface java.lang.AutoCloseable

addPublication

public ConcurrentPublication addPublication(java.lang.String channel,
                                            int streamId)

Add a Publication for publishing messages to subscribers. The publication returned is threadsafe.

Parameters:

channel - for sending the messages known to the media layer.

streamId - within the channel scope.

Returns:

a new ConcurrentPublication.

addExclusivePublication

public ExclusivePublication addExclusivePublication(java.lang.String channel,
                                                    int streamId)

Add an ExclusivePublication for publishing messages to subscribers from a single thread.

Parameters:

channel - for sending the messages known to the media layer.

streamId - within the channel scope.

Returns:

a new ExclusivePublication.

addSubscription

public Subscription addSubscription(java.lang.String channel,
                                    int streamId)

Add a new Subscription for subscribing to messages from publishers.

The method will set up the Subscription to use the Aeron.Context.availableImageHandler(AvailableImageHandler) and Aeron.Context.unavailableImageHandler(UnavailableImageHandler) from the Aeron.Context.

Parameters:

channel - for receiving the messages known to the media layer.

streamId - within the channel scope.

Returns:

the Subscription for the channel and streamId pair.

addSubscription

public Subscription addSubscription(java.lang.String channel,
                                    int streamId,
                                    AvailableImageHandler availableImageHandler,
                                    UnavailableImageHandler unavailableImageHandler)

Add a new Subscription for subscribing to messages from publishers.

This method will override the default handlers from the Aeron.Context, i.e. Aeron.Context.availableImageHandler(AvailableImageHandler) and Aeron.Context.unavailableImageHandler(UnavailableImageHandler). Null values are valid and will result in no action being taken.

Parameters:

channel - for receiving the messages known to the media layer.

streamId - within the channel scope.

availableImageHandler - called when Images become available for consumption. Null is valid if no action is to be taken.

unavailableImageHandler - called when Images go unavailable for consumption. Null is valid if no action is to be taken.

Returns:

the Subscription for the channel and streamId pair.

nextCorrelationId

public long nextCorrelationId()

Generate the next correlation id that is unique for the connected Media Driver.

This is useful generating correlation identifiers for pairing requests with responses in a clients own application protocol.

This method is thread safe and will work across processes that all use the same media driver.

Returns:

next correlation id that is unique for the Media Driver.

countersReader

public org.agrona.concurrent.status.CountersReader countersReader()

Get the CountersReader for the Aeron media driver counters.

Returns:

new CountersReader for the Aeron media driver in use.

addCounter

public Counter addCounter(int typeId,
                          org.agrona.DirectBuffer keyBuffer,
                          int keyOffset,
                          int keyLength,
                          org.agrona.DirectBuffer labelBuffer,
                          int labelOffset,
                          int labelLength)

Allocate a counter on the media driver and return a Counter for it.

The counter should be freed by calling Counter.close().

Parameters:

typeId - for the counter.

keyBuffer - containing the optional key for the counter.

keyOffset - within the keyBuffer at which the key begins.

keyLength - of the key in the keyBuffer.

labelBuffer - containing the mandatory label for the counter. The label should not be length prefixed.

labelOffset - within the labelBuffer at which the label begins.

labelLength - of the label in the labelBuffer.

Returns:

the newly allocated counter.

See Also:

CountersManager.allocate(int, DirectBuffer, int, int, DirectBuffer, int, int)

addCounter

public Counter addCounter(int typeId,
                          java.lang.String label)

Allocate a counter on the media driver and return a Counter for it.

The counter should be freed by calling Counter.close().

Parameters:

typeId - for the counter.

label - for the counter. It should be US-ASCII.

Returns:

the newly allocated counter.

See Also:

CountersManager.allocate(String, int)