Package me.ahoo.cosid.machine

Interface MachineIdDistributor

All Known Implementing Classes:
AbstractMachineIdDistributor, JdbcMachineIdDistributor, ManualMachineIdDistributor, MongoMachineIdDistributor, ProxyMachineIdDistributor, SpringRedisMachineIdDistributor, StatefulSetMachineIdDistributor, ZookeeperMachineIdDistributor
@ThreadSafe public interface MachineIdDistributor
Machine ID distributor for coordinating unique machine identifiers in distributed systems.

In distributed ID generation, each machine or instance must have a unique identifier to ensure global uniqueness of generated IDs. This interface provides the contract for distributing and managing these machine IDs across a cluster.

The distributor is responsible for:

  • Allocating unique machine IDs within a namespace
  • Reverting (releasing) machine IDs when instances shut down
  • Guarding machine IDs with heartbeats to detect failures

Common implementations include:

  • Redis-based distribution
  • ZooKeeper-based distribution
  • JDBC-based distribution

Machine-Id-Safe-Guard

Implementations of this interface are expected to be thread-safe and can be used concurrently across multiple threads.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Duration
    FOREVER_SAFE_GUARD_DURATION
    A duration representing forever for safe guard purposes.

  • Method Summary

    Modifier and Type
    Method
    Description
    MachineState
    distribute(String namespace, int machineBit, InstanceId instanceId, Duration safeGuardDuration)
    Distribute (allocate) a machine ID within the specified namespace.
    static long
    getSafeGuardAt(Duration safeGuardDuration, boolean stable)
    Calculate the safe guard timestamp.
    void
    guard(String namespace, InstanceId instanceId, Duration safeGuardDuration)
    Guard a machine ID with a heartbeat mechanism.
    static int
    maxMachineId(int machineBit)
    Calculate the maximum machine ID for the specified bit size.
    static String
    namespacedMachineId(String namespace, int machineId)
    Generate a namespaced machine ID string.
    void
    revert(String namespace, InstanceId instanceId)
    Revert (release) a previously allocated machine ID.
    static int
    totalMachineIds(int machineBit)
    Calculate the total number of machine IDs for the specified bit size.

  • Field Details

    • FOREVER_SAFE_GUARD_DURATION

      static final Duration FOREVER_SAFE_GUARD_DURATION
      A duration representing forever for safe guard purposes.

      This constant is used to indicate that machine ID guarding should persist indefinitely, without expiration.

  • Method Details

    • maxMachineId

      static int maxMachineId(int machineBit)
      Calculate the maximum machine ID for the specified bit size.

      This method calculates the largest machine ID that can be represented with the given number of bits, which determines how many unique machines can participate in ID generation.

      Parameters:
      machineBit - The number of bits used for machine IDs
      Returns:
      The maximum machine ID value

    • totalMachineIds

      static int totalMachineIds(int machineBit)
      Calculate the total number of machine IDs for the specified bit size.

      This method calculates the total number of unique machine IDs that can be allocated with the given bit size, including zero.

      Parameters:
      machineBit - The number of bits used for machine IDs
      Returns:
      The total number of machine IDs

    • namespacedMachineId

      static String namespacedMachineId(String namespace, int machineId)
      Generate a namespaced machine ID string.

      This method creates a formatted string that combines a namespace with a machine ID, padding the machine ID with leading zeros to ensure consistent formatting.

      Parameters:
      namespace - The namespace for the machine ID
      machineId - The machine ID
      Returns:
      A formatted namespaced machine ID string

    • getSafeGuardAt

      static long getSafeGuardAt(Duration safeGuardDuration, boolean stable)
      Calculate the safe guard timestamp.

      This method calculates the timestamp before which a machine ID should be considered stale and potentially reallocated if not guarded by a heartbeat.

      Parameters:
      safeGuardDuration - The duration for safe guarding
      stable - Whether the system is in a stable state
      Returns:
      The safe guard timestamp

    • distribute

      @Nonnull MachineState distribute(String namespace, int machineBit, InstanceId instanceId, Duration safeGuardDuration) throws MachineIdOverflowException
      Distribute (allocate) a machine ID within the specified namespace.

      This method allocates a unique machine ID for the given instance within the specified namespace. The allocated ID is guaranteed to be unique within that namespace for the duration of its lease.

      The method returns a MachineState object containing the allocated machine ID and associated metadata.

      Parameters:
      namespace - The namespace for machine ID allocation
      machineBit - The number of bits to use for machine IDs
      instanceId - The instance identifier requesting the machine ID
      safeGuardDuration - The duration for safe guarding the allocation
      Returns:
      The machine state containing the allocated machine ID
      Throws:
      MachineIdOverflowException - if no more machine IDs are available

    • revert

      void revert(String namespace, InstanceId instanceId) throws NotFoundMachineStateException
      Revert (release) a previously allocated machine ID.

      This method releases a machine ID back to the distributor, making it available for reallocation. This should be called when an instance shuts down gracefully to enable efficient reuse of machine IDs.

      Parameters:
      namespace - The namespace of the machine ID
      instanceId - The instance identifier whose machine ID should be released
      Throws:
      NotFoundMachineStateException - if the machine ID was not found

    • guard

      void guard(String namespace, InstanceId instanceId, Duration safeGuardDuration) throws NotFoundMachineStateException, MachineIdLostException
      Guard a machine ID with a heartbeat mechanism.

      This method updates the heartbeat timestamp for a machine ID to prevent it from being considered stale and reallocated. It should be called periodically by instances to maintain their machine ID lease.

      Machine-Id-Safe-Guard

      Parameters:
      namespace - The namespace of the machine ID
      instanceId - The instance identifier whose machine ID should be guarded
      safeGuardDuration - The duration for safe guarding the allocation
      Throws:
      NotFoundMachineStateException - if the machine ID was not found
      MachineIdLostException - if the machine ID has been lost or reallocated