Package io.aeron

Class Aeron

java.lang.Object
io.aeron.Aeron
All Implemented Interfaces:
AutoCloseable
public class Aeron extends Object implements 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.

  • Field Details

    • NULL_VALUE

      public static final int NULL_VALUE
      Used to represent a null value for when some value is not yet set.
      See Also:

  • Method Details

    • 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(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 AgentInvoker conductorAgentInvoker()
      Get the AgentInvoker for the client conductor.
      Returns:
      the AgentInvoker for the client conductor.

    • isCommandActive

      public boolean isCommandActive(long correlationId)
      Is the command still active for a given correlation id.
      Parameters:
      correlationId - to check if it is still active.
      Returns:
      true in the command is still in active processing or false if completed successfully or errored.
      See Also:

    • hasActiveCommands

      public boolean hasActiveCommands()
      Does the client have any active asynchronous commands?

      When close operations are performed on Publications, Subscriptions, and Counters the commands are sent asynchronously to the driver. The client tracks active commands in case errors need to be reported. If you wish to wait for acknowledgement of close operations then wait for this method to return false.

      Returns:
      true if any commands are currently active otherwise false.

    • 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. To check for the command being acknowledged by the driver

      Specified by:
      close in interface AutoCloseable

    • addPublication

      public ConcurrentPublication addPublication(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(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.

    • asyncAddPublication

      public long asyncAddPublication(String channel, int streamId)
      Asynchronously add a Publication for publishing messages to subscribers. The added publication returned is threadsafe.
      Parameters:
      channel - for sending the messages known to the media layer.
      streamId - within the channel scope.
      Returns:
      the registration id of the publication which can be used to get the added publication.
      See Also:

    • asyncAddExclusivePublication

      public long asyncAddExclusivePublication(String channel, int streamId)
      Asynchronously add a Publication 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:
      the registration id of the publication which can be used to get the added exclusive publication.
      See Also:

    • asyncRemovePublication

      public void asyncRemovePublication(long registrationId)
      Asynchronously remove a Publication.
      Parameters:
      registrationId - to be of the publication removed.
      See Also:

    • getPublication

      public ConcurrentPublication getPublication(long registrationId)
      Get a Publication for publishing messages to subscribers. The publication returned is threadsafe.
      Parameters:
      registrationId - returned from asyncAddPublication(String, int).
      Returns:
      a new ConcurrentPublication when available otherwise null.
      See Also:

    • getExclusivePublication

      public ExclusivePublication getExclusivePublication(long registrationId)
      Get a single threaded Publication for publishing messages to subscribers.
      Parameters:
      registrationId - returned from asyncAddExclusivePublication(String, int).
      Returns:
      a new ExclusivePublication when available otherwise null.
      See Also:

    • addSubscription

      public Subscription addSubscription(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(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.

    • asyncAddSubscription

      public long asyncAddSubscription(String channel, int streamId, AvailableImageHandler availableImageHandler, UnavailableImageHandler unavailableImageHandler)
      Add a new Subscription for subscribing to messages from publishers.
      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 registration id of the subscription which can be used to get the added subscription.
      See Also:

    • asyncAddSubscription

      public long asyncAddSubscription(String channel, int streamId)
      Add a new Subscription for subscribing to messages from publishers.
      Parameters:
      channel - for receiving the messages known to the media layer.
      streamId - within the channel scope.
      Returns:
      the registration id of the subscription which can be used to get the added subscription.
      See Also:

    • asyncRemoveSubscription

      public void asyncRemoveSubscription(long registrationId)
      Asynchronously remove a Subscription.
      Parameters:
      registrationId - to be of the subscription removed.
      See Also:

    • getSubscription

      public Subscription getSubscription(long registrationId)
      Get a Subscription for subscribing to messages from publishers.
      Parameters:
      registrationId - returned from asyncAddSubscription(String, int, AvailableImageHandler, UnavailableImageHandler) or asyncAddSubscription(String, int)
      Returns:
      a new Subscription when available otherwise null.
      See Also:

    • 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 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, DirectBuffer keyBuffer, int keyOffset, int keyLength, 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:

    • addCounter

      public Counter addCounter(int typeId, 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:

    • addStaticCounter

      public Counter addStaticCounter(int typeId, DirectBuffer keyBuffer, int keyOffset, int keyLength, DirectBuffer labelBuffer, int labelOffset, int labelLength, long registrationId)
      Allocates or returns an existing static counter instance using specified typeId and registrationId pair. Such counter cannot be deleted and its lifecycle is decoupled from this Aeron instance, i.e. won't be closed when this instance is closed or times out.

      Note: calling Counter.close() will only close the counter instance itself but will not free the counter in the CnC file.

      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.
      registrationId - that uniquely identifies the static counter for a given typeId.
      Returns:
      the static counter instance.
      Since:
      1.45.0
      See Also:

    • addStaticCounter

      public Counter addStaticCounter(int typeId, String label, long registrationId)
      Allocates or returns an existing static counter instance using specified typeId and registrationId pair. Such counter cannot be deleted and its lifecycle is decoupled from this Aeron instance, i.e. won't be closed when this instance is closed or times out.

      Note: calling Counter.close() will only close the counter instance itself but will not free the counter in the CnC file.

      Parameters:
      typeId - for the counter.
      label - for the counter. It should be US-ASCII.
      registrationId - that uniquely identifies the static counter for a given typeId.
      Returns:
      the static counter.
      Since:
      1.45.0
      See Also:

    • addAvailableCounterHandler

      public long addAvailableCounterHandler(AvailableCounterHandler handler)
      Add a handler to the list be called when Counters become available.
      Parameters:
      handler - to be called when Counters become available.
      Returns:
      registration id for the handler which can be used to remove it.

    • removeAvailableCounterHandler

      public boolean removeAvailableCounterHandler(long registrationId)
      Remove a previously added handler to the list be called when Counters become available.
      Parameters:
      registrationId - to be removed which was returned from add method.
      Returns:
      true if found and removed otherwise false.

    • removeAvailableCounterHandler

      @Deprecated public boolean removeAvailableCounterHandler(AvailableCounterHandler handler)
      Deprecated.
      please use removeAvailableCounterHandler(long).
      Remove a previously added handler to the list be called when Counters become available.
      Parameters:
      handler - to be removed.
      Returns:
      true if found and removed otherwise false.

    • addUnavailableCounterHandler

      public long addUnavailableCounterHandler(UnavailableCounterHandler handler)
      Add a handler to the list be called when Counters become unavailable.
      Parameters:
      handler - to be called when Counters become unavailable.
      Returns:
      registration id for the handler which can be used to remove it.

    • removeUnavailableCounterHandler

      public boolean removeUnavailableCounterHandler(long registrationId)
      Remove a previously added handler to the list be called when Counters become unavailable.
      Parameters:
      registrationId - to be removed which was returned from add method.
      Returns:
      true if found and removed otherwise false.

    • removeUnavailableCounterHandler

      @Deprecated public boolean removeUnavailableCounterHandler(UnavailableCounterHandler handler)
      Deprecated.
      please use removeUnavailableCounterHandler(long).
      Remove a previously added handler to the list be called when Counters become unavailable.
      Parameters:
      handler - to be removed.
      Returns:
      true if found and removed otherwise false.

    • addCloseHandler

      public long addCloseHandler(Runnable handler)
      Add a handler to the list be called when the Aeron client is closed.
      Parameters:
      handler - to be called when the Aeron client is closed.
      Returns:
      registration id for the handler which can be used to remove it.

    • removeCloseHandler

      public boolean removeCloseHandler(long registrationId)
      Remove a previously added handler to the list be called when the Aeron client is closed.
      Parameters:
      registrationId - of the handler from when it was added.
      Returns:
      true if found and removed otherwise false.

    • removeCloseHandler

      @Deprecated public boolean removeCloseHandler(Runnable handler)
      Deprecated.
      please use removeCloseHandler(long).
      Remove a previously added handler to the list be called when the Aeron client is closed.
      Parameters:
      handler - to be removed.
      Returns:
      true if found and removed otherwise false.

    • toString

      public String toString()
      Overrides:
      toString in class Object