public abstract class Publication
extends java.lang.Object
implements java.lang.AutoCloseable
Publication
s
are created via the Aeron.addPublication(String, int)
Aeron.addExclusivePublication(String, int)
methods, and messages are sent via one of the offer(DirectBuffer)
methods.
The APIs used for tryClaim and offer are non-blocking.
Note: All methods are threadsafe with the exception of offer and tryClaim for the subclass
ExclusivePublication
. In the case of ConcurrentPublication
all methods are threadsafe.
Modifier and Type | Field and Description |
---|---|
static long |
ADMIN_ACTION
The offer failed due to an administration action and should be retried.
|
static long |
BACK_PRESSURED
The offer failed due to back pressure from the subscribers preventing further transmission.
|
protected java.lang.String |
channel |
protected int |
channelStatusId |
static long |
CLOSED
The
Publication has been closed and should no longer be used. |
protected io.aeron.ClientConductor |
conductor |
protected HeaderWriter |
headerWriter |
protected int |
initialTermId |
protected boolean |
isClosed |
protected LogBuffers |
logBuffers |
protected org.agrona.concurrent.UnsafeBuffer |
logMetaDataBuffer |
static long |
MAX_POSITION_EXCEEDED
The offer failed due to reaching the maximum position of the stream given term buffer length times the total
possible number of terms.
|
protected int |
maxMessageLength |
protected int |
maxPayloadLength |
protected long |
maxPossiblePosition |
static long |
NOT_CONNECTED
The publication is not yet connected to a subscriber.
|
protected long |
originalRegistrationId |
protected int |
positionBitsToShift |
protected org.agrona.concurrent.status.ReadablePosition |
positionLimit |
protected long |
registrationId |
protected int |
sessionId |
protected int |
streamId |
protected int |
termBufferLength |
Modifier | Constructor and Description |
---|---|
protected |
Publication(io.aeron.ClientConductor clientConductor,
java.lang.String channel,
int streamId,
int sessionId,
org.agrona.concurrent.status.ReadablePosition positionLimit,
int channelStatusId,
LogBuffers logBuffers,
long originalRegistrationId,
long registrationId) |
Modifier and Type | Method and Description |
---|---|
void |
addDestination(java.lang.String endpointChannel)
Add a destination manually to a multi-destination-cast Publication.
|
abstract long |
availableWindow()
Available window for offering into a publication before the
positionLimit() is reached. |
java.lang.String |
channel()
Media address for delivery to the channel.
|
long |
channelStatus()
Get the status of the media channel for this Publication.
|
int |
channelStatusId()
Get the counter used to represent the channel status for this publication.
|
void |
close()
Release resources used by this Publication when there are no more references.
|
int |
initialTermId()
The initial term id assigned when this
Publication was created. |
boolean |
isClosed()
Has this object been closed and should no longer be used?
|
boolean |
isConnected()
Has the
Publication seen an active Subscriber recently? |
boolean |
isOriginal()
Is this Publication the original instance added to the driver? If not then it was added after another client
has already added the publication.
|
int |
maxMessageLength()
Maximum message length supported in bytes.
|
int |
maxPayloadLength()
Maximum length of a message payload that fits within a message fragment.
|
long |
maxPossiblePosition()
The maximum possible position this stream can reach due to its term buffer length.
|
long |
offer(org.agrona.DirectBuffer buffer)
Non-blocking publish of a buffer containing a message.
|
long |
offer(org.agrona.DirectBuffer buffer,
int offset,
int length)
Non-blocking publish of a partial buffer containing a message.
|
long |
offer(org.agrona.DirectBuffer bufferOne,
int offsetOne,
int lengthOne,
org.agrona.DirectBuffer bufferTwo,
int offsetTwo,
int lengthTwo)
Non-blocking publish of a message composed of two parts, e.g.
|
abstract 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.
|
abstract 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)
Non-blocking publish by gathering buffer vectors into a message.
|
abstract long |
offer(DirectBufferVector[] vectors,
ReservedValueSupplier reservedValueSupplier)
Non-blocking publish by gathering buffer vectors into a message.
|
long |
originalRegistrationId()
Get the registration used to register this Publication with the media driver by the first publisher.
|
long |
position()
Get the current position to which the publication has advanced for this stream.
|
int |
positionBitsToShift()
Number of bits to right shift a position to get a term count for how far the stream has progressed.
|
long |
positionLimit()
Get the position limit beyond which this
Publication will be back pressured. |
int |
positionLimitId()
Get the counter id for the position limit after which the publication will be back pressured.
|
long |
registrationId()
Get the registration id used to register this Publication with the media driver.
|
void |
removeDestination(java.lang.String endpointChannel)
Remove a previously added destination manually from a multi-destination-cast Publication.
|
int |
sessionId()
Session under which messages are published.
|
int |
streamId()
Stream identity for scoping within the channel media address.
|
int |
termBufferLength()
Get the length in bytes for each term partition in the log buffer.
|
java.lang.String |
toString() |
abstract 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.
|
public static final long NOT_CONNECTED
public static final long BACK_PRESSURED
public static final long ADMIN_ACTION
public static final long CLOSED
Publication
has been closed and should no longer be used.public static final long MAX_POSITION_EXCEEDED
If this happens then the publication should be closed and a new one added. To make it less likely to happen then increase the term buffer length.
protected final long originalRegistrationId
protected final long registrationId
protected final long maxPossiblePosition
protected final int channelStatusId
protected final int streamId
protected final int sessionId
protected final int maxMessageLength
protected final int initialTermId
protected final int maxPayloadLength
protected final int positionBitsToShift
protected final int termBufferLength
protected volatile boolean isClosed
protected final org.agrona.concurrent.status.ReadablePosition positionLimit
protected final org.agrona.concurrent.UnsafeBuffer logMetaDataBuffer
protected final HeaderWriter headerWriter
protected final LogBuffers logBuffers
protected final io.aeron.ClientConductor conductor
protected final java.lang.String channel
protected Publication(io.aeron.ClientConductor clientConductor, java.lang.String channel, int streamId, int sessionId, org.agrona.concurrent.status.ReadablePosition positionLimit, int channelStatusId, LogBuffers logBuffers, long originalRegistrationId, long registrationId)
public int positionBitsToShift()
public int termBufferLength()
public long maxPossiblePosition()
Maximum possible position is term-length times 2^31 in bytes.
public java.lang.String channel()
public int streamId()
public int sessionId()
public int initialTermId()
Publication
was created. This can be used to determine how many
terms have passed since creation.public int maxMessageLength()
public int maxPayloadLength()
This is he MTU length minus the message fragment header length.
public long originalRegistrationId()
public boolean isOriginal()
public long registrationId()
If this value is different from the originalRegistrationId()
then a previous active registration exists.
public boolean isConnected()
Publication
seen an active Subscriber recently?Publication
has recently seen an active subscriber otherwise false.public void close()
Publications are reference counted and are only truly closed when the ref count reaches zero.
close
in interface java.lang.AutoCloseable
public boolean isClosed()
public long channelStatus()
The status will be ChannelEndpointStatus.ERRORED
if a socket exception occurs on setup
and ChannelEndpointStatus.ACTIVE
if all is well.
ChannelEndpointStatus
with it being
ChannelEndpointStatus.NO_ID_ALLOCATED
if the publication is closed.ChannelEndpointStatus
public int channelStatusId()
public long position()
CLOSED
.public long positionLimit()
Publication
will be back pressured.
This should only be used as a guide to determine when back pressure is likely to be applied.
Publication
will be back pressured.public int positionLimitId()
public abstract long availableWindow()
positionLimit()
is reached.positionLimit()
is reached. If
the publication is closed then CLOSED
will be returned.public final long offer(org.agrona.DirectBuffer buffer)
buffer
- containing message.NOT_CONNECTED
,
BACK_PRESSURED
, ADMIN_ACTION
, CLOSED
, or MAX_POSITION_EXCEEDED
.public final long offer(org.agrona.DirectBuffer buffer, int offset, int length)
buffer
- containing message.offset
- offset in the buffer at which the encoded message begins.length
- in bytes of the encoded message.NOT_CONNECTED
,
BACK_PRESSURED
, ADMIN_ACTION
, CLOSED
, or MAX_POSITION_EXCEEDED
.public abstract long offer(org.agrona.DirectBuffer buffer, int offset, int length, ReservedValueSupplier reservedValueSupplier)
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.NOT_CONNECTED
,
BACK_PRESSURED
, ADMIN_ACTION
, CLOSED
, or MAX_POSITION_EXCEEDED
.public final long offer(org.agrona.DirectBuffer bufferOne, int offsetOne, int lengthOne, org.agrona.DirectBuffer bufferTwo, int offsetTwo, int lengthTwo)
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.NOT_CONNECTED
,
BACK_PRESSURED
, ADMIN_ACTION
, CLOSED
, or MAX_POSITION_EXCEEDED
.public abstract long offer(org.agrona.DirectBuffer bufferOne, int offsetOne, int lengthOne, org.agrona.DirectBuffer bufferTwo, int offsetTwo, int lengthTwo, ReservedValueSupplier reservedValueSupplier)
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.NOT_CONNECTED
,
BACK_PRESSURED
, ADMIN_ACTION
, CLOSED
, or MAX_POSITION_EXCEEDED
.public final long offer(DirectBufferVector[] vectors)
vectors
- which make up the message.NOT_CONNECTED
,
BACK_PRESSURED
, ADMIN_ACTION
, CLOSED
, or MAX_POSITION_EXCEEDED
.public abstract long offer(DirectBufferVector[] vectors, ReservedValueSupplier reservedValueSupplier)
vectors
- which make up the message.reservedValueSupplier
- ReservedValueSupplier
for the frame.NOT_CONNECTED
,
BACK_PRESSURED
, ADMIN_ACTION
, CLOSED
, or MAX_POSITION_EXCEEDED
.public abstract long tryClaim(int length, BufferClaim bufferClaim)
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
for ConcurrentPublication
and other claims to be sent 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();
}
}
length
- of the range to claim, in bytes..bufferClaim
- to be populated if the claim succeeds.NOT_CONNECTED
,
BACK_PRESSURED
, ADMIN_ACTION
, CLOSED
, or MAX_POSITION_EXCEEDED
.java.lang.IllegalArgumentException
- if the length is greater than maxPayloadLength()
within an MTU.BufferClaim.commit()
,
BufferClaim.abort()
public void addDestination(java.lang.String endpointChannel)
endpointChannel
- for the destination to addpublic void removeDestination(java.lang.String endpointChannel)
endpointChannel
- for the destination to removepublic java.lang.String toString()
toString
in class java.lang.Object
Copyright © 2014-2018 Real Logic Ltd. All Rights Reserved.