Preliminary SLC API¶
Helper functions / structures¶
-
slc.
SERIALIZER
¶ Namedtuple specifying serialization protocols.
Parameters: - protocol – Protocol name.
- version – Protocol version.
- dumps – Callable that performs the serialization. Use a partial to specify the function arguments.
- loads – Callable that performs the reverse serialization.
alias of
serializer
-
slc.
SER_PICKLE_HIGHEST
¶
-
slc.
SER_PICKLE_TEXT
¶
-
slc.
COMPRESSOR
¶ Namedtuple specifying compressors.
Parameters: - name – Compressor name.
- version – Compressor version.
- comp – Callable that performs the compression. Use a partial to specify the function arguments.
- decomp – Callable that performs the decompression.
alias of
compressor
-
slc.
COMP_ZLIB_DEFAULT
¶
-
slc.
COMP_ZLIB_MAX
¶
-
slc.
ALL
¶
-
slc.
INFINITE
¶
Communicator Class¶
-
class
slc.
Communicator
(self, secure=False, compress=None, serializer=slc.SER_BEST, buffer_cap=slc.INFINITE, timeout=30, retries=INFINITE, protocol="tcp")[source]¶ Builds a new communicator.
Parameters: - secure – Use encryption and authentication. This makes the messages readable only by the target and validates the authenticity of the sender.
- compress – Compression scheme to use. None deactivates compression. See slc.COMPRESSOR.
- serializer – Namedtuple representing the serialization protocol. See slc.SERIALIZER.
- buffer_cap – Maximum sending buffer capacity. Past this capacity, sending data will block. (TODO)
- timeout – Timeout in seconds before a connection attempt is considered failed.
- retries – Number of retries before a socket is considered disconnected. After this number of retries, subsequent operations on the communicator will raise an exception.
- protocol – Underlying protocol to use (‘tcp’, ‘udp’, ‘icmp’). Only ‘tcp’ is supported as of now.
-
advertise
(name)[source]¶ Advertise the current server on the network.
TODO: Add support for IPv6.
Parameters: name – Name to advertise.
-
connect
(self, port, host='127.0.0.1', timeout=INFINITE, source_address=ALL)[source]¶ Connect to a socket that prealably performed a listen().
Parameters: - port – Target port connect.
- host – Target host.
- timeout – Maximum time to wait. slc.INFINITE means blocking. 0 means non-blocking. Any strictly positive number means to wait for this maximum time in seconds to wait. An error is raised in the latter case if no data is received.
- source_address – Address on which to perform the connection. None means all available interfaces.
-
disconnect
(self, target=ALL, timeout=INFINITE)[source]¶ Disconnect target(s) from the communicator.
Parameters: - target – Target to disconnect. slc.ALL means disconnect all peers. A tuple (host, port) means to disconnect this particular target. A list of tuples disconnects the targets in the list.
- timeout – Timeout to ensure all data is sent before disconnecting. slc.INFINITE means blocking, 0 means disconnect and discard pending messages and any positive number is the maximum time to wait before discarding the messages (TODO: Or raising an exception?).
-
discover
(name=None)[source]¶ Discover the sockets advertising on the local network.
Parameters: name – Name to discover. Defaults to discover everything.
-
is_acknowledged
(self, message_id, target=ALL)[source]¶ Returns if the message represented by message_id has been successfully received by the pair.
Parameters: - message_id – Message ID provided by send.
- target – Check for a given target or list of targets. If there are multiple targets, the function will return true only if all targets have acknowledged the message.
-
listen
(port=0, host='0.0.0.0')[source]¶ Act as a server. Allows other communicators to connect() to it.
Parameters: - port – Port on which to listen. Default (0) is to let the operating system decide which port, available on the variable port.
- host – Host address on which to listen to.
-
receive
(self, source=ALL, timeout=INFINITE)[source]¶ Receive data from the peer.
Parameters: - source – Tuple (host, port) from which to receive from.
- timeout – Maximum time to wait. slc.INFINITE means blocking. 0 means non-blocking. Any strictly positive number means to wait for this maximum time in seconds to wait. An error is raised in the latter case if no data is received.
Returns: src, obj
-
recv
(self, source=ALL, timeout=INFINITE)[source]¶ Receive data. Same as receive(), but won’t provide the peer address.
-
send
(self, data, target=ALL, raw=False)[source]¶ Send data to peer(s).
Parameters: - data – Data to send. Can be any type serializable by the chosen serialization protocol if raw is False. If raw is True, data must have a file-like interface, such as a bytes type.
- target – Target peer to send the data to. If None, send to all peers. If set to a tuple of (host, port), send only to this peer. If set to a list of tuples, only send to these particular targets.
- raw – If the data must be serialized or not before sending.
Returns: Message ID. Can be used to determine whether or not this message has been acknowledged by all its recipients.