diff --git a/aeron-cluster/src/main/java/io/aeron/cluster/service/Cluster.java b/aeron-cluster/src/main/java/io/aeron/cluster/service/Cluster.java index cb6a9aa434..0a589e5a19 100644 --- a/aeron-cluster/src/main/java/io/aeron/cluster/service/Cluster.java +++ b/aeron-cluster/src/main/java/io/aeron/cluster/service/Cluster.java @@ -253,8 +253,18 @@ public static Role get(final AtomicCounter counter) * {@link ClusteredService#onSessionClose(ClientSession, long, CloseReason)}. * If applied to other events then they are not guaranteed to be reliable. *
- * Callers of this method must loop until the method succeeds, see {@link - * io.aeron.cluster.service.Cluster#scheduleTimer(long, long)} for an example. + * Callers of this method must loop until the method succeeds. + * + *
{@code + * private Cluster cluster; + * // Lines omitted... + * + * cluster.idleStrategy().reset(); + * while (!cluster.cancelTimer(correlationId)) + * { + * cluster.idleStrategy().idle(); + * } + * }* * @param correlationId for the timer provided when it was scheduled. {@link Long#MAX_VALUE} not supported. * @return true if the request to cancel a timer has been sent or false if back-pressure is applied. @@ -267,14 +277,14 @@ public static Role get(final AtomicCounter counter) * consensus module and have the cluster session of as the * {@link io.aeron.cluster.service.ClusteredServiceContainer.Configuration#SERVICE_ID_PROP_NAME}. *
- * Callers of this method should loop until the method succeeds. + * Callers of this method must loop until the method succeeds. * *
{@code * private Cluster cluster; * // Lines omitted... * * cluster.idleStrategy().reset(); - * do + * while(true) * { * final long position = cluster.offer(buffer, offset, length); * if (position > 0) @@ -288,7 +298,6 @@ public static Role get(final AtomicCounter counter) * * cluster.idleStrategy.idle(); * } - * while (true); * }* * The cluster's idle strategy must be used in the body of the loop to allow for the clustered service to be @@ -324,27 +333,36 @@ public static Role get(final AtomicCounter counter) *
* On successful claim, the Cluster session header will be written to the start of the claimed buffer section. * Clients MUST write into the claimed buffer region at offset + {@link AeronCluster#SESSION_HEADER_LENGTH}. + *
+ * Callers of this method must loop until the method succeeds. + * *
{@code - * final DirectBuffer srcBuffer = acquireMessage(); + * private final BufferClaim bufferClaim = new BufferClaim(); + * private Cluster cluster; + * // Lines omitted... * - * if (cluster.tryClaim(length, bufferClaim)) + * final DirectBuffer srcBuffer = acquireMessage(); + * cluster.idleStrategy().reset(); + * while(true) + * { + * final long position = cluster.tryClaim(length, bufferClaim); + * if (position > 0) * { - * try - * { - * final MutableDirectBuffer buffer = bufferClaim.buffer(); - * final int offset = bufferClaim.offset(); - * // ensure that data is written at the correct offset - * buffer.putBytes(offset + AeronCluster.SESSION_HEADER_LENGTH, srcBuffer, 0, length); - * } - * finally - * { - * bufferClaim.commit(); - * } + * final MutableDirectBuffer buffer = bufferClaim.buffer(); + * final int offset = bufferClaim.offset(); + * // ensure that data is written after the session header + * buffer.putBytes(offset + AeronCluster.SESSION_HEADER_LENGTH, srcBuffer, 0, length); + * bufferClaim.commit(); + * break; * } + * else if (Publication.ADMIN_ACTION != position && Publication.BACK_PRESSURED != position) + * { + * throw new ClusterException("Internal tryClaim failed: " + position); + * } + * + * cluster.idleStrategy.idle(); + * } * }- *
- * Callers of this method should loop until the method succeeds, see - * {@link io.aeron.cluster.service.Cluster#offer(DirectBuffer, int, int)} for an example. * * @param length of the range to claim, in bytes. * @param bufferClaim to be populated if the claim succeeds.