Struct Coordinator 

pub struct Coordinator { /* private fields */ }

The distributed coordinator.

The coordinator manages the distributed colony by:

• Maintaining a registry of all active shards
• Routing documents to shards using consistent hashing
• Synchronizing tick phases across all shards
• Aggregating global statistics for TF-IDF computation

Thread Safety

The coordinator is designed for concurrent access. It uses interior mutability with RwLock for the registry and hash ring, and atomics for the tick counter.

Example

use phago_distributed::Coordinator;
use phago_distributed::types::{ShardInfo, NodeAddress};

let coordinator = Coordinator::new(3);

// Register a shard
let info = ShardInfo::new(NodeAddress::new("127.0.0.1", 8080));
let shard_id = coordinator.register_shard(info).await?;

// Route a document
let doc_id = DocumentId::new();
let target_shard = coordinator.route_document(&doc_id).await;

Implementations

impl Coordinator

pub fn new(num_shards: u32) -> Self

Create a new coordinator with the specified number of shards.

The coordinator will initialize the hash ring with the given number of shards, but actual shards must be registered before they can receive documents.

pub fn with_config(config: DistributedConfig) -> Self

Create a coordinator with custom configuration.

pub async fn register_shard( &self, info: ShardInfo, ) -> DistributedResult<ShardId>

Register a shard with the coordinator.

The shard will be assigned a unique ID, added to the registry, and included in the hash ring for document routing.

Arguments

• info - Information about the shard to register

Returns

The assigned shard ID.

pub async fn deregister_shard(&self, shard_id: ShardId) -> DistributedResult<()>

Deregister a shard from the coordinator.

The shard will be removed from the registry and hash ring. Documents previously assigned to this shard will be redistributed.

pub async fn route_document(&self, doc_id: &DocumentId) -> ShardId

Route a document to the appropriate shard.

Uses consistent hashing to determine which shard should store the document. The same document will always route to the same shard (unless the cluster topology changes).

pub async fn get_replica_shards(&self, doc_id: &DocumentId) -> Vec<ShardId>

Get replica shards for a document.

Returns the primary shard plus additional replica shards based on the configured replication factor.

pub async fn phase_complete( &self, shard_id: ShardId, phase: TickPhase, tick: Tick, ) -> DistributedResult<()>

Signal that a shard has completed a phase.

This is called by each shard when it finishes a phase of the tick. The coordinator tracks progress and releases the barrier when all shards have completed.

pub async fn wait_for_phase( &self, phase: TickPhase, tick: Tick, ) -> DistributedResult<()>

Wait for all shards to complete a phase.

Blocks until all registered shards have signaled completion of the specified phase.

pub async fn advance_tick(&self) -> Tick

Advance to the next tick.

This should be called after all phases of the current tick are complete. Returns the new tick number.

pub fn current_tick(&self) -> Tick

Get the current tick number.

pub fn aggregate_global_df( &self, local_dfs: Vec<HashMap<String, u64>>, ) -> HashMap<String, u64>

Aggregate global document frequencies from all shards.

This is used for computing global TF-IDF scores. Each shard provides its local document frequencies, and the coordinator sums them to produce global counts.

Arguments

• local_dfs - Vector of term->count maps from each shard

Returns

A map of term->global_count across all shards.

pub async fn all_shards(&self) -> Vec<ShardInfo>

Get all registered shards.

pub async fn online_shards(&self) -> Vec<ShardInfo>

Get all online shards.

pub async fn get_shard(&self, shard_id: ShardId) -> Option<ShardInfo>

Get a specific shard’s information.

pub async fn shard_heartbeat(&self, shard_id: ShardId)

Update heartbeat for a shard.

Called periodically by shards to indicate they are still alive.

pub async fn check_shard_health(&self) -> Vec<ShardId>

Check for dead shards and mark them offline.

Returns the IDs of shards that were marked offline.

pub async fn update_shard_metrics( &self, shard_id: ShardId, document_count: usize, memory_bytes: u64, )

Update shard metrics.

pub async fn total_documents(&self) -> u64

Get the total number of documents across all shards.

pub async fn cluster_stats(&self) -> ClusterStats

Get cluster statistics.

pub fn config(&self) -> &DistributedConfig

Get the configuration.

pub async fn shard_count(&self) -> u32

Get the shard count from the hash ring.