io.aeron

Class Aeron.Context

java.lang.Object

io.aeron.CommonContext

io.aeron.Aeron.Context

All Implemented Interfaces:

java.lang.Cloneable

Enclosing class:

Aeron

public static class Aeron.Context
extends CommonContext

This class provides configuration for the Aeron class via the Aeron.connect(Aeron.Context) method and its overloads. It gives applications some control over the interactions with the Aeron Media Driver. It can also set up error handling as well as application callbacks for image information from the Media Driver.

A number of the properties are for testing and should not be set by end users.

Note: Do not reuse instances of the context across different Aeron clients.

The context will be owned by ClientConductor after a successful Aeron.connect(Context) and closed via Aeron.close().

Field Summary

Fields inherited from class io.aeron.CommonContext

AERON_DIR_PROP_DEFAULT, AERON_DIR_PROP_NAME, ALIAS_PARAM_NAME, DEFAULT_DRIVER_TIMEOUT_MS, DRIVER_TIMEOUT_MS, DRIVER_TIMEOUT_PROP_NAME, ENDPOINT_PARAM_NAME, INITIAL_TERM_ID_PARAM_NAME, INTERFACE_PARAM_NAME, IPC_CHANNEL, IPC_MEDIA, LINGER_PARAM_NAME, MDC_CONTROL_MODE_DYNAMIC, MDC_CONTROL_MODE_MANUAL, MDC_CONTROL_MODE_PARAM_NAME, MDC_CONTROL_PARAM_NAME, MTU_LENGTH_PARAM_NAME, NULL_SESSION_ID, RELIABLE_STREAM_PARAM_NAME, SESSION_ID_PARAM_NAME, SPARSE_PARAM_NAME, SPY_PREFIX, TAG_PREFIX, TAGS_PARAM_NAME, TERM_ID_PARAM_NAME, TERM_LENGTH_PARAM_NAME, TERM_OFFSET_PARAM_NAME, TTL_PARAM_NAME, UDP_MEDIA

Constructor Summary

Constructors

Constructor and Description
Context()

Method Summary

Modifier and Type	Method and Description
Aeron.Context	aeronDirectoryName(java.lang.String dirName) Set the top level Aeron directory used for communication between the client and Media Driver, and the location of the data buffers.
AvailableCounterHandler	availableCounterHandler() Get the callback handler for when a counter is available.
Aeron.Context	availableCounterHandler(AvailableCounterHandler handler) Setup a callback for when a counter is available.
AvailableImageHandler	availableImageHandler() Get the default callback handler for notifying when Images become available.
Aeron.Context	availableImageHandler(AvailableImageHandler handler) Setup a default callback for when an Image is available.
long	clientId() Get the client identity that has been allocated for communicating with the media driver.
java.util.concurrent.locks.Lock	clientLock() Get the Lock that is used to provide mutual exclusion in the Aeron client.
Aeron.Context	clientLock(java.util.concurrent.locks.Lock lock) The Lock that is used to provide mutual exclusion in the Aeron client.
Aeron.Context	clone() Perform a shallow copy of the object.
void	close() Clean up all resources that the client uses to communicate with the Media Driver.
Aeron.Context	conclude() This is called automatically by Aeron.connect(Aeron.Context) and its overloads.
org.agrona.concurrent.AgentInvoker	driverAgentInvoker() Get the AgentInvoker that is used to run the Media Driver while awaiting a synchronous response.
Aeron.Context	driverAgentInvoker(org.agrona.concurrent.AgentInvoker driverAgentInvoker) Set the AgentInvoker for the Media Driver to be used while awaiting a synchronous response.
DriverProxy	driverProxy() Get the proxy for communicating with the media driver.
Aeron.Context	driverTimeoutMs(long value) Set the amount of time, in milliseconds, that this client will wait until it determines the Media Driver is unavailable.
org.agrona.concurrent.EpochClock	epochClock() Get the EpochClock used by the client for the epoch time in milliseconds.
Aeron.Context	epochClock(org.agrona.concurrent.EpochClock clock) Set the EpochClock to be used for tracking wall clock time when interacting with the driver.
org.agrona.ErrorHandler	errorHandler() Get the error handler that will be called for errors reported back from the media driver.
Aeron.Context	errorHandler(org.agrona.ErrorHandler errorHandler) Handle Aeron exceptions in a callback method.
org.agrona.concurrent.IdleStrategy	idleStrategy() Get the IdleStrategy employed by the client conductor thread.
Aeron.Context	idleStrategy(org.agrona.concurrent.IdleStrategy idleStrategy) Provides an IdleStrategy for the thread responsible for communicating with the Aeron Media Driver.
long	interServiceTimeout() Return the timeout between service calls to the duty cycle for the client.
long	keepAliveInterval() Get the interval in nanoseconds for which the client will perform keep-alive operations.
Aeron.Context	keepAliveInterval(long value) Set the interval in nanoseconds for which the client will perform keep-alive operations.
io.aeron.LogBuffersFactory	logBuffersFactory() Get the factory for making log buffers.
org.agrona.concurrent.NanoClock	nanoClock() Get the NanoClock to be used for tracking high resolution time.
Aeron.Context	nanoClock(org.agrona.concurrent.NanoClock clock) Set the NanoClock to be used for tracking high resolution time.
long	resourceLingerDurationNs() Duration to wait while lingering a entity such as an Image before deleting underlying resources such as memory mapped files.
Aeron.Context	resourceLingerDurationNs(long resourceLingerDurationNs) Duration to wait while lingering a entity such as an Image before deleting underlying resources such as memory mapped files.
java.util.concurrent.ThreadFactory	threadFactory() The thread factory to be use to construct the conductor thread
Aeron.Context	threadFactory(java.util.concurrent.ThreadFactory threadFactory) Specify the thread factory to use when starting the conductor thread.
org.agrona.concurrent.broadcast.CopyBroadcastReceiver	toClientBuffer() The buffer used for communicating from the media driver to the Aeron client.
org.agrona.concurrent.ringbuffer.RingBuffer	toDriverBuffer() Get the RingBuffer used for sending commands to the media driver.
UnavailableCounterHandler	unavailableCounterHandler() Get the callback handler for when a counter is unavailable.
Aeron.Context	unavailableCounterHandler(UnavailableCounterHandler handler) Setup a callback for when a counter is unavailable.
UnavailableImageHandler	unavailableImageHandler() Get the callback handler for when an Image is unavailable.
Aeron.Context	unavailableImageHandler(UnavailableImageHandler handler) Setup a default callback for when an Image is unavailable.
boolean	useConductorAgentInvoker() Should an AgentInvoker be used for running the ClientConductor rather than run it on a thread with a AgentRunner.
Aeron.Context	useConductorAgentInvoker(boolean useConductorAgentInvoker) Should an AgentInvoker be used for running the ClientConductor rather than run it on a thread with a AgentRunner.

Methods inherited from class io.aeron.CommonContext

aeronDirectory, aeronDirectoryName, cncFile, concludeAeronDirectory, countersMetaDataBuffer, countersMetaDataBuffer, countersValuesBuffer, countersValuesBuffer, deleteAeronDirectory, driverTimeoutMs, formatError, generateRandomDirName, getAeronDirectoryName, isDriverActive, isDriverActive, isDriverActive, mapExistingCncFile, newDefaultCncFile, saveErrorLog, saveErrorLog

Methods inherited from class java.lang.Object

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

Constructor Detail

Context

public Context()

Method Detail

clone

public Aeron.Context clone()

Perform a shallow copy of the object.

Overrides:

clone in class CommonContext

Returns:

a shallow copy of the object.

conclude

public Aeron.Context conclude()

This is called automatically by Aeron.connect(Aeron.Context) and its overloads. There is no need to call it from a client application. It is responsible for providing default values for options that are not individually changed through field setters.

Overrides:

conclude in class CommonContext

Returns:

this for a fluent API.

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.

useConductorAgentInvoker

public Aeron.Context useConductorAgentInvoker(boolean useConductorAgentInvoker)

Should an AgentInvoker be used for running the ClientConductor rather than run it on a thread with a AgentRunner.

Parameters:

useConductorAgentInvoker - use AgentInvoker be used for running the ClientConductor?

Returns:

this for a fluent API.

useConductorAgentInvoker

public boolean useConductorAgentInvoker()

Should an AgentInvoker be used for running the ClientConductor rather than run it on a thread with a AgentRunner.

Returns:

true if the ClientConductor will be run with an AgentInvoker otherwise false.

driverAgentInvoker

public Aeron.Context driverAgentInvoker(org.agrona.concurrent.AgentInvoker driverAgentInvoker)

Set the AgentInvoker for the Media Driver to be used while awaiting a synchronous response.

Useful for when running on a low thread count scenario.

Parameters:

driverAgentInvoker - to be invoked while awaiting a response in the client.

Returns:

this for a fluent API.

driverAgentInvoker

public org.agrona.concurrent.AgentInvoker driverAgentInvoker()

Get the AgentInvoker that is used to run the Media Driver while awaiting a synchronous response.

Returns:

the AgentInvoker that is used for running the Media Driver.

clientLock

public Aeron.Context clientLock(java.util.concurrent.locks.Lock lock)

The Lock that is used to provide mutual exclusion in the Aeron client.

If the useConductorAgentInvoker() is set and only one thread accesses the client then the lock can be set to NoOpLock to elide the lock overhead.

Parameters:

lock - that is used to provide mutual exclusion in the Aeron client.

Returns:

this for a fluent API.

clientLock

public java.util.concurrent.locks.Lock clientLock()

Get the Lock that is used to provide mutual exclusion in the Aeron client.

Returns:

the Lock that is used to provide mutual exclusion in the Aeron client.

epochClock

public Aeron.Context epochClock(org.agrona.concurrent.EpochClock clock)

Set the EpochClock to be used for tracking wall clock time when interacting with the driver.

Parameters:

clock - EpochClock to be used for tracking wall clock time when interacting with the driver.

Returns:

this for a fluent API.

epochClock

public org.agrona.concurrent.EpochClock epochClock()

Get the EpochClock used by the client for the epoch time in milliseconds.

Returns:

the EpochClock used by the client for the epoch time in milliseconds.

nanoClock

public Aeron.Context nanoClock(org.agrona.concurrent.NanoClock clock)

Set the NanoClock to be used for tracking high resolution time.

Parameters:

clock - NanoClock to be used for tracking high resolution time.

Returns:

this for a fluent API.

nanoClock

public org.agrona.concurrent.NanoClock nanoClock()

Get the NanoClock to be used for tracking high resolution time.

Returns:

the NanoClock to be used for tracking high resolution time.

idleStrategy

public Aeron.Context idleStrategy(org.agrona.concurrent.IdleStrategy idleStrategy)

Provides an IdleStrategy for the thread responsible for communicating with the Aeron Media Driver.

Parameters:

idleStrategy - Thread idle strategy for communication with the Media Driver.

Returns:

this for a fluent API.

idleStrategy

public org.agrona.concurrent.IdleStrategy idleStrategy()

Get the IdleStrategy employed by the client conductor thread.

Returns:

the IdleStrategy employed by the client conductor thread.

toClientBuffer

public org.agrona.concurrent.broadcast.CopyBroadcastReceiver toClientBuffer()

The buffer used for communicating from the media driver to the Aeron client.

Returns:

the buffer used for communicating from the media driver to the Aeron client.

toDriverBuffer

public org.agrona.concurrent.ringbuffer.RingBuffer toDriverBuffer()

Get the RingBuffer used for sending commands to the media driver.

Returns:

the RingBuffer used for sending commands to the media driver.

driverProxy

public DriverProxy driverProxy()

Get the proxy for communicating with the media driver.

Returns:

the proxy for communicating with the media driver.

logBuffersFactory

public io.aeron.LogBuffersFactory logBuffersFactory()

Get the factory for making log buffers.

Returns:

the factory for making log buffers.

errorHandler

public Aeron.Context errorHandler(org.agrona.ErrorHandler errorHandler)

Handle Aeron exceptions in a callback method. The default behavior is defined by Aeron.Configuration.DEFAULT_ERROR_HANDLER. This is the error handler which will be used if an error occurs during the callback for poll operations such as Subscription.poll(FragmentHandler, int).

The error handler can be reset after Aeron.connect() and the latest version will always be used so that the boot strapping process can be performed such as replacing the default one with a CountedErrorHandler.

Parameters:

errorHandler - Method to handle objects of type Throwable.

Returns:

this for a fluent API.

See Also:

DriverTimeoutException, RegistrationException

errorHandler

public org.agrona.ErrorHandler errorHandler()

Get the error handler that will be called for errors reported back from the media driver.

Returns:

the error handler that will be called for errors reported back from the media driver.

availableImageHandler

public Aeron.Context availableImageHandler(AvailableImageHandler handler)

Setup a default callback for when an Image is available.

Parameters:

handler - Callback method for handling available image notifications.

Returns:

this for a fluent API.

availableImageHandler

public AvailableImageHandler availableImageHandler()

Get the default callback handler for notifying when Images become available.

Returns:

the callback handler for notifying when Images become available.

unavailableImageHandler

public Aeron.Context unavailableImageHandler(UnavailableImageHandler handler)

Setup a default callback for when an Image is unavailable.

Parameters:

handler - Callback method for handling unavailable image notifications.

Returns:

this for a fluent API.

unavailableImageHandler

public UnavailableImageHandler unavailableImageHandler()

Get the callback handler for when an Image is unavailable.

Returns:

the callback handler for when an Image is unavailable.

availableCounterHandler

public Aeron.Context availableCounterHandler(AvailableCounterHandler handler)

Setup a callback for when a counter is available.

Parameters:

handler - to be called for handling available counter notifications.

Returns:

this for a fluent API.

availableCounterHandler

public AvailableCounterHandler availableCounterHandler()

Get the callback handler for when a counter is available.

Returns:

the callback handler for when a counter is available.

unavailableCounterHandler

public Aeron.Context unavailableCounterHandler(UnavailableCounterHandler handler)

Setup a callback for when a counter is unavailable.

Parameters:

handler - to be called for handling unavailable counter notifications.

Returns:

this for a fluent API.

unavailableCounterHandler

public UnavailableCounterHandler unavailableCounterHandler()

Get the callback handler for when a counter is unavailable.

Returns:

the callback handler for when a counter is unavailable.

keepAliveInterval

public Aeron.Context keepAliveInterval(long value)

Set the interval in nanoseconds for which the client will perform keep-alive operations.

Parameters:

value - the interval in nanoseconds for which the client will perform keep-alive operations.

Returns:

this for a fluent API.

keepAliveInterval

public long keepAliveInterval()

Get the interval in nanoseconds for which the client will perform keep-alive operations.

Returns:

the interval in nanoseconds for which the client will perform keep-alive operations.

driverTimeoutMs

public Aeron.Context driverTimeoutMs(long value)

Set the amount of time, in milliseconds, that this client will wait until it determines the Media Driver is unavailable. When this happens a DriverTimeoutException will be generated for the error handler.

Overrides:

driverTimeoutMs in class CommonContext

Parameters:

value - Number of milliseconds.

Returns:

this for a fluent API.

See Also:

errorHandler(ErrorHandler)

interServiceTimeout

public long interServiceTimeout()

Return the timeout between service calls to the duty cycle for the client.

When exceeded, errorHandler will be called and the active Publications and Images closed.

This value is controlled by the driver and included in the CnC file. It can be configured by adjusting the aeron.client.liveness.timeout property on the media driver.

Returns:

the timeout in nanoseconds between service calls.

resourceLingerDurationNs

public Aeron.Context resourceLingerDurationNs(long resourceLingerDurationNs)

Duration to wait while lingering a entity such as an Image before deleting underlying resources such as memory mapped files.

Parameters:

resourceLingerDurationNs - to wait before deleting a expired resource.

Returns:

this for a fluent API.

See Also:

Aeron.Configuration.RESOURCE_LINGER_DURATION_PROP_NAME

resourceLingerDurationNs

public long resourceLingerDurationNs()

Duration to wait while lingering a entity such as an Image before deleting underlying resources such as memory mapped files.

Returns:

duration in nanoseconds to wait before deleting a expired resource.

See Also:

Aeron.Configuration.RESOURCE_LINGER_DURATION_PROP_NAME

aeronDirectoryName

public Aeron.Context aeronDirectoryName(java.lang.String dirName)

Description copied from class: CommonContext

Set the top level Aeron directory used for communication between the client and Media Driver, and the location of the data buffers.

Overrides:

aeronDirectoryName in class CommonContext

Parameters:

dirName - New top level Aeron directory.

Returns:

this for a fluent API.

See Also:

CommonContext.aeronDirectoryName(String)

threadFactory

public Aeron.Context threadFactory(java.util.concurrent.ThreadFactory threadFactory)

Specify the thread factory to use when starting the conductor thread.

Parameters:

threadFactory - thread factory to construct the thread.

Returns:

this for a fluent API.

threadFactory

public java.util.concurrent.ThreadFactory threadFactory()

The thread factory to be use to construct the conductor thread

Returns:

the specified thread factory or Thread.Thread(Runnable) if none is provided

close

public void close()

Clean up all resources that the client uses to communicate with the Media Driver.

Overrides:

close in class CommonContext