spinnman.spalloc package¶
Submodules¶
spinnman.spalloc.proxy_protocol module¶
-
class
spinnman.spalloc.proxy_protocol.
ProxyProtocol
[source]¶ Bases:
enum.IntEnum
Websocket binary frame type identifiers in the Spalloc Proxy protocol.
-
CLOSE
= 1¶ Message relating to closing a channel
-
ERROR
= 5¶ Message relating to an error when opening or closing a channel
-
MSG
= 2¶ Message sent on a channel
-
MSG_TO
= 4¶ Message sent on an unbound channel to a given board
-
OPEN
= 0¶ Message relating to opening a channel
-
OPEN_UNBOUND
= 3¶ Message relating to opening an unbound listen-only channel
-
spinnman.spalloc.session module¶
-
class
spinnman.spalloc.session.
Session
(service_url: str, username: str = None, password: str = None, token: str = None, session_credentials: Tuple[Dict[str, str], Dict[str, str]] = None)[source]¶ Bases:
object
Manages session credentials for the Spalloc client.
Warning
This class does not present a stable API for public consumption.
Parameters: -
delete
(url: str, timeout: int = 10, **kwargs) → requests.models.Response[source]¶ Do an HTTP
DELETE
in the session.Parameters: url (str) – Return type: Response Raises: ValueError – If the server rejects a request
-
get
(url: str, timeout: int = 10, **kwargs) → requests.models.Response[source]¶ Do an HTTP
GET
in the session.Parameters: Return type: Response
Raises: ValueError – If the server rejects a request
-
post
(url: str, jsonobj: dict, timeout: int = 10, **kwargs) → requests.models.Response[source]¶ Do an HTTP
POST
in the session.Parameters: Return type: Response
Raises: ValueError – If the server rejects a request
-
put
(url: str, data: str, timeout: int = 10, **kwargs) → requests.models.Response[source]¶ Do an HTTP
PUT
in the session. Puts plain text OR JSON!Parameters: Return type: Response
Raises: ValueError – If the server rejects a request
-
renew
() → dict[source]¶ Renews the session, logging the user into it so that state modification operations can be performed.
Returns: Description of the root of the service, without CSRF data Return type: dict Raises: SpallocException – If the session cannot be renewed.
-
spinnman.spalloc.spalloc_boot_connection module¶
API of the client for the Spalloc web service.
-
class
spinnman.spalloc.spalloc_boot_connection.
SpallocBootConnection
(remote_host=None)[source]¶ Bases:
spinnman.connections.udp_packet_connections.BootConnection
,spinnman.spalloc.SpallocProxiedConnection
The socket interface supported by proxied boot sockets. The socket will always be talking to the root board of a job. This emulates a BootConnection.
Parameters: remote_host (str) – The remote host name or IP address to send packets to. If not specified, the socket will be available for listening only, and will throw and exception if used for sending Raises: SpinnmanIOException – If there is an error setting up the communication channel -
receive_boot_message
(timeout=None) → spinnman.messages.spinnaker_boot.SpinnakerBootMessage[source]¶ Receives a boot message from this connection. Blocks until a message has been received, or a timeout occurs.
Parameters: timeout (int) – The time in seconds to wait for the message to arrive; if not specified, will wait forever, or until the connection is closed.
Returns: a boot message
Return type: Raises: - SpinnmanIOException – If there is an error receiving the message
- SpinnmanTimeoutException – If there is a timeout before a message is received
- SpinnmanInvalidPacketException – If the received packet is not a valid SpiNNaker boot message
- SpinnmanInvalidParameterException – If one of the fields of the SpiNNaker boot message is invalid
-
send_boot_message
(boot_message: spinnman.messages.spinnaker_boot.SpinnakerBootMessage)[source]¶ Sends a SpiNNaker boot message using this connection.
Parameters: boot_message (SpinnakerBootMessage) – The message to be sent Raises: SpinnmanIOException – If there is an error sending the message
-
spinnman.spalloc.spalloc_scp_connection module¶
-
class
spinnman.spalloc.spalloc_scp_connection.
SpallocSCPConnection
(x, y)[source]¶ Bases:
spinnman.connections.udp_packet_connections.SCAMPConnection
,spinnman.spalloc.SpallocProxiedConnection
The socket interface supported by proxied sockets. The socket will always be talking to a specific board. This emulates a
SCAMPConnection
.-
get_scp_data
(scp_request: spinnman.messages.scp.abstract_messages.AbstractSCPRequest, x=None, y=None) → bytes[source]¶ Returns the data of an SCP request as it would be sent down this connection.
Parameters:
-
receive_scp_response
(timeout=1.0) → Tuple[spinnman.messages.scp.enums.SCPResult, int, bytes, int][source]¶ Receives an SCP response from this connection. Blocks until a message has been received, or a timeout occurs.
Parameters: timeout (int) – The time in seconds to wait for the message to arrive; if not specified, will wait forever, or until the connection is closed
Returns: The SCP result, the sequence number, the data of the response and the offset at which the data starts (i.e., where the SDP header starts).
Return type: Raises: - SpinnmanIOException – If there is an error receiving the message
- SpinnmanTimeoutException – If there is a timeout before a message is received
-
receive_sdp_message
(timeout=None) → spinnman.messages.sdp.SDPMessage[source]¶ Receives an SDP message from this connection. Blocks until the message has been received, or a timeout occurs.
Parameters: timeout (int) – The time in seconds to wait for the message to arrive; if not specified, will wait forever, or until the connection is closed.
Returns: The received SDP message
Return type: Raises: - SpinnmanIOException – If there is an error receiving the message
- SpinnmanTimeoutException – If there is a timeout before a message is received
- SpinnmanInvalidPacketException – If the received packet is not a valid SDP message
- SpinnmanInvalidParameterException – If one of the fields of the SDP message is invalid
-
send_scp_request
(scp_request: spinnman.messages.scp.abstract_messages.AbstractSCPRequest)[source]¶ Sends an SCP request down this connection.
Messages must have the following properties:
- source_port is None or 7
- source_cpu is None or 31
- source_chip_x is None or 0
- source_chip_y is None or 0
tag in the message is optional; if not set, the default set in the constructor will be used. sequence in the message is optional; if not set, (sequence number last assigned + 1) % 65536 will be used
Parameters: scp_request (AbstractSCPRequest) – message packet to send Raises: SpinnmanIOException – If there is an error sending the message
-
send_sdp_message
(sdp_message: spinnman.messages.sdp.SDPMessage)[source]¶ Sends an SDP message down this connection.
Parameters: sdp_message (SDPMessage) – The SDP message to be sent Raises: SpinnmanIOException – If there is an error sending the message.
-
Module contents¶
The new Spalloc client implementation. This has the notable distinction of including a proxying system that allows creating a transceiver with access to the boards of a job despite the client being not within the same firewall/NAT security domain as the Spalloc-managed service.
The main class in here is SpallocClient
.
-
class
spinnman.spalloc.
AbstractSpallocClient
¶ Bases:
object
The API exported by the Spalloc Client.
-
create_job
(num_boards: int = 1, machine_name: str = None, keepalive: int = 45) → spinnman.spalloc.SpallocJob[source]¶ Create a job with a specified number of boards.
Parameters: Returns: A handle for monitoring and interacting with the job.
Return type:
-
create_job_board
(triad: Tuple[int, int, int] = None, physical: Tuple[int, int, int] = None, ip_address: str = None, machine_name: str = None, keepalive: int = 45) → spinnman.spalloc.SpallocJob[source]¶ Create a job with a specific board. At least one of
triad
,physical
andip_address
must be notNone
.Parameters: - triad (tuple(int,int,int)) – The logical coordinate of the board to request
- physical (tuple(int,int,int)) – The physical coordinate of the board to request
- ip_address (str) – The IP address of the board to request
- machine_name (str) – Which machine to run on? If omitted, the service’s machine tagged
with
default
will be used. - keepalive (int) – After how many seconds of no activity should a job become eligible for automatic pruning?
Returns: A handle for monitoring and interacting with the job.
Return type:
-
create_job_rect
(width: int, height: int, machine_name: str = None, keepalive: int = 45) → spinnman.spalloc.SpallocJob[source]¶ Create a job with a rectangle of boards.
Parameters: - width (int) – The width of rectangle to request
- height (int) – The height of rectangle to request
- machine_name (str) – Which machine to run on? If omitted, the service’s machine tagged
with
default
will be used. - keepalive (int) – After how many seconds of no activity should a job become eligible for automatic pruning?
Returns: A handle for monitoring and interacting with the job.
Return type:
-
list_jobs
(deleted: bool = False) → Iterable[spinnman.spalloc.SpallocJob][source]¶ Get the jobs known to the server.
Parameters: deleted (bool) – Whether to include deleted jobs. Returns: The jobs known to the server. Return type: Iterable(SpallocJob)
-
list_machines
() → Dict[str, spinnman.spalloc.SpallocMachine][source]¶ Get the machines supported by the server.
Returns: Mapping from machine names to handles for working with a machine. Return type: dict(str,SpallocMachine)
-
-
spinnman.spalloc.
is_server_address
(address: str, additional_schemes: Iterable[str] = ()) → bool¶ Test if the given address is a likely Spalloc server URL.
Parameters: Return type:
-
class
spinnman.spalloc.
SpallocClient
(service_url, username=None, password=None, bearer_token=None, group=None, collab=None, nmpi_job=None, nmpi_user=None)¶ Bases:
spinn_utilities.abstract_context_manager.AbstractContextManager
,spinnman.spalloc.AbstractSpallocClient
Basic client library for talking to new Spalloc.
Parameters: - service_url (str) – The reference to the service.
May have username and password supplied as part of the network
location; if so, the
username
andpassword
arguments must beNone
. Ifusername
andpassword
are not given, not even within the URL, thebearer_token
must be notNone
. - username (str) – The user name to use
- password (str) – The password to use
- bearer_token (str) – The bearer token to use
-
create_job
(num_boards=1, machine_name=None, keepalive=45)[source]¶ Create a job with a specified number of boards.
Parameters: Returns: A handle for monitoring and interacting with the job.
Return type:
-
create_job_board
(triad=None, physical=None, ip_address=None, machine_name=None, keepalive=45)[source]¶ Create a job with a specific board. At least one of
triad
,physical
andip_address
must be notNone
.Parameters: - triad (tuple(int,int,int)) – The logical coordinate of the board to request
- physical (tuple(int,int,int)) – The physical coordinate of the board to request
- ip_address (str) – The IP address of the board to request
- machine_name (str) – Which machine to run on? If omitted, the service’s machine tagged
with
default
will be used. - keepalive (int) – After how many seconds of no activity should a job become eligible for automatic pruning?
Returns: A handle for monitoring and interacting with the job.
Return type:
-
create_job_rect
(width, height, machine_name=None, keepalive=45)[source]¶ Create a job with a rectangle of boards.
Parameters: - width (int) – The width of rectangle to request
- height (int) – The height of rectangle to request
- machine_name (str) – Which machine to run on? If omitted, the service’s machine tagged
with
default
will be used. - keepalive (int) – After how many seconds of no activity should a job become eligible for automatic pruning?
Returns: A handle for monitoring and interacting with the job.
Return type:
-
list_jobs
(deleted=False)[source]¶ Get the jobs known to the server.
Parameters: deleted (bool) – Whether to include deleted jobs. Returns: The jobs known to the server. Return type: Iterable(SpallocJob)
-
list_machines
()[source]¶ Get the machines supported by the server.
Returns: Mapping from machine names to handles for working with a machine. Return type: dict(str,SpallocMachine)
-
static
open_job_from_database
(conn: sqlite3.Cursor) → spinnman.spalloc.SpallocJob[source]¶ Create a job from the description in the attached database. This is intended to allow for access to the job’s allocated resources from visualisers and other third party code participating in the SpiNNaker Tools Notification Protocol.
Note
The job is not verified to exist and be running. The session credentials may have expired; if so, the job will be unable to regenerate them.
Parameters: conn (Cursor) – The database cursor to retrieve the job details from. Assumes the presence of a proxy_configuration
table withkind
,name
andvalue
columns.Returns: The job handle, or None
if the records in the database are absent or incomplete.Return type: SpallocJob
-
version
¶
- service_url (str) – The reference to the service.
May have username and password supplied as part of the network
location; if so, the
-
class
spinnman.spalloc.
SpallocJob
¶ Bases:
object
Represents a job in Spalloc.
Don’t make this yourself. Use
SpallocClient
instead.-
connect_for_booting
() → spinnman.spalloc.spalloc_boot_connection.SpallocBootConnection[source]¶ Open a connection to a job’s allocation so it can be booted.
Returns: a boot connection Return type: SpallocBootConnection
-
connect_to_board
(x: int, y: int, port: int = 17893) → spinnman.spalloc.spalloc_scp_connection.SpallocSCPConnection[source]¶ Open a connection to a particular board in the job.
Parameters: Returns: A connection that talks to the board.
Return type:
-
create_transceiver
() → spinnman.transceiver.Transceiver[source]¶ Create a transceiver that will talk to this job. The transceiver will only be configured to talk to the SCP ports of the boards of the job.
Return type: Transceiver
-
destroy
(reason: str = 'finished')[source]¶ Destroy the job.
Parameters: reason (str) – Why the job is being destroyed.
-
get_connections
() → Dict[Tuple[int, int], str][source]¶ Get the mapping from board coordinates to IP addresses.
Returns: (x,y)->IP mapping, or None
if not allocatedReturn type: dict(tuple(int,int), str) or None
-
get_root_host
() → str[source]¶ Get the IP address for talking to the machine.
Returns: The IP address, or None
if not allocated.Return type: str or None
-
get_state
() → spinnman.spalloc.SpallocState[source]¶ Get the current state of the machine.
Return type: SpallocState
-
launch_keepalive_task
(period: int = 30) → spinn_utilities.abstract_context_manager.AbstractContextManager[source]¶ Starts a periodic task to keep a job alive.
Parameters: - job (SpallocJob) – The job to keep alive
- period (int) – How often to send a keepalive message (in seconds)
Returns: Some kind of closable task handle; closing it terminates the task. Destroying the job will also terminate the task.
-
open_eieio_connection
(x: int, y: int) → spinnman.spalloc.SpallocEIEIOConnection[source]¶ Open an EIEIO connection to a specific board in a job.
Parameters: Returns: an EIEIO connection with a board address bound
Return type:
-
open_eieio_listener_connection
() → spinnman.spalloc.SpallocEIEIOListener[source]¶ Open a listening EIEIO connection to the job’s boards. Messages cannot be sent on this connection unless you say which board to send to, but they can be received from all boards. You can also get the server side connection information so you can program that into a tag.
Returns: an EIEIO connection with no board address bound Return type: SpallocEIEIOListener
-
open_udp_listener_connection
() → spinnman.connections.udp_packet_connections.UDPConnection[source]¶ Open a listening UDP connection to the job’s boards. Messages cannot be sent on this connection unless you say which board to send to, but they can be received from all boards. You can also get the server side connection information so you can program that into a tag.
Returns: a UDP connection with no board address bound Return type: UDPConnection
-
wait_for_state_change
(old_state: spinnman.spalloc.SpallocState) → spinnman.spalloc.SpallocState[source]¶ Wait until the allocation is not in the given old state.
Parameters: old_state (SpallocState) – The state that we are looking to change out of. Returns: The state that the allocation is now in. Note
If the machine gets destroyed, this will not wait for it.
Return type: SpallocState
-
wait_until_ready
()[source]¶ Wait until the allocation is in the
READY
state.Raises: Exception – If the allocation is destroyed
-
where_is_machine
(x: int, y: int) → Tuple[int, int, int][source]¶ Get the physical coordinates of the board hosting the given chip.
Parameters: Returns: physical board coordinates (cabinet, frame, board), or
None
if there are no boards currently allocated to the job or the chip lies outside the allocation.Return type:
-
-
class
spinnman.spalloc.
SpallocMachine
¶ Bases:
object
Represents a Spalloc-controlled machine.
Don’t make this yourself. Use
SpallocClient
instead.-
dead_boards
¶ The dead or out-of-service boards of the machine.
-
dead_links
¶ The dead or out-of-service links of the machine.
-
height
¶ The height of the machine, in boards.
-
name
¶ The name of the machine.
The tags of the machine.
-
width
¶ The width of the machine, in boards.
-
-
class
spinnman.spalloc.
SpallocProxiedConnection
¶ Bases:
spinnman.connections.abstract_classes.Listenable
Base class for connections proxied via Spalloc.
-
receive
(timeout=None) → bytes[source]¶ Receive a message on an open socket. Will block until a message is received.
Parameters: timeout (int or float or None) – How long to wait for a message to be received before timing out. If None, will wait indefinitely (or until the connection is closed). Returns: The received message. Raises: SpinnmanTimeoutException – If a timeout happens
-
-
class
spinnman.spalloc.
SpallocEIEIOConnection
(local_host=None, local_port=None, remote_host=None, remote_port=None)¶ Bases:
spinnman.connections.udp_packet_connections.EIEIOConnection
,spinnman.spalloc.SpallocProxiedConnection
The socket interface supported by proxied EIEIO connected sockets. This emulates an
EIEOConnection
opened with a remote address specified.Parameters: - local_host (str) – The local host name or IP address to bind to. If not specified defaults to bind to all interfaces, unless remote_host is specified, in which case binding is done to the IP address that will be used to send packets
- local_port (int) – The local port to bind to, between 1025 and 65535. If not specified, defaults to a random unused local port
- remote_host (str) – The remote host name or IP address to send packets to. If not specified, the socket will be available for listening only, and will throw and exception if used for sending
- remote_port (int) – The remote port to send packets to. If remote_host is None, this is ignored. If remote_host is specified specified, this must also be specified for the connection to allow sending
Raises: SpinnmanIOException – If there is an error setting up the communication channel
-
receive_eieio_message
(timeout=None)[source]¶ Receives an EIEIO message from this connection. Blocks until a message has been received, or a timeout occurs.
Parameters: timeout (int) – The time in seconds to wait for the message to arrive; if not specified, will wait forever, or until the connection is closed
Returns: an EIEIO message
Return type: Raises: - SpinnmanIOException – If there is an error receiving the message.
- SpinnmanTimeoutException – If there is a timeout before a message is received.
- SpinnmanInvalidPacketException – If the received packet is not a valid EIEIO message.
- SpinnmanInvalidParameterException – If one of the fields of the EIEIO message is invalid.
-
send_eieio_message
(eieio_message)[source]¶ Sends an EIEIO message down this connection.
Parameters: eieio_message (AbstractEIEIOMessage) – The EIEIO message to be sent Raises: SpinnmanIOException – If there is an error sending the message
-
send_eieio_message_to_core
(eieio_message: spinnman.messages.eieio.AbstractEIEIOMessage, x: int, y: int, p: int)[source]¶
-
update_tag
(tag: int, do_receive: bool = True)[source]¶ Update the given tag on the connected Ethernet-enabled chip to send messages to this connection.
Parameters: Raises: - SpinnmanTimeoutException – If the message isn’t handled within a reasonable timeout.
- SpinnmanUnexpectedResponseCodeException – If the message is rejected by SpiNNaker/SCAMP.
-
class
spinnman.spalloc.
SpallocEIEIOListener
(local_host=None, local_port=None, remote_host=None, remote_port=None)¶ Bases:
spinnman.connections.udp_packet_connections.EIEIOConnection
,spinnman.spalloc.SpallocProxiedConnection
The socket interface supported by proxied EIEIO listener sockets. This emulates an
EIEOConnection
opened with no address specified.Parameters: - local_host (str) – The local host name or IP address to bind to. If not specified defaults to bind to all interfaces, unless remote_host is specified, in which case binding is done to the IP address that will be used to send packets
- local_port (int) – The local port to bind to, between 1025 and 65535. If not specified, defaults to a random unused local port
- remote_host (str) – The remote host name or IP address to send packets to. If not specified, the socket will be available for listening only, and will throw and exception if used for sending
- remote_port (int) – The remote port to send packets to. If remote_host is None, this is ignored. If remote_host is specified specified, this must also be specified for the connection to allow sending
Raises: SpinnmanIOException – If there is an error setting up the communication channel
-
local_ip_address
¶ The IP address on the server to which the connection is bound.
Returns: The IP address as a dotted string, e.g., 0.0.0.0 Return type: str
-
local_port
¶ The port on the server to which the connection is bound.
Returns: The local port number Return type: int
-
receive_eieio_message
(timeout=None)[source]¶ Receives an EIEIO message from this connection. Blocks until a message has been received, or a timeout occurs.
Parameters: timeout (int) – The time in seconds to wait for the message to arrive; if not specified, will wait forever, or until the connection is closed
Returns: an EIEIO message
Return type: Raises: - SpinnmanIOException – If there is an error receiving the message.
- SpinnmanTimeoutException – If there is a timeout before a message is received.
- SpinnmanInvalidPacketException – If the received packet is not a valid EIEIO message.
- SpinnmanInvalidParameterException – If one of the fields of the EIEIO message is invalid.
-
send
(data)[source]¶ Send a message on an open socket.
Parameters: data – The message to send. Note
This class does not allow sending.
-
send_eieio_message_to_core
(eieio_message: spinnman.messages.eieio.AbstractEIEIOMessage, x: int, y: int, p: int, ip_address: str)[source]¶ Send an EIEIO message (one way) to a given core.
Parameters: - eieio_message (AbstractEIEIOMessage) – The message to send.
- x (int) – The X coordinate of the core to send to.
- y (int) – The Y coordinate of the core to send to.
- p (int) – The ID of the core to send to.
- ip_address (str) – The IP address of the Ethernet-enabled chip to route the message via.
-
send_to
(data: bytes, address: Tuple[str, int])[source]¶ Send a message on an open socket.
Parameters:
-
send_to_chip
(message: bytes, x: int, y: int, port: int = 17893)[source]¶ Send a message on an open socket to a particular board.
Parameters: - message (bytes) – The message to send.
- x (int) – The X coordinate of the Ethernet-enabled chip to send the message to.
- y (int) – The Y coordinate of the Ethernet-enabled chip to send the message to.
- port (int) – The UDP port on the Ethernet-enabled chip to send the message to. Defaults to the SCP port.
-
update_tag
(x: int, y: int, tag: int, do_receive: bool = True)[source]¶ Update the given tag on the given Ethernet-enabled chip to send messages to this connection.
Parameters: Raises: - SpinnmanTimeoutException – If the message isn’t handled within a reasonable timeout.
- SpinnmanUnexpectedResponseCodeException – If the message is rejected by SpiNNaker/SCAMP.
-
class
spinnman.spalloc.
SpallocState
¶ Bases:
enum.IntEnum
The possible states of a Spalloc Job.
Jobs start as QUEUED, then move to POWER once they’ve been allocated. Once the job’s boards have been switched on and the hardware stabilised, the job moves to state READY. (It goes back to POWER if you tell it to switch off or on; this is not recommended.) Finally, it goes to DESTROYED once the job is completed in any way.
The UNKNOWN state is used when something odd is going on. It should normally be ignored.
-
DESTROYED
= 4¶
-
POWER
= 2¶
-
QUEUED
= 1¶
-
READY
= 3¶
-
UNKNOWN
= 0¶
-