io.aeron.cluster.service

Interface Cluster

public interface Cluster

Interface for a ClusteredService to interact with cluster hosting it.

This object should only be used to send messages to the cluster or schedule timers in response to other messages and timers. Sending messages and timers should not happen from cluster lifecycle methods like ClusteredService.onStart(Cluster, Image), ClusteredService.onRoleChange(Cluster.Role) or ClusteredService.onTakeSnapshot(ExclusivePublication), or ClusteredService.onTerminate(Cluster), with the exception of the session lifecycle methods ClusteredService.onSessionOpen(ClientSession, long) and ClusteredService.onSessionClose(ClientSession, long, CloseReason).

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Cluster.Role Role of the node in the cluster.

Method Summary

Modifier and Type	Method and Description
Aeron	aeron() Get the Aeron client used by the cluster.
boolean	cancelTimer(long correlationId) Cancel a previously scheduled timer.
Collection<ClientSession>	clientSessions() Get the current collection of cluster client sessions.
boolean	closeClientSession(long clusterSessionId) Request the close of a ClientSession by sending the request to the consensus module.
ClusteredServiceContainer.Context	context() Get the ClusteredServiceContainer.Context under which the container is running.
void	forEachClientSession(Consumer<? super ClientSession> action) For each iterator over ClientSessions using the most efficient method possible.
ClientSession	getClientSession(long clusterSessionId) Get the ClientSession for a given cluster session id.
IdleStrategy	idleStrategy() IdleStrategy which should be used by the service when it experiences back-pressure on egress, closing sessions, making timer requests, or any long running actions.
long	logPosition() Position the log has reached in bytes as of the current message.
int	memberId() The unique id for the hosting member of the cluster.
long	offer(DirectBuffer buffer, int offset, int length) Offer a message as ingress to the cluster for sequencing.
long	offer(DirectBufferVector[] vectors) Offer a message as ingress to the cluster for sequencing.
Cluster.Role	role() The role the cluster node is playing.
boolean	scheduleTimer(long correlationId, long deadline) Schedule a timer for a given deadline and provide a correlation id to identify the timer when it expires or for cancellation.
long	time() Cluster time as timeUnit()s since 1 Jan 1970 UTC.
TimeUnit	timeUnit() The unit of time applied to timestamps and time().
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.

Method Detail

memberId

int memberId()

The unique id for the hosting member of the cluster. Useful only for debugging purposes.

Returns:

unique id for the hosting member of the cluster.

role

Cluster.Role role()

The role the cluster node is playing.

Returns:

the role the cluster node is playing.

logPosition

long logPosition()

Position the log has reached in bytes as of the current message.

Returns:

position the log has reached in bytes as of the current message.

aeron

Aeron aeron()

Get the Aeron client used by the cluster.

Returns:

the Aeron client used by the cluster.

context

ClusteredServiceContainer.Context context()

Get the ClusteredServiceContainer.Context under which the container is running.

Returns:

the ClusteredServiceContainer.Context under which the container is running.

getClientSession

ClientSession getClientSession(long clusterSessionId)

Get the ClientSession for a given cluster session id.

Parameters:

clusterSessionId - to be looked up.

Returns:

the ClientSession that matches the clusterSessionId.

clientSessions

Collection<ClientSession> clientSessions()

Get the current collection of cluster client sessions.

The Iterator on this class does not support nested iteration. It reuses the iterator to avoid allocation.

Returns:

the current collection of cluster client sessions.

forEachClientSession

void forEachClientSession(Consumer<? super ClientSession> action)

For each iterator over ClientSessions using the most efficient method possible.

Parameters:

action - to be taken for each ClientSession in turn.

closeClientSession

boolean closeClientSession(long clusterSessionId)

Request the close of a ClientSession by sending the request to the consensus module.

Parameters:

clusterSessionId - to be closed.

Returns:

true if the event to close a session was sent or false if back pressure was applied.

Throws:

ClusterException - if the clusterSessionId is not recognised.

time

long time()

Cluster time as timeUnit()s since 1 Jan 1970 UTC.

Returns:

time as timeUnit()s since 1 Jan 1970 UTC.

timeUnit

TimeUnit timeUnit()

The unit of time applied to timestamps and time().

Returns:

the unit of time applied to timestamps and time().

scheduleTimer

boolean scheduleTimer(long correlationId,
                      long deadline)

Schedule a timer for a given deadline and provide a correlation id to identify the timer when it expires or for cancellation. This action is asynchronous and will race with the timer expiring.

If the correlationId is for an existing scheduled timer then it will be reschedule to the new deadline. However it is best to generate correlationIds in a monotonic fashion and be aware of potential clashes with other services in the same cluster. Service isolation can be achieved by using the upper bits for service id.

Timers should only be scheduled or cancelled in the context of processing a ClusteredService.onSessionMessage(ClientSession, long, DirectBuffer, int, int, Header), ClusteredService.onTimerEvent(long, long), ClusteredService.onSessionOpen(ClientSession, long), or ClusteredService.onSessionClose(ClientSession, long, CloseReason). If applied to other events then they are not guaranteed to be reliable.

Parameters:

correlationId - to identify the timer when it expires. Long.MAX_VALUE not supported.

deadline - time after which the timer will fire. Long.MAX_VALUE not supported.

Returns:

true if the event to schedule a timer request has been sent or false if back-pressure is applied.

See Also:

cancelTimer(long)

cancelTimer

boolean cancelTimer(long correlationId)

Cancel a previously scheduled timer. This action is asynchronous and will race with the timer expiring.

Timers should only be scheduled or cancelled in the context of processing a ClusteredService.onSessionMessage(ClientSession, long, DirectBuffer, int, int, Header), ClusteredService.onTimerEvent(long, long), ClusteredService.onSessionOpen(ClientSession, long), or ClusteredService.onSessionClose(ClientSession, long, CloseReason). If applied to other events then they are not guaranteed to be reliable.

Parameters:

correlationId - for the timer provided when it was scheduled. Long.MAX_VALUE not supported.

Returns:

true if the event to cancel request has been sent or false if back-pressure is applied.

See Also:

scheduleTimer(long, long)

offer

long offer(DirectBuffer buffer,
           int offset,
           int length)

Offer a message as ingress to the cluster for sequencing. This will happen efficiently over IPC to the consensus module and have the cluster session of as the negative value of the ClusteredServiceContainer.Configuration.SERVICE_ID_PROP_NAME.

Parameters:

buffer - containing the message to be offered.

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

length - in the buffer of the encoded message.

Returns:

positive value if successful.

See Also:

Publication.offer(DirectBuffer, int, int)

offer

long offer(DirectBufferVector[] vectors)

Offer a message as ingress to the cluster for sequencing. This will happen efficiently over IPC to the consensus module and have the cluster session of as the negative value of the ClusteredServiceContainer.Configuration.SERVICE_ID_PROP_NAME.

The first vector must be left free to be filled in for the session message header.

Parameters:

vectors - containing the message parts with the first left to be filled.

Returns:

positive value if successful.

See Also:

Publication.offer(DirectBufferVector[])

tryClaim

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.

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 + AeronCluster.SESSION_HEADER_LENGTH.

     final DirectBuffer srcBuffer = acquireMessage();

     if (cluster.tryClaim(length, bufferClaim))
     {
         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();
         }
     }
 

Parameters:

length - of the range to claim, in bytes.

bufferClaim - to be populated if the claim succeeds.

Returns:

positive value if successful.

Throws:

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

See Also:

Publication.tryClaim(int, BufferClaim), BufferClaim.commit(), BufferClaim.abort()

idleStrategy

IdleStrategy idleStrategy()

IdleStrategy which should be used by the service when it experiences back-pressure on egress, closing sessions, making timer requests, or any long running actions.

Returns:

the IdleStrategy which should be used by the service when it experiences back-pressure.