etha.tensor_bus.client#
Tensor Bus Client (Host-side).
Host processes use TensorBusClient to register pairs and communicate with Agents.
Attributes#
Classes#
Handler for batch tensor operations across multiple pairs. |
|
Host-side Tensor Bus Client. |
Functions#
|
Module Contents#
- class etha.tensor_bus.client.BatchHandler(client: TensorBusClient, batch_id: str, pair_names: list[str], generation: int = 0)#
Handler for batch tensor operations across multiple pairs.
Initialize BatchHandler.
- Parameters:
client – TensorBusClient instance
batch_id – Unique identifier for this batch
pair_names – List of pair names managed by this handler
- close(blocking: bool = True, timeout: float = 30.0)#
Explicitly cleanup batch state in agent.
Sends a CleanupBatch command to free resources associated with this batch. After calling close(), this handler should not be used.
- Parameters:
blocking – If True, block until cleanup completes
timeout – Timeout in seconds
- query_transfer_request(direction: tuple[str, str], blocking: bool = True, timeout: float = 30.0, sync_round: int = 0) bool#
Has the (src -> dst) direction of this dual batch requested round r?
True once the agent saw the direction-round’s FIRST command — before it parks. A reactive recv issuer polls this (quiesce, then issue the matching
sync_roundrecv); seeTensorBusClient.query_transfer_request.
- query_transfer_signal(blocking: bool = True, timeout: float = 30.0, sync_round: int | None = None) bool#
Query transfer signal status for this batch.
- Parameters:
sync_round – dual-endpoint batches publish a VERSIONED completion (the last completed round id, monotonic). With
sync_round=rthis returns True once round r (or later) completed — a watcher cannot lose a pulse. Without it, the legacy boolean signal of split batches is returned.- Returns:
bool for the legacy signal / the round query; callers of the round query may also pass
sync_roundand treat the return as bool.
- transfer(transfer_type: Literal['send', 'recv'], blocking: bool = False, timeout: float = 30.0, role: str | None = None, sync_round: int = 0) posix_ipc.Semaphore#
Transfer all tensors in this batch atomically.
Sends a single Transfer command to execute all pairs in the batch simultaneously using flattened chunks/buckets for optimal performance.
- Parameters:
transfer_type – “send” or “recv”
blocking – If True, block until transfer completes
timeout – Timeout in seconds
role – Issuing side’s peer name — required on dual-endpoint (colocated) batches, where one agent hosts both sides; ignored on split (single-role) batches.
sync_round – Weight-sync round within this batch (dual batches). A direction-round executes once both roles’ commands for it arrived; older/duplicate rounds are acknowledged, not re-executed. Split batches ignore it.
- Returns:
Semaphore for operation completion
- batch_id#
- property client: TensorBusClient#
Get client from weak reference.
- Raises:
RuntimeError – If client has been garbage collected
- generation = 0#
- pair_names#
- class etha.tensor_bus.client.TensorBusClient(agent_rank: int, lmdb_command_queue_path: str | None = None, agent_state_lmdb_path: str | None = None, connection_timeout: float = 30.0)#
Host-side Tensor Bus Client.
Initialize TensorBusClient.
- Parameters:
lmdb_command_queue_path – Path to Agent’s CommandQueue LMDB
agent_state_lmdb_path – Path to Agent’s State LMDB
connection_timeout – Max time to wait for Agent connection (seconds)
- Raises:
ValueError – If agent_state_lmdb_path is not provided
ConnectionError – If Agent is not found or not responding
- close()#
Cleanup resources.
- init_pair(pair_name: str, local_name: str, remote_name: str, expected_world_size: int, device_mesh: torch.distributed.device_mesh.DeviceMesh | None = None, placements: tuple[torch.distributed.tensor.placement_types.Placement, Ellipsis] | None = None, blocking: bool = True, timeout: float = 30.0) None#
Register a pair for communication.
- Parameters:
pair_name – Unique identifier for this pair
local_name – Name of local peer
remote_name – Name of remote peer
expected_world_size – Number of ranks for local peer
device_mesh – Local device mesh configuration
placements – Local tensor placement strategy.
Shard,ReplicateandPartialare supported on the source side;Partialis collapsed toReplicatevia an all-reduce on the source mesh sub-group before send.Partialon the target side is rejected.
- Blocks until:
Agent registers to TCPStore
Remote peer registers
Pair is matched
- query_transfer_request(batch_id: str, direction: tuple[str, str], blocking: bool = True, timeout: float = 30.0, sync_round: int = 0, generation: int = 0) bool#
Has the (src -> dst) direction of a dual batch requested round r?
The agent publishes the request when the direction-round’s FIRST command arrives — before that command parks. True only when the published request id equals
sync_round: a later round must not satisfy an earlier recv. A reactive recv issuer (engine service) polls this, quiesces, and only then issues the matchingsync_roundrecv — the completion signal must never drive the START of a recv.
- query_transfer_signal(batch_id: str, blocking: bool = True, timeout: float = 30.0, sync_round: int | None = None, generation: int = 0) bool | int#
Legacy boolean signal (split) or versioned dual completion.
With
sync_round=r: returns True once the dual direction-round r (or any later round) completed — the agent publishes a monotonic round id, so a poll cannot miss a completed round it hasn’t seen. Without: the split batches’ boolean transfer signal.
- register_tensors(batch_id: str, tensors: list[tuple[torch.Tensor, str]], bucket_size: int | None = None, timeout: float = 30.0, role: str | None = None) BatchHandler#
Register multiple tensors across pairs.
This operation always blocks until registration completes, ensuring the returned BatchHandler is immediately usable.
- Parameters:
batch_id – Unique identifier for this batch (must be same on both send/recv sides)
tensors – list of (tensor, pair_name) tuples
bucket_size – optional bucket size in bytes for bucketization optimization
timeout – timeout in seconds
role – peer name of the registering side — required when a pair in this batch is dual-endpoint (colocated); both sides register into the same batch on the same agent and the role tells them apart. Split pairs leave it None.
- Returns:
BatchHandler for managing the registered tensors
- transfer(batch_id: str, transfer_type: Literal['send', 'recv'], blocking: bool = False, timeout: float = 30.0, role: str | None = None, sync_round: int = 0) posix_ipc.Semaphore#
- agent_rank#
- agent_state_lmdb_path = None#
- command_queue#
- state_db = None#
- etha.tensor_bus.client.logger#