Class Leadership

java.lang.Object
io.krabka.streams.coordination.Leadership
All Implemented Interfaces:
AutoCloseable
public final class Leadership extends Object implements AutoCloseable
The live leadership of one role by one member.

CoordinationClient.tryAcquire(Role, MemberId) returns one after the member minted the epoch of the role and wrote its first lease. The handle carries the token, and the caller passes that token to every guarded write. The broker checks it, so a leader does not have to prove that its lease is live before each write. The write itself carries the proof.

renew() writes a fresh lease record under the same token. It throws FencedException when another member has taken the role, and that exception is the only signal that a leadership ended. A caller stops the work of the role at once and does not retry.

The handle is AutoCloseable. close() resigns, so a standby challenges at once rather than at the deadline of the record this member left behind. A close after a fence is a no-op, because the cluster already moved the role.

One handle is not safe for concurrent use. Confine it to the thread that runs the work of the role.

Example

try (Leadership leadership = client.acquire(role, me, Duration.ofMinutes(1))) {
    while (running) {
        if (leadership.renewDue()) {
            leadership.renew();
        }
        dispatch(leadership.token());
    }
} catch (FencedException lost) {
    controller.stop();
}

  • Method Details

    • role

      public Role role()
      Returns the role this member holds.
      Returns:
      the role of this leadership

    • member

      public MemberId member()
      Returns the member that holds the role.
      Returns:
      the member of this leadership

    • token

      public FencingToken token()
      Returns the quorum-minted proof of this leadership.

      Pass this token to every guarded write. The broker rejects a write that carries an older token.

      Returns:
      the token the transaction coordinator minted for this member

    • lease

      public Lease lease()
      Returns the last lease record this member wrote.
      Returns:
      the current lease of the role

    • timing

      public LeaseTiming timing()
      Returns the lease clock of the current lease.
      Returns:
      the clock questions this policy answers about the current lease

    • held

      public boolean held()
      Reports whether this handle still believes it holds the role.

      The answer turns false after a fence and after a resignation. It says nothing about the lease deadline, because the deadline is not the authority.

      Returns:
      true until this member is fenced or resigns

    • renewDue

      public boolean renewDue()
      Reports whether the holder writes a renewal now.
      Returns:
      true when the renewal instant of the current lease has passed

    • renew

      public Lease renew()
      Writes a fresh lease record under the same token.

      The record carries the same token and a later grant instant, so a renewal and a first grant are the same write. The broker rejects the write when another member has taken the role.

      Returns:
      the lease record this call wrote
      Throws:
      FencedException - if another member holds the role now
      CoordinationException - if this member already resigned, or if the write fails for another reason

    • resign

      public void resign()
      Gives up the role and clears the lease record.

      A standby then challenges at once rather than at the deadline of the record this member left behind. The epoch of this member stays valid until a challenger mints a newer one, so a resignation is a courtesy and not a fence.

      Throws:
      FencedException - if another member already holds the role
      CoordinationException - if this member already resigned, or if the write fails for another reason

    • close

      public void close()
      Resigns when this member still holds the role.

      The method swallows a fence, because a fenced member has nothing left to give up. It rethrows every other failure.

      Specified by:
      close in interface AutoCloseable
      Throws:
      CoordinationException - if the tombstone write fails for a reason other than a fence