Class LeaseConfig

java.lang.Object
io.krabka.streams.coordination.LeaseConfig
public final class LeaseConfig extends Object
The lease timings of one role.

The lease adds no safety. The leadership epoch is the safety mechanism, and the broker enforces it. The lease decides when a standby stops waiting for a quiet holder, and nothing else. A wrong timing makes a failover early or late. A wrong timing never makes two members authoritative.

The three extents are independent of the record layout, so one process holds several roles with different timings. Build a value with of(Duration, Duration, Duration), which rejects a set of extents that cannot work, or take defaults().

Example

LeaseConfig config = LeaseConfig.of(
    Duration.ofSeconds(30), Duration.ofSeconds(10), Duration.ofSeconds(5));
Lease lease = config.grant(me, token, clock.nowMillis());
long renewAt = config.timing(lease).renewAtMillis();

  • Field Details

    • DEFAULT_LEASE_DURATION

      public static final Duration DEFAULT_LEASE_DURATION
      The default extent of a lease.

    • DEFAULT_RENEW_INTERVAL

      public static final Duration DEFAULT_RENEW_INTERVAL
      The default gap between two renewals by the holder.

    • DEFAULT_CHALLENGE_STAGGER

      public static final Duration DEFAULT_CHALLENGE_STAGGER
      The default extra delay that one rank of succession adds.

  • Method Details

    • defaults

      public static LeaseConfig defaults()
      Returns the config of DEFAULT_LEASE_DURATION, DEFAULT_RENEW_INTERVAL, and DEFAULT_CHALLENGE_STAGGER.
      Returns:
      the default lease timings

    • of

      public static LeaseConfig of(Duration duration, Duration renewInterval, Duration challengeStagger)
      Builds a lease policy from three extents.

      A caller should set the renew interval to at most a third of the duration. The holder then keeps two more attempts before the deadline. This factory accepts a larger value. Ask renewsWithMargin() which side of that bound a value is on.

      Parameters:
      duration - the extent of a lease that a member takes now
      renewInterval - the gap between two renewals by the holder
      challengeStagger - the extra delay that one rank of succession adds
      Returns:
      the lease policy of the three extents
      Throws:
      CoordinationException - if an extent is zero or negative, or if the renew interval is not shorter than the duration
      NullPointerException - if an extent is null

    • duration

      public Duration duration()
      Returns the extent of a lease that a member takes now.
      Returns:
      the lease duration

    • renewInterval

      public Duration renewInterval()
      Returns the gap between two renewals by the holder.
      Returns:
      the renew interval

    • challengeStagger

      public Duration challengeStagger()
      Returns the extra delay that one rank of succession adds.
      Returns:
      the challenge stagger

    • renewsWithMargin

      public boolean renewsWithMargin()
      Reports whether the renew interval leaves the holder two spare attempts.

      The interval this module recommends is at most a third of the lease duration. A config outside that bound still works, and the holder then loses the role after fewer missed renewals.

      Returns:
      true when three renew intervals fit inside the lease duration

    • challengeDelayMillis

      public long challengeDelayMillis(int rank)
      Returns the extra delay that a challenger of one rank takes.

      Rank 0 takes none. The value saturates, so a very large rank does not wrap the instant that a caller adds it to.

      Parameters:
      rank - the challenge rank, where zero is the first standby
      Returns:
      the delay in milliseconds

    • grant

      public Lease grant(MemberId member, FencingToken token, long nowMillis)
      Builds the lease record that a member writes after it mints a token.

      A renewal writes the same record with the same token and a later instant, so this one method covers a first grant and a renewal.

      Parameters:
      member - the member that holds the role
      token - the token the transaction coordinator minted for the member
      nowMillis - the instant of the grant, in milliseconds since the Unix epoch
      Returns:
      the lease record to write
      Throws:
      NullPointerException - if the member or the token is null

    • timing

      public LeaseTiming timing(Lease lease)
      Binds a lease record to this policy and answers the clock questions about it.
      Parameters:
      lease - the lease record to read
      Returns:
      the lease clock of that record under this policy
      Throws:
      NullPointerException - if the lease is null

    • equals

      public boolean equals(Object other)
      Reports whether another object is a config with the same three extents.
      Overrides:
      equals in class Object
      Parameters:
      other - the object to compare against
      Returns:
      true when the other object carries these extents

    • hashCode

      public int hashCode()
      Returns a hash of the three extents.
      Overrides:
      hashCode in class Object
      Returns:
      the hash code of the duration, the renew interval, and the stagger

    • toString

      public String toString()
      Returns the three extents in milliseconds.
      Overrides:
      toString in class Object
      Returns:
      a description of this policy