Receive addresses

This library offers the ability to calculate reception hosts and ports (i.e., endpoints) for the scan types associated to the script under execution. This process yields SDP’s receive addresses.

Usage

The process of calculating and publishing receive addresses works as follows:

User invoke ProcessingBlock.generate_receive_addresses(). This requires users to provide at least a function argument, indicating the beam function for which receive addresses will be generated. This must be one of the allowed function values in the Beam SDP schema, part of the AssignedResources command:
```
# Request parameters
>>> num_hosts = 1

# Generate partial addresses
>>> partial_receive_addresses = pb.generate_receive_addresses("visibilities", num_hosts)
```
The returned object is of type PartialReceiveAddresses. It is partial in the sense that it has placeholders in the place of actual hostnames/IPs. It’s the user’s responsibility to acquire those separately. At least PartialReceiveAddresses.host_count hostnames/IPs should be needed. This number should match the requested number of hosts too from the previous step.
```
>>> isinstance(partial_receive_addresses, PartialReceiveAddresses)
True
>>> partial_receive_addresses.host_count
1
>>> partial_receive_addresses.host_count == num_hosts
True
```

Once hostnames/IPs are acquired, calling PartialReceiveAddresses.replace_hosts() yields a ReceiveAddresses object with actual hostnames/IPs.

>>> ips = ["1.1.1.1"]
>>> receive_addresses = partial_receive_addresses.replace_hosts(ips)
>>> isinstance(receive_addresses, ReceiveAddresses)
True

To set these as the processing block’s receive addresses users invoke ProcessingBlock.publish_receive_addresses().

# Register as this ProcessingBlock's receive addresses
>>> pb.publish_receive_addresses(receive_addresses)

# These can be read now from the SDP config DB
>>> for txn in config.txn():
...    pb_state = txn.processing_block.state(pb._pb_id).get()
...    recv_address_dict = pb_state.get("receive_addresses")
>>> recv_address_dict
{'target:a': {'vis0': {'function': 'visibilities', 'host': [[0, '1.1.1.1']], 'port': [[0, 21000], [2, 21001], [4, 21002], [6, 21003]]}}}

The ReceiveAddresses and PartialReceiveAddresses classes also have a :attr:~.ReceiveAddresses.allocations` attribute with the individual host/port allocation spans, which can be inspected (mostly useful for debugging and testing).

Allocation strategy

Hosts and ports are allocated for a Processing Block’s scan types using the following logic:

Users provide a number of hosts to allocate resources on. This number is always respected.

Each scan type allocates ports across all hosts as evenly as possible. Note that each scan type can have a different number of channels, therefore the port count for each scan type on each host will be different.

Within a scan type, only beams matching the given function are considered.

In a scan type ports are fully allocated to each beam in the order in which they are declared in the Execution Block.

For each beam, ports are fully allocated to each Spectral Window in ascending order according to their first channel ID.

When channels_per_port is different to 1 multiple channels are assigned to the same port. However grouping of channels onto a single port only takes place within a Spectral Window. In other words a port will never be assigned to channels from different Spectral Windows or Beams.