Struct SessionHandle 

pub struct SessionHandle { /* private fields */ }

Unified handle for controlling remote sessions. Handle for controlling a remote session.

Created by attaching to a remote session. Provides methods to:

• Query and observe session state
• Issue control commands (trigger staging, release blocks)
• Transfer control bidirectionally (yield/acquire)
• Pull blocks via RDMA

Usage

// Attach to remote session
let mut handle = leader.attach_session(remote_id, session_id).await?;

// Wait for initial state
let state = handle.wait_for_ready().await?;

// Trigger staging if needed
if state.g3_pending > 0 {
    handle.trigger_staging().await?;
    handle.wait_for_ready().await?;
}

// Pull blocks via RDMA
let notification = handle.pull_blocks_rdma(&state.g2_blocks, &local_block_ids).await?;
notification.await?;

// Notify remote and detach
handle.mark_blocks_pulled(hashes).await?;
handle.detach().await?;

Implementations

impl SessionHandle

pub fn with_rdma_support( self, parallel_worker: Arc<dyn ParallelWorkers>, ) -> Self

Add RDMA support to this handle.

pub fn session_id(&self) -> SessionId

Get the session ID.

pub fn remote_instance(&self) -> InstanceId

Get the remote instance ID.

pub fn local_instance(&self) -> InstanceId

Get the local instance ID.

pub fn current_state(&self) -> SessionStateSnapshot

Get the current state snapshot (non-blocking).

pub fn phase(&self) -> SessionPhase

Get the current phase.

pub fn remote_control_role(&self) -> ControlRole

Get the current control role of the remote session.

pub fn has_changed(&self) -> bool

Check if state has changed since last read.

pub async fn wait_for_change(&mut self) -> Result<SessionStateSnapshot>

Wait for state to change.

pub async fn wait_for_ready(&mut self) -> Result<SessionStateSnapshot>

Wait for the session to reach Ready phase (all blocks in G2).

pub async fn wait_for_complete(&mut self) -> Result<SessionStateSnapshot>

Wait for the session to complete.

pub fn is_complete(&self) -> bool

Check if the session is complete.

pub fn is_ready(&self) -> bool

Check if the session is ready (all blocks in G2).

pub fn get_g2_blocks(&self) -> Vec<BlockInfo>

Get G2 blocks from current state.

pub fn g3_pending_count(&self) -> usize

Get count of G3 blocks pending staging.

pub fn ready_layer_range(&self) -> Option<Range<usize>>

Get the layer range that is ready for transfer.

Returns None if all layers are ready or layerwise tracking is not active. Returns Some(range) if only specific layers are ready.

pub async fn trigger_staging(&self) -> Result<()>

Trigger G3→G2 staging on the remote session.

Idempotent - no-op if already staging or staged.

pub async fn mark_blocks_pulled( &self, pulled_hashes: Vec<SequenceHash>, ) -> Result<()>

Notify remote that blocks have been pulled.

Call after successfully pulling blocks via RDMA.

pub async fn detach(self) -> Result<()>

Detach from the session.

Consumes the handle. The remote session will release remaining blocks.

pub async fn yield_control(&self) -> Result<()>

Yield control to the remote peer.

After yielding, this handle transitions to Neutral and the remote can acquire control if desired.

pub async fn acquire_control(&self) -> Result<()>

Attempt to acquire control from the remote peer.

Valid when remote is in Neutral state.

pub fn has_remote_metadata(&self) -> bool

Check if remote metadata has been imported.

pub async fn ensure_metadata_imported(&mut self) -> Result<()>

Ensure remote metadata is imported (lazy loading).

pub async fn pull_blocks_rdma( &mut self, blocks: &[BlockInfo], local_dst_block_ids: &[BlockId], ) -> Result<TransferCompleteNotification>

Pull blocks from remote G2 to local G2 via RDMA.

This method:

1. Ensures remote metadata is imported
2. Executes SPMD-aware transfer (worker N pulls from remote worker N)
3. Returns notification that completes when all transfers done

pub fn pull_blocks_rdma_explicit( &self, blocks: &[BlockInfo], local_dst_block_ids: &[BlockId], ) -> Result<TransferCompleteNotification>

Pull blocks with explicit metadata pre-import.

Caller must have already ensured metadata is imported.

pub async fn pull_blocks_rdma_with_options( &mut self, blocks: &[BlockInfo], local_dst_block_ids: &[BlockId], options: TransferOptions, ) -> Result<TransferCompleteNotification>

Pull blocks from remote G2 to local G2 via RDMA with transfer options.

This method allows specifying transfer options like layer range for layerwise transfer. Use this when you only want to pull specific layers.

Example

// Pull only layer 0
let notification = handle.pull_blocks_rdma_with_options(
    &state.g2_blocks,
    &local_block_ids,
    TransferOptions::builder().layer_range(0..1).build(),
).await?;
notification.await?;

pub fn pull_blocks_rdma_with_options_explicit( &self, blocks: &[BlockInfo], local_dst_block_ids: &[BlockId], options: TransferOptions, ) -> Result<TransferCompleteNotification>

Pull blocks with options and explicit metadata pre-import.

Caller must have already ensured metadata is imported.