Sending

Unlike for receiving, each stream object can only use a single transport. There is currently no support for collective operations where multiple producers cooperate to construct a heap between them. It is still possible to do multi-producer, single-consumer operation if the heap IDs are kept separate.

Because each stream has only one transport, there is a separate class for each, rather than a generic Stream class. Because there is common configuration between the stream classes, configuration is encapsulated in a spead2.send.StreamConfig.

class spead2.send.StreamConfig(max_packet_size=1472, rate=0.0, burst_size=65536, max_heaps=4)
Parameters:
  • max_packet_size (int) – Heaps will be split into packets of at most this size.
  • rate (double) – Maximum transmission rate, in bytes per second, or 0 to send as fast as possible.
  • burst_size (int) – Bursts of up to this size will be sent as fast as possible. Setting this too large (larger than available buffer sizes) risks losing packets, while setting it too small may reduce throughput by causing more sleeps than necessary.
  • max_heaps (int) – For asynchronous transmits, the maximum number of heaps that can be in-flight.

The constructor arguments are also instance attributes.

Streams send pre-baked heaps, which can be constructed by hand, but are more normally created from an ItemGroup by a spead2.send.HeapGenerator. To simplify cases where one item group is paired with one heap generator, a convenience class spead2.send.ItemGroup is provided that inherits from both.

class spead2.send.HeapGenerator(item_group, descriptor_frequency=None, flavour=<Mock name='mock.Flavour()' id='140032309393168'>)

Tracks which items and item values have previously been sent and generates delta heaps.

Parameters:
  • item_group (spead2.ItemGroup) – Item group to monitor.
  • descriptor_frequency (int, optional) – If specified, descriptors will be re-sent once every descriptor_frequency heaps generated by this method.
  • flavour (spead2.Flavour) – The SPEAD protocol flavour used for heaps generated by get_heap() and get_end().
add_to_heap(heap, descriptors='stale', data='stale')

Update a heap to contains all the new items and item descriptors since the last call.

Parameters:
  • heap (Heap) – The heap to update.
  • descriptors ({'stale', 'all', 'none'}) – Which descriptors to send. The default (‘stale’) sends only descriptors that have not been sent, or have not been sent recently enough according to the descriptor_frequency passed to the constructor. The other options are to send all the descriptors or none of them. Sending all descriptors is useful if a new receiver is added which will be out of date.
  • data ({'stale', 'all', 'none'}) – Which data items to send.
  • item_group (ItemGroup, optional) – If specified, uses the items from this item group instead of the one passed to the constructor (which could be None).
Raises:

ValueError – if descriptors or data is not one of the legal values
get_heap(*args, **kwargs)

Return a new heap which contains all the new items and item descriptors since the last call. This is a convenience wrapper around add_to_heap().

get_start()

Return a heap that contains only a start-of-stream marker.

get_end()

Return a heap that contains only an end-of-stream marker.

Blocking send

class spead2.send.UdpStream(thread_pool, hostname, port, config, buffer_size=DEFAULT_BUFFER_SIZE, socket=None)

Stream using UDP. Note that since UDP is an unreliable protocol, there is no guarantee that packets arrive.

Parameters:
  • thread_pool (spead2.ThreadPool) – Thread pool handling the I/O
  • hostname (str) – Peer hostname
  • port (int) – Peer port
  • config (spead2.send.StreamConfig) – Stream configuration
  • buffer_size (int) – Socket buffer size. A warning is logged if this size cannot be set due to OS limits.
  • socket (socket.socket) – If specified, this socket is used rather than a new one. The socket must be open but unbound. The caller must not use this socket any further, although it is not necessary to keep it alive. This is mainly useful for fine-tuning socket options.
send_heap(heap, cnt=-1)

Sends a spead2.send.Heap to the peer, and wait for completion. There is currently no indication of whether it successfully arrived.

If not specified, a heap cnt is chosen automatically (the choice can be modified by calling set_cnt_sequence()). If a non-negative value is specified for cnt, it is used instead. It is the user’s responsibility to avoid collisions.

set_cnt_sequence(next, step)

Modify the linear sequence used to generate heap cnts. The next heap will have cnt next, and each following cnt will be incremented by step. When using this, it is the user’s responsibility to ensure that the generated values remain unique. The initial state is next = 1, cnt = 1.

This is useful when multiple senders will send heaps to the same receiver, and need to keep their heap cnts separate.

class spead2.send.UdpStream(thread_pool, multicast_group, port, config, buffer_size=DEFAULT_BUFFER_SIZE, ttl)

Stream using UDP, with multicast TTL. Note that the regular constructor will also work with UDP, but does not give any control over the TTL.

Parameters:
  • thread_pool (spead2.ThreadPool) – Thread pool handling the I/O
  • multicast_group (str) – Multicast group hostname/IP address
  • port (int) – Destination port
  • config (spead2.send.StreamConfig) – Stream configuration
  • buffer_size (int) – Socket buffer size. A warning is logged if this size cannot be set due to OS limits.
  • ttl (int) – Multicast TTL
class spead2.send.UdpStream(thread_pool, multicast_group, port, config, buffer_size=524288, ttl, interface_address)

Stream using UDP, with multicast TTL and interface address (IPv4 only).

Parameters:
  • thread_pool (spead2.ThreadPool) – Thread pool handling the I/O
  • multicast_group (str) – Multicast group hostname/IP address
  • port (int) – Destination port
  • config (spead2.send.StreamConfig) – Stream configuration
  • buffer_size (int) – Socket buffer size. A warning is logged if this size cannot be set due to OS limits.
  • ttl (int) – Multicast TTL
  • interface_address (str) – Hostname/IP address of the interface on which to send the data
class spead2.send.UdpStream(thread_pool, multicast_group, port, config, buffer_size=524288, ttl, interface_index)

Stream using UDP, with multicast TTL and interface index (IPv6 only).

Parameters:
  • thread_pool (spead2.ThreadPool) – Thread pool handling the I/O
  • multicast_group (str) – Multicast group hostname/IP address
  • port (int) – Destination port
  • config (spead2.send.StreamConfig) – Stream configuration
  • buffer_size (int) – Socket buffer size. A warning is logged if this size cannot be set due to OS limits.
  • ttl (int) – Multicast TTL
  • interface_index (str) – Index of the interface on which to send the data
class spead2.send.BytesStream(thread_pool, config)

Stream that collects packets in memory and makes the concatenated stream available.

Parameters:
  • thread_pool (spead2.ThreadPool) – Thread pool handling the I/O
  • config (spead2.send.StreamConfig) – Stream configuration
send_heap(heap)

Appends a spead2.send.Heap to the memory buffer.

getvalue()

Return a copy of the memory buffer.

Return type:bytes

Asynchronous send

As for asynchronous receives, asynchronous sends are managed by trollius. A stream can buffer up multiple heaps for asynchronous send, up to the limit specified by max_heaps in the StreamConfig. If this limit is exceeded, heaps will be dropped, and the returned future has an IOError exception set. An IOError could also indicate a low-level error in sending the heap (for example, if the packet size exceeds the MTU).