Class PartitionRebalancer

java.lang.Object
com.loomcache.server.sharding.PartitionRebalancer
public class PartitionRebalancer extends Object
Handles partition migration between Raft groups when groups are added or removed.

Rebalancing algorithm:

  1. Compute ideal assignment: partition i goes to group i % targetGroups
  2. Compare with current assignment to find moves
  3. Execute moves sequentially: copy data, then update routing
  4. Fence old writes by updating the partition router atomically

Consistency during migration (two-phase copy with routing fence):

  1. Copy: snapshot partition entries and copy to target group
  2. Fence: atomically update routing so new writes go to target
  3. Sweep: re-scan source for entries written during the copy phase
  4. Cleanup: delete migrated entries from source (safe: routing already points to target)

If migration fails, the plan is rolled back to the last successfully completed move. Progress is tracked and can be queried by monitoring tools.

Thread Safety: Only one migration can run at a time, enforced by a reentrant lock. Progress queries are lock-free via AtomicReference.

Since:
2.0

  • Constructor Details

    • PartitionRebalancer

      public PartitionRebalancer(PartitionRouter router, ShardedDataStructureRegistry shardedRegistry)
      Creates a new rebalancer for the given router and sharded registry.
      Parameters:
      router - the partition router to update (must not be null)
      shardedRegistry - the sharded registry containing group data (must not be null)

  • Method Details

    • calculatePlan

      public RebalancePlan calculatePlan(int currentGroups, int targetGroups)
      Calculates a rebalance plan to move from the current group count to the target.

      The plan computes the ideal round-robin assignment for targetGroups and determines which partitions need to move from their current group.

      Parameters:
      currentGroups - the current number of Raft groups (must be > 0)
      targetGroups - the desired number of Raft groups (must be > 0)
      Returns:
      the rebalance plan (never null, may be empty if no moves needed)

    • executeMigration

      public void executeMigration(RebalancePlan plan)
      Executes a migration plan, moving data between groups and updating routing.

      Moves are executed sequentially. For each move:

      1. Data from the source group is copied to the destination group
      2. The partition router mapping is updated
      3. Progress is updated atomically

      If a move fails, the migration stops and the state is left at the last successfully completed move. The router reflects all completed moves.

      Parameters:
      plan - the rebalance plan to execute (must not be null)

    • getProgress

      public MigrationProgress getProgress()
      Returns the current migration progress.
      Returns:
      the progress snapshot (never null)