Module me.ahoo.cosid.core
Package me.ahoo.cosid.lease

Interface SlotLeaseStore

All Superinterfaces:
AutoCloseable
public interface SlotLeaseStore extends AutoCloseable
Leases time windows on machine slots, the lease primitive of a store (05-machine-lease.md §2). Every state change is an atomic conditional update of one slot; the store clock stamps it.

Failures (R1-spi-03): an operation that fails for another reason than its outcome throws a RuntimeException of the backend's choosing (a driver exception, or the store's own wrapper of one). A timeout is recognised with StoreTimeoutException.isTimeout(Throwable), whether the backend throws a StoreTimeoutException or one as the cause; the runtime counts those as store timeouts. No common base class is promised beyond RuntimeException.

  • Method Summary

    Modifier and Type
    Method
    Description
    AcquireResult
    acquire(String namespace, Owner owner, int limit, Duration ttl, Duration tolerance, int slotOffset, OptionalInt preferredSlot)
    Acquires a slot, trying in order (§2.1): one this owner already holds, preferredSlot, the slot this owner key held last, the lowest free slot.
    default void
    close()
     
    boolean
    release(SlotLease lease, long lastIssued)
    Releases a lease; the next holder's floor becomes max(floor, min(lastIssued, ceiling)).
    Optional<SlotLease>
    renew(SlotLease lease, Duration ttl, Duration tolerance)
    Renews a lease; idempotent, the fence stays.

  • Method Details

    • acquire

      AcquireResult acquire(String namespace, Owner owner, int limit, Duration ttl, Duration tolerance, int slotOffset, OptionalInt preferredSlot)
      Acquires a slot, trying in order (§2.1): one this owner already holds, preferredSlot, the slot this owner key held last, the lowest free slot.
      Parameters:
      namespace - the namespace
      owner - the owner
      limit - the slots are [0, limit)
      ttl - the lease expires this long after the write
      tolerance - the ceiling lies this far beyond the expiry (D20)
      slotOffset - the offset the clients add to the slot to get the node of their ids (api-freeze.md §2.1.1); it is recorded with the limit and the tolerance and does not change which slot is chosen
      preferredSlot - the slot to try before the others
      Returns:
      the lease, or AcquireResult.Exhausted
      Throws:
      NamespaceMismatchException - if the namespace was first used with another limit, tolerance or slot offset (metadata written before the slot offset existed reads as offset 0)

    • renew

      Optional<SlotLease> renew(SlotLease lease, Duration ttl, Duration tolerance)
      Renews a lease; idempotent, the fence stays.
      Parameters:
      lease - the lease, as last returned
      ttl - the lease expires this long after the write, never earlier than before
      tolerance - the ceiling lies this far beyond the expiry
      Returns:
      the renewed lease, or empty if the owner or fence no longer match

    • release

      boolean release(SlotLease lease, long lastIssued)
      Releases a lease; the next holder's floor becomes max(floor, min(lastIssued, ceiling)).
      Parameters:
      lease - the lease, as last returned
      lastIssued - the largest timestamp issued under the lease, in milliseconds
      Returns:
      whether the lease was released; false if the owner or fence no longer match

    • close

      default void close()
      Specified by:
      close in interface AutoCloseable