mars-shard · cross_shard

Package: mars-shard · Workspace version: 0.1.0 · Module: cross_shard

Status: prototype / draft. This is not the production registry topology.

This reference follows declared modules and public syntax, including public implementation methods. Function bodies and constant values are omitted. Feature conditions are retained. Private-module re-exports and trait resolution require the compiler; not every declaration is a root import.

cross_shard::CrossShardQuery

A query that must be executed across multiple shards.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CrossShardQuery {
/// Unique query ID for correlation.

pub query_id: String,
/// Shard IDs that must be queried.

pub target_shards: Vec<String>,
/// The MARS-QL query string.

pub query: String,
/// Per-shard timeout in milliseconds.

pub timeout_ms: u64
}

Source line: 21.

cross_shard::ShardPartialResult

Partial result from a single shard.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ShardPartialResult {
/// The shard that produced this result.

pub shard_id: String,
/// Whether the shard responded successfully.

pub success: bool,
/// Matching entry IDs from this shard.

pub entry_ids: Vec<String>,
/// Optional error message on failure.

#[serde(skip_serializing_if = "Option::is_none")]
pub error: Option<String>
}

Source line: 39.

cross_shard::CrossShardResult

Aggregated result from a cross-shard scatter/gather query.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CrossShardResult {
/// The original query ID.

pub query_id: String,
/// Per-shard partial results.

pub shard_results: Vec<ShardPartialResult>,
/// Merged entry IDs across all successful shards.

pub merged_entry_ids: Vec<String>,
/// Number of shards that responded successfully.

pub success_count: usize,
/// Number of shards that failed.

pub failure_count: usize
}

Source line: 58.

cross_shard::scatter_query

Scatter a cross-shard query into per-shard work items.

Returns a list of (shard_id, query_string) pairs that the coordinator should dispatch to individual shard workers.

pub fn scatter_query(query: &CrossShardQuery) -> Vec<(String, String)>;

Source line: 79.

cross_shard::gather_results

Gather partial results from shard workers into a unified cross-shard result.

Merges all successful entry IDs and tallies success/failure counts.

pub fn gather_results(query_id: &str, partials: Vec<ShardPartialResult>) -> CrossShardResult;

Source line: 90.

cross_shard::TransferState

State machine for an atomic cross-shard entry transfer.

#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum TransferState {
    /// Transfer has been initiated; no locks yet.
    Initiated,
    /// The entry is locked on the source shard (preventing mutations).
    SourceLocked,
    /// The entry has been written to the target shard.
    TargetWritten,
    /// The entry has been deleted from the source shard.
    SourceDeleted,
    /// Transfer completed successfully.
    Complete,
    /// Transfer was rolled back after a failure.
    RolledBack,
}

Source line: 123.

cross_shard::CrossShardTransfer

Tracks an atomic entry transfer between two shards.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CrossShardTransfer {
/// Unique transfer ID.

pub transfer_id: String,
/// The entry being transferred.

pub entry_id: String,
/// Source shard ID.

pub source_shard: String,
/// Target shard ID.

pub target_shard: String,
/// Current state of the transfer.

pub state: TransferState,
/// When the transfer was initiated.

pub initiated_at: chrono::DateTime<chrono::Utc>,
/// When the transfer completed or was rolled back.

#[serde(skip_serializing_if = "Option::is_none")]
pub finished_at: Option<chrono::DateTime<chrono::Utc>>
}

Source line: 145.

cross_shard::AtomicTransfer

Manages atomic cross-shard entry transfers.

Implements a two-phase state machine: Initiated -> SourceLocked -> TargetWritten -> SourceDeleted -> Complete

Any state before SourceDeleted can be rolled back.

pub struct AtomicTransfer {

}

Source line: 173.

cross_shard::AtomicTransfer::new

Create a new atomic transfer manager.

pub fn new() -> Self;

Source line: 180.

cross_shard::AtomicTransfer::initiate

Initiate a new cross-shard transfer.

pub fn initiate(
        &mut self,
        entry_id: &str,
        source_shard: &str,
        target_shard: &str,
    ) -> Result<CrossShardTransfer, ShardError>;

Source line: 188.

cross_shard::AtomicTransfer::advance

Advance a transfer to the next state.

Valid transitions:

Initiated -> SourceLocked
SourceLocked -> TargetWritten
TargetWritten -> SourceDeleted
SourceDeleted -> Complete

pub fn advance(&mut self, transfer_id: &str) -> Result<&CrossShardTransfer, ShardError>;

Source line: 250.

cross_shard::AtomicTransfer::rollback

Roll back a transfer.

Only possible from Initiated, SourceLocked, or TargetWritten. Once SourceDeleted is reached, rollback is not safe.

pub fn rollback(&mut self, transfer_id: &str) -> Result<&CrossShardTransfer, ShardError>;

Source line: 284.

cross_shard::AtomicTransfer::get

Get a transfer by ID.

pub fn get(&self, transfer_id: &str) -> Option<&CrossShardTransfer>;

Source line: 310.

cross_shard::AtomicTransfer::in_flight

List all in-flight transfers (not complete, not rolled back).

pub fn in_flight(&self) -> Vec<&CrossShardTransfer>;

Source line: 315.

cross_shard::AtomicTransfer::all_transfers

List all transfers.

pub fn all_transfers(&self) -> Vec<&CrossShardTransfer>;

Source line: 323.

Source provenance

Source: mars-shard/src/cross_shard.rs · SHA-256 a3c33ae417daed2d3670c3774518c74ed6c6dbf725a3f224fcee23f27d3e5783. Package overview.

mars-shard · cross_shard

On this page