etha.tensor_bus.client#

Tensor Bus Client (Host-side).

Host processes use TensorBusClient to register pairs and communicate with Agents.

Attributes#

Classes#

BatchHandler

Handler for batch tensor operations across multiple pairs.

TensorBusClient

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_round recv); see TensorBusClient.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=r this 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_round and 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:
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, Replicate and Partial are supported on the source side; Partial is collapsed to Replicate via an all-reduce on the source mesh sub-group before send. Partial on 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 matching sync_round recv — 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#
state_env: lmdb.Environment | None = None#
etha.tensor_bus.client.generate_semaphore_name(command_type: str, context_id: str) → str#
etha.tensor_bus.client.logger#