io.aeron

Class ConcurrentPublication

java.lang.Object

io.aeron.Publication

io.aeron.ConcurrentPublication

All Implemented Interfaces:

java.lang.AutoCloseable

public class ConcurrentPublication
extends Publication

Aeron publisher API for sending messages to subscribers of a given channel and streamId pair. Publications are created via the Aeron.addPublication(String, int) method, and messages are sent via one of the Publication.offer(DirectBuffer) methods, or a tryClaim(int, BufferClaim) and BufferClaim.commit() method combination.

The APIs used for try claim and offer are non-blocking and thread safe.

Note: Instances are threadsafe and can be shared between publishing threads.

See Also:

Aeron.addPublication(String, int), BufferClaim

Field Summary

Fields inherited from class io.aeron.Publication

ADMIN_ACTION, BACK_PRESSURED, channel, channelStatusId, CLOSED, conductor, headerWriter, initialTermId, isClosed, logBuffers, logMetaDataBuffer, MAX_POSITION_EXCEEDED, maxMessageLength, maxPayloadLength, maxPossiblePosition, NOT_CONNECTED, originalRegistrationId, positionBitsToShift, positionLimit, registrationId, sessionId, streamId, termBufferLength

Method Summary

Modifier and Type	Method and Description
long	availableWindow() Available window for offering into a publication before the Publication.positionLimit() is reached.
long	offer(org.agrona.DirectBuffer bufferOne, int offsetOne, int lengthOne, org.agrona.DirectBuffer bufferTwo, int offsetTwo, int lengthTwo, ReservedValueSupplier reservedValueSupplier) Non-blocking publish of a message composed of two parts, e.g.
long	offer(org.agrona.DirectBuffer buffer, int offset, int length, ReservedValueSupplier reservedValueSupplier) Non-blocking publish of a partial buffer containing a message.
long	offer(DirectBufferVector[] vectors, ReservedValueSupplier reservedValueSupplier) Non-blocking publish by gathering buffer vectors into a message.
long	tryClaim(int length, BufferClaim bufferClaim) Try to claim a range in the publication log into which a message can be written with zero copy semantics.

Methods inherited from class io.aeron.Publication

addDestination, channel, channelStatus, channelStatusId, close, initialTermId, isClosed, isConnected, isOriginal, maxMessageLength, maxPayloadLength, maxPossiblePosition, offer, offer, offer, offer, originalRegistrationId, position, positionBitsToShift, positionLimit, positionLimitId, registrationId, removeDestination, sessionId, streamId, termBufferLength, toString

Methods inherited from class java.lang.Object

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

Method Detail

availableWindow

public long availableWindow()

Description copied from class: Publication

Available window for offering into a publication before the Publication.positionLimit() is reached.

Specified by:

availableWindow in class Publication

Returns:

window for offering into a publication before the Publication.positionLimit() is reached. If the publication is closed then Publication.CLOSED will be returned.

offer

public long offer(org.agrona.DirectBuffer buffer,
                  int offset,
                  int length,
                  ReservedValueSupplier reservedValueSupplier)

Non-blocking publish of a partial buffer containing a message.

Specified by:

offer in class Publication

Parameters:

buffer - containing message.

offset - offset in the buffer at which the encoded message begins.

length - in bytes of the encoded message.

reservedValueSupplier - ReservedValueSupplier for the frame.

Returns:

The new stream position, otherwise a negative error value of Publication.NOT_CONNECTED, Publication.BACK_PRESSURED, Publication.ADMIN_ACTION, Publication.CLOSED, or Publication.MAX_POSITION_EXCEEDED.

offer

public long offer(org.agrona.DirectBuffer bufferOne,
                  int offsetOne,
                  int lengthOne,
                  org.agrona.DirectBuffer bufferTwo,
                  int offsetTwo,
                  int lengthTwo,
                  ReservedValueSupplier reservedValueSupplier)

Non-blocking publish of a message composed of two parts, e.g. a header and encapsulated payload.

Specified by:

offer in class Publication

Parameters:

bufferOne - containing the first part of the message.

offsetOne - at which the first part of the message begins.

lengthOne - of the first part of the message.

bufferTwo - containing the second part of the message.

offsetTwo - at which the second part of the message begins.

lengthTwo - of the second part of the message.

reservedValueSupplier - ReservedValueSupplier for the frame.

Returns:

The new stream position, otherwise a negative error value of Publication.NOT_CONNECTED, Publication.BACK_PRESSURED, Publication.ADMIN_ACTION, Publication.CLOSED, or Publication.MAX_POSITION_EXCEEDED.

offer

public long offer(DirectBufferVector[] vectors,
                  ReservedValueSupplier reservedValueSupplier)

Non-blocking publish by gathering buffer vectors into a message.

Specified by:

offer in class Publication

Parameters:

vectors - which make up the message.

reservedValueSupplier - ReservedValueSupplier for the frame.

Returns:

The new stream position, otherwise a negative error value of Publication.NOT_CONNECTED, Publication.BACK_PRESSURED, Publication.ADMIN_ACTION, Publication.CLOSED, or Publication.MAX_POSITION_EXCEEDED.

tryClaim

public long tryClaim(int length,
                     BufferClaim bufferClaim)

Try to claim a range in the publication log into which a message can be written with zero copy semantics. Once the message has been written then BufferClaim.commit() should be called thus making it available.

Note: This method can only be used for message lengths less than MTU length minus header. If the claim is held for more than the aeron.publication.unblock.timeout system property then the driver will assume the publication thread is dead and will unblock the claim thus allowing other threads to make progress or to reach end-of-stream (EOS).

     final BufferClaim bufferClaim = new BufferClaim(); // Can be stored and reused to avoid allocation

     if (publication.tryClaim(messageLength, bufferClaim) > 0L)
     {
         try
         {
              final MutableDirectBuffer buffer = bufferClaim.buffer();
              final int offset = bufferClaim.offset();

              // Work with buffer directly or wrap with a flyweight
         }
         finally
         {
             bufferClaim.commit();
         }
     }
 

Specified by:

tryClaim in class Publication

Parameters:

length - of the range to claim, in bytes..

bufferClaim - to be populated if the claim succeeds.

Returns:

The new stream position, otherwise a negative error value of Publication.NOT_CONNECTED, Publication.BACK_PRESSURED, Publication.ADMIN_ACTION, Publication.CLOSED, or Publication.MAX_POSITION_EXCEEDED.

Throws:

java.lang.IllegalArgumentException - if the length is greater than Publication.maxPayloadLength() within an MTU.

See Also:

BufferClaim.commit(), BufferClaim.abort()