Package me.ahoo.cosid.machine.lease

Interface MachineLeaseStore

All Known Implementing Classes:
InMemoryMachineLeaseStore, JdbcMachineLeaseStore, MongoMachineLeaseStore, ProxyMachineLeaseStore, SpringRedisMachineLeaseStore, ZookeeperMachineLeaseStore
public interface MachineLeaseStore
Storage primitives for machine id leases, with compare-and-set semantics.

Backends implement only these primitives; the allocation order (self, released, new, expired), guarding and clock-backwards handling live in core. Every claim is atomic: when several instances claim concurrently, each machine id goes to at most one of them. MachineLeaseStoreSpec in cosid-test is the compatibility kit every implementation must pass.

Time contract

All timestamps are milliseconds, and every now and expiredBefore passed to a store must come from that same store's serverTime(). A claim or renewal sets renewed at to now, and expiry compares it with expiredBefore: if instance A wrote it with its own clock and instance B computed expiredBefore from a faster clock, B would recycle A's lease early and both would generate the same ids. Stores with a server clock (Redis, databases, MongoDB) override serverTime(); stores without one (ZooKeeper) fall back to the host clock, so their hosts' clocks must be kept in sync.

The watermark never decreases. Every claim (self, released, new or expired) raises it to at least now and the stored renewed at, so an owner whose host clock is behind the store never reuses timestamps the previous owner may have issued; release raises it to the generator's last timestamp; renewing does not move it. The version changes on every write, and renew and release compare against it.

Since:
3.4.0

  • Method Summary

    Modifier and Type
    Method
    Description
    Optional<Lease>
    claimExpired(String namespace, InstanceId instanceId, int maxMachineId, long expiredBefore, long now)
    Take over a machine id whose owner has not renewed it since expiredBefore.
    Optional<Lease>
    claimNew(String namespace, InstanceId instanceId, int maxMachineId, long now)
    Take the next machine id that was never used in the namespace.
    Optional<Lease>
    claimReleased(String namespace, InstanceId instanceId, int maxMachineId, long now)
    Take a machine id that a non-stable instance released on shutdown.
    Optional<Lease>
    claimSelf(String namespace, InstanceId instanceId, long now)
    Take back the lease this instance already holds, renewing it to now, whether or not it has expired.
    boolean
    release(Lease lease, long watermark)
    Release a lease on shutdown, if it is still the current version.
    Optional<Lease>
    renew(Lease lease, long now)
    Renew a lease to now if it is still the current version, even when now is before the stored renewed at (the store clock moved back).
    default long
    serverTime()
    The store's clock, in milliseconds, when it has one; otherwise this host's clock.

  • Method Details

    • claimSelf

      Optional<Lease> claimSelf(String namespace, InstanceId instanceId, long now)
      Take back the lease this instance already holds, renewing it to now, whether or not it has expired. The watermark is raised to at least now and the stored renewed at.
      Returns:
      the renewed lease, or empty if the instance holds none (it was released or recycled)

    • claimReleased

      Optional<Lease> claimReleased(String namespace, InstanceId instanceId, int maxMachineId, long now)
      Take a machine id that a non-stable instance released on shutdown.
      Parameters:
      maxMachineId - the largest machine id allowed: released ids above it (left over from a larger machine bit) are never returned
      Returns:
      the new lease, or empty if no released machine id up to maxMachineId is left

    • claimNew

      Optional<Lease> claimNew(String namespace, InstanceId instanceId, int maxMachineId, long now)
      Take the next machine id that was never used in the namespace.
      Parameters:
      maxMachineId - the largest machine id allowed
      Returns:
      the new lease, or empty if every machine id up to maxMachineId is in use

    • claimExpired

      Optional<Lease> claimExpired(String namespace, InstanceId instanceId, int maxMachineId, long expiredBefore, long now)
      Take over a machine id whose owner has not renewed it since expiredBefore. Leases of stable instances are never taken over.
      Parameters:
      maxMachineId - the largest machine id allowed: expired ids above it are never returned
      expiredBefore - leases renewed at or before this time are expired
      Returns:
      the new lease, or empty if no lease up to maxMachineId has expired

    • renew

      Optional<Lease> renew(Lease lease, long now)
      Renew a lease to now if it is still the current version, even when now is before the stored renewed at (the store clock moved back). The watermark is unchanged.
      Returns:
      the renewed lease, or empty if the lease was taken over, released or changed since

    • release

      boolean release(Lease lease, long watermark)
      Release a lease on shutdown, if it is still the current version. A stable instance keeps its machine id (only the watermark is updated); otherwise the machine id becomes available to claimReleased(java.lang.String, me.ahoo.cosid.machine.InstanceId, int, long).
      Parameters:
      watermark - the generator's last timestamp: the watermark becomes at least this, so that the next owner waits if its clock is behind
      Returns:
      false if the lease was taken over or changed since

    • serverTime

      default long serverTime()
      The store's clock, in milliseconds, when it has one; otherwise this host's clock. The source of every now and expiredBefore passed to this store.