Struct PhysicalWorker 

pub struct PhysicalWorker { /* private fields */ }

PhysicalWorker executes transfer operations using a local TransferManager.

This is the fundamental worker type that directly owns a TransferManager and layout handles for executing data transfers. It implements the Worker and WorkerTransfers traits for single-worker scenarios.

Builder fields

Field	Required	Description
manager	yes	TransferManager that executes actual data movement
g1_handle	no	GPU KV cache layout handle (for GPU transfers)
g2_handle	no	Host/pinned cache layout handle (for host transfers)
g3_handle	no	Disk cache layout handle (for disk-tier transfers)
rank	no	Worker rank for object-key prefixing in SPMD setups
object_client	no	Object storage client for G4 tier (S3, etc.)

Execution State vs Coordination State

PhysicalWorker maintains execution state – the handles and manager needed to actually perform RDMA/local transfers. This is distinct from coordination state which the leader tracks in CoordinatedWorker.

When a leader wraps a PhysicalWorker in a CoordinatedWorker:

• PhysicalWorker: owns handles for TransferManager execution
• CoordinatedWorker: tracks the same handles for leader coordination

This duplication is intentional – PhysicalWorker needs handles to execute, and CoordinatedWorker provides a uniform API regardless of whether the inner worker is local (PhysicalWorker) or remote (VeloWorkerClient).

Typical lifecycle

1. Created via PhysicalWorker::builder() during deferred initialization
2. Wrapped by VeloWorkerService to expose RPC handlers
3. Wrapped by CoordinatedWorker for leader coordination
4. Used as a building block in parallel workers (e.g., SpmdParallelWorkers)

Implementations

impl PhysicalWorker

pub fn builder() -> PhysicalWorkerBuilder

Create a new builder for PhysicalWorker.

Example

let worker = PhysicalWorker::builder()
    .manager(manager)
    .g1_handle(g1_handle)
    .g2_handle(g2_handle)
    .g3_handle(g3_handle)
    .build();

pub fn rank(&self) -> Option<usize>

Get the worker rank (if set).

pub fn object_client(&self) -> Option<&Arc<dyn ObjectBlockOps>>

Get the object storage client (if set).

pub fn g1_handle(&self) -> Option<LayoutHandle>

Get the G1 layout handle (if set).

pub fn g2_handle(&self) -> Option<LayoutHandle>

Get the G2 layout handle (if set).

pub fn g3_handle(&self) -> Option<LayoutHandle>

Get the G3 layout handle (if set).

pub fn transfer_manager(&self) -> &TransferManager

Get a reference to the TransferManager.

pub fn resolve_layout( &self, logical: LogicalLayoutHandle, ) -> Result<PhysicalLayout>

Resolve a logical layout handle to a physical layout.

Arguments

• logical - The logical layout handle (G1, G2, G3)

Returns

The physical layout for the given logical handle, or an error if not found.

pub fn create_bounce_buffer( &self, handle: LayoutHandle, block_ids: Vec<BlockId>, ) -> Result<BounceBuffer>

Create a bounce buffer specification from a layout handle and block IDs.

pub fn export_metadata(&self) -> Result<SerializedLayout>

Export serialized layout metadata with proper logical type mappings.

This exports layouts with their logical types (G1, G2, G3) so that remote instances can correctly identify which handle corresponds to which tier during RDMA transfers.

pub fn import_metadata( &self, metadata: SerializedLayout, ) -> Result<Vec<LayoutHandle>>

Import serialized layout metadata into the transfer manager.

Trait Implementations

impl ObjectBlockOps for PhysicalWorker

fn has_blocks( &self, keys: Vec<SequenceHash>, ) -> BoxFuture<'static, Vec<(SequenceHash, Option<usize>)>>

Check if blocks exist in object storage.

fn put_blocks( &self, keys: Vec<SequenceHash>, src_layout: LogicalLayoutHandle, block_ids: Vec<BlockId>, ) -> BoxFuture<'static, Vec<Result<SequenceHash, SequenceHash>>>

Put blocks to object storage.

fn get_blocks( &self, keys: Vec<SequenceHash>, dst_layout: LogicalLayoutHandle, block_ids: Vec<BlockId>, ) -> BoxFuture<'static, Vec<Result<SequenceHash, SequenceHash>>>

Get blocks from object storage.

fn put_blocks_with_layout( &self, keys: Vec<SequenceHash>, _layout: PhysicalLayout, _block_ids: Vec<BlockId>, ) -> BoxFuture<'static, Vec<Result<SequenceHash, SequenceHash>>>

Put blocks to object storage using a resolved physical layout.

fn get_blocks_with_layout( &self, keys: Vec<SequenceHash>, _layout: PhysicalLayout, _block_ids: Vec<BlockId>, ) -> BoxFuture<'static, Vec<Result<SequenceHash, SequenceHash>>>

Get blocks from object storage into a resolved physical layout.

impl Worker for PhysicalWorker

fn g1_handle(&self) -> Option<LayoutHandle>

Get the G1 layout handle for this worker (if configured).

fn g2_handle(&self) -> Option<LayoutHandle>

Get the G2 layout handle for this worker (if configured).

fn g3_handle(&self) -> Option<LayoutHandle>

Get the G3 layout handle for this worker (if configured).

fn export_metadata(&self) -> Result<SerializedLayoutResponse>

Export the local metadata for this worker.

fn import_metadata( &self, metadata: SerializedLayout, ) -> Result<ImportMetadataResponse>

Import the remote metadata for this worker.

impl WorkerTransfers for PhysicalWorker

fn execute_local_transfer( &self, src: LogicalLayoutHandle, dst: LogicalLayoutHandle, src_block_ids: Arc<[BlockId]>, dst_block_ids: Arc<[BlockId]>, options: TransferOptions, ) -> Result<TransferCompleteNotification>

Execute a local transfer between two logical layouts.

fn execute_remote_onboard( &self, src: RemoteDescriptor, dst: LogicalLayoutHandle, dst_block_ids: Arc<[BlockId]>, options: TransferOptions, ) -> Result<TransferCompleteNotification>

Execute a remote transfer from a remote layout to a local logical layout.

fn execute_remote_offload( &self, src: LogicalLayoutHandle, src_block_ids: Arc<[BlockId]>, dst: RemoteDescriptor, _options: TransferOptions, ) -> Result<TransferCompleteNotification>

Execute a remote offload from a local logical layout to a remote descriptor.

fn connect_remote( &self, instance_id: InstanceId, metadata: Vec<SerializedLayout>, ) -> Result<ConnectRemoteResponse>

Connect to a remote instance by importing its metadata and storing handle mappings.

fn has_remote_metadata(&self, instance_id: InstanceId) -> bool

Check if remote metadata has been imported for an instance.

fn execute_remote_onboard_for_instance( &self, instance_id: InstanceId, remote_logical_type: LogicalLayoutHandle, src_block_ids: Vec<BlockId>, dst: LogicalLayoutHandle, dst_block_ids: Arc<[BlockId]>, options: TransferOptions, ) -> Result<TransferCompleteNotification>

Execute a remote onboard transfer using stored handle mapping.