io.aeron

Class ExclusivePublication

java.lang.Object

io.aeron.Publication

io.aeron.ExclusivePublication

All Implemented Interfaces:

java.lang.AutoCloseable

public class ExclusivePublication
extends Publication

Aeron publisher API for sending messages to subscribers of a given channel and streamId pair. ExclusivePublications each get their own session id so multiple can be concurrently active on the same media driver as independent streams.

ExclusivePublications are created via the Aeron.addExclusivePublication(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.

ExclusivePublications have the potential to provide greater throughput than the default Publication which supports concurrent access.

The APIs used for tryClaim and offer are non-blocking.

Note: Instances are NOT threadsafe for offer and tryClaim methods but are for the others.

See Also:

Aeron.addExclusivePublication(String, int), ExclusiveBufferClaim

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	appendPadding(int length) Append a padding record log of a given length to make up the log to a position.
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, originalRegistrationId, position, positionLimit, positionLimitId, registrationId, removeDestination, sessionId, streamId, termBufferLength

Methods inherited from class java.lang.Object

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

Method Detail

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(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 after the publication is closed, or the client dies, then it will be unblocked to reach end-of-stream (EOS).

     final ExclusiveBufferClaim bufferClaim = new ExclusiveBufferClaim();

     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()

appendPadding

public long appendPadding(int length)

Append a padding record log of a given length to make up the log to a position.

Parameters:

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

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.maxMessageLength().