Grid

class Grid[source]

Bases: ABC

Abstract base class Grid to send/receive messages.

Methods

create_message(content, message_type, ...[, ttl])

Create a new message with specified parameters.

get_node_ids()

Get node IDs.

pull_messages(message_ids)

Pull messages based on message IDs.

push_messages(messages)

Push messages to specified node IDs.

send_and_receive(messages, *[, timeout])

Push messages to specified node IDs and pull the reply messages.

set_run(run_id)

Request a run to the SuperLink with a given run_id.

Attributes

run

Run information.
abstract create_message(content: RecordDict, message_type: str, dst_node_id: int, group_id: str, ttl: float | None = None) → Message[source]

Create a new message with specified parameters.

This method constructs a new Message with given content and metadata. The run_id and src_node_id will be set automatically.

Parameters:

  • content (RecordDict) – The content for the new message. This holds records that are to be sent to the destination node.

  • message_type (str) – The type of the message, defining the action to be executed on the receiving end.

  • dst_node_id (int) – The ID of the destination node to which the message is being sent.

  • group_id (str) – The ID of the group to which this message is associated. In some settings, this is used as the federated learning round.

  • ttl (Optional[float] (default: None)) – Time-to-live for the round trip of this message, i.e., the time from sending this message to receiving a reply. It specifies in seconds the duration for which the message and its potential reply are considered valid. If unset, the default TTL (i.e., common.DEFAULT_TTL) will be used.

Returns:

message – A new Message instance with the specified content and metadata.

Return type:

Message

abstract get_node_ids() → Iterable[int][source]

Get node IDs.

abstract pull_messages(message_ids: Iterable[str]) → Iterable[Message][source]

Pull messages based on message IDs.

This method is used to collect messages from the SuperLink that correspond to a set of given message IDs.

Parameters:

message_ids (Iterable[str]) – An iterable of message IDs for which reply messages are to be retrieved.

Returns:

messages – An iterable of messages received.

Return type:

Iterable[Message]

abstract push_messages(messages: Iterable[Message]) → Iterable[str][source]

Push messages to specified node IDs.

This method takes an iterable of messages and sends each message to the node specified in dst_node_id.

Parameters:

messages (Iterable[Message]) – An iterable of messages to be sent.

Returns:

message_ids – An iterable of IDs for the messages that were sent, which can be used to pull replies.

Return type:

Iterable[str]

abstract property run: Run

Run information.

abstract send_and_receive(messages: Iterable[Message], *, timeout: float | None = None) → Iterable[Message][source]

Push messages to specified node IDs and pull the reply messages.

This method sends a list of messages to their destination node IDs and then waits for the replies. It continues to pull replies until either all replies are received or the specified timeout duration is exceeded.

Parameters:

  • messages (Iterable[Message]) – An iterable of messages to be sent.

  • timeout (Optional[float] (default: None)) – The timeout duration in seconds. If specified, the method will wait for replies for this duration. If None, there is no time limit and the method will wait until replies for all messages are received.

Returns:

replies – An iterable of reply messages received from the SuperLink.

Return type:

Iterable[Message]

Notes

This method uses push_messages to send the messages and pull_messages to collect the replies. If timeout is set, the method may not return replies for all sent messages. A message remains valid until its TTL, which is not affected by timeout.

abstract set_run(run_id: int) → None[source]

Request a run to the SuperLink with a given run_id.

If a Run with the specified run_id exists, a local Run object will be created. It enables further functionality in the grid, such as sending ``Message``s.

Parameters:

run_id (int) – The run_id of the Run this Grid object operates in.