io.aeron

Class ExclusivePublication

java.lang.Object

io.aeron.Publication

io.aeron.ExclusivePublication

All Implemented Interfaces:

AutoCloseable

public final 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)

Field Summary

Fields inherited from class io.aeron.Publication

ADMIN_ACTION, BACK_PRESSURED, CLOSED, MAX_POSITION_EXCEEDED, NOT_CONNECTED

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	availableWindow() Available window for offering into a publication before the Publication.positionLimit() is reached.
long	offer(DirectBuffer bufferOne, int offsetOne, int lengthOne, DirectBuffer bufferTwo, int offsetTwo, int lengthTwo, ReservedValueSupplier reservedValueSupplier) Non-blocking publish of a message composed of two parts, e.g.
long	offer(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	offerBlock(MutableDirectBuffer buffer, int offset, int length) Offer a block of pre-formatted message fragments directly into the current term.
long	position() Get the current position to which the publication has advanced for this stream.
int	termId() The current term-id of the publication.
int	termOffset() The current term-offset of the publication.
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, asyncAddDestination, asyncRemoveDestination, channel, channelStatus, channelStatusId, close, initialTermId, isClosed, isConnected, isOriginal, localSocketAddresses, maxMessageLength, maxPayloadLength, maxPossiblePosition, offer, offer, offer, offer, originalRegistrationId, 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

position

public long position()

Description copied from class: Publication

Get the current position to which the publication has advanced for this stream.

Overrides:

position in class Publication

Returns:

the current position to which the publication has advanced for this stream or Publication.CLOSED.

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.

termId

public int termId()

The current term-id of the publication.

Returns:

the current term-id of the publication.

termOffset

public int termOffset()

The current term-offset of the publication.

Returns:

the current term-offset of the publication.

offer

public long offer(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(DirectBuffer bufferOne,
                  int offsetOne,
                  int lengthOne,
                  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 after the publication is closed, or the client dies, then it will be unblocked to reach end-of-stream (EOS).

     final BufferClaim bufferClaim = new BufferClaim();

     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:

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:

IllegalArgumentException - if the length is greater than Publication.maxMessageLength().

offerBlock

public long offerBlock(MutableDirectBuffer buffer,
                       int offset,
                       int length)

Offer a block of pre-formatted message fragments directly into the current term.

Parameters:

buffer - containing the pre-formatted block of message fragments.

offset - offset in the buffer at which the first fragment begins.

length - in bytes of the encoded block.

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:

IllegalArgumentException - if the length is greater than remaining size of the current term.

IllegalArgumentException - if the first frame within the block is not properly formatted, i.e. if the streamId is not equal to the value returned by the Publication.streamId() method or if the sessionId is not equal to the value returned by the Publication.sessionId() method or if the frame type is not equal to the HeaderFlyweight.HDR_TYPE_DATA.