etha.tensor_bus.commands#

Command (Host to Tensor Bus) Definitions and State Structures.

Attributes#

Classes#

BaseCommand

Base class for all Tensor Bus commands.

CleanupBatch

Cleanup a batch's state in the agent.

InitPair

Init a Device Mesh + Placement to Device Mesh + Placement pair.

QueryStatus

Query status for a batch.

RegisterTensors

Register multiple tensors for zero-copy sharing between processes.

Transfer

Transfer tensor command for a specific batch.

Functions#

command_error_key(→ bytes)

LMDB key used to report a command failure to its waiting client.

command_result_key(→ bytes)

LMDB key used to return a scalar result (e.g. batch generation).

Module Contents#

class etha.tensor_bus.commands.BaseCommand#

Bases: msgspec.Struct

Base class for all Tensor Bus commands.

Features: - Auto-tagging: Uses class name as type tag - Common timestamp field for all commands - Optional semaphore for completion notification

semaphore_name: str | None = None#
timestamp: float | None = None#
class etha.tensor_bus.commands.CleanupBatch#

Bases: BaseCommand

Cleanup a batch’s state in the agent.

generation is the registration token the client received. 0 means unspecified (always matches). A stale sibling handler after batch-id reuse carries an older generation and is ignored.

batch_id: str#
generation: int = 0#
class etha.tensor_bus.commands.InitPair#

Bases: BaseCommand

Init a Device Mesh + Placement to Device Mesh + Placement pair.

Parameters:
  • pair_name – Unique identifier for this pair (e.g., “obs”, “action”)

  • local_name – Name of local peer (e.g., “inference”, “training”)

  • expected_world_size – Number of ranks for local peer

  • remote_name – Name of remote peer (explicit pairing)

  • mesh_shape_payload – Serialized mesh shape tuple as memoryview

  • placements_payload – Serialized placements tuple as memoryview

expected_world_size: int#
local_name: str#
mesh_shape_payload: memoryview | None = None#
pair_name: str#
placements_payload: memoryview | None = None#
remote_name: str#
class etha.tensor_bus.commands.QueryStatus#

Bases: BaseCommand

Query status for a batch.

batch_id: str#
generation: int = 0#
state_name: str#
class etha.tensor_bus.commands.RegisterTensors#

Bases: BaseCommand

Register multiple tensors for zero-copy sharing between processes.

Creates a new batch with a unique batch_id. Multiple tensors can be registered across different pairs in a single batch, enabling efficient cross-pair execution via flattened chunks/buckets.

role is required when a pair of the batch is dual-endpoint (colocated): both sides of the pair register into the same batch on the same agent, and the role names which side this registration’s tensors belong to. It must match one of the pair’s peer names. Split pairs leave it None.

batch_id: str#
bucket_size: int | None = None#
role: str | None = None#
tensors: list[tuple[str, memoryview]]#
class etha.tensor_bus.commands.Transfer#

Bases: BaseCommand

Transfer tensor command for a specific batch.

On a dual-endpoint (colocated) batch the agent hosts both sides of the pair, so the command alone cannot tell which side issued it: role names the issuing client’s side (its init_pair local_name). send from role R executes the R→other direction; recv from role R executes the other→R direction. Split (single-role) agents leave it None.

sync_round identifies the weight-sync round within one batch: a direction-round executes exactly once, only after BOTH roles’ commands for that round arrived (source-ready and dest-ready), and re-issues of an already-executed or older round are acknowledged without re-execution. Monotonic per (batch, direction); round 0 is the first sync. Split batches ignore it.

batch_id: str#
generation: int = 0#
role: str | None = None#
sync_round: int = 0#
transfer_type: Literal['send', 'recv']#
etha.tensor_bus.commands.command_error_key(semaphore_name: str) → bytes#

LMDB key used to report a command failure to its waiting client.

etha.tensor_bus.commands.command_result_key(semaphore_name: str) → bytes#

LMDB key used to return a scalar result (e.g. batch generation).

etha.tensor_bus.commands.Message#