Spread Transport¶
This page describes the protocol used by the Spread-based transport.
Note
Starting with version 0.9 of RSB, the C++ implementation does no longer include the Spread-based transport in the RSB core. Instead, the transport is available as a plugin.
Options¶
See also
- Configuration
- Specification of configuration mechanism.
The following configuration options are accepted by the Spread-based transport:
Name Type Comment
+ transport
+-- spread
+---- host string Name of the host running the Spread daemon
+---- port uint Port on which Spread daemon runs
+---- maxfragmentsize uint Maximum Spread message size
+---- tcpnodelay boolean Implementation detail
Notification Format¶
Data exchanged on the wire by the Spread-based transport is encoded using Google protocol buffers. A Spread message always contains a fragment of a notification elementary communication unit:
Fragmentation¶
Because Spread has a message size limit, a single
notification may not be sufficient to transport a whole
event when the payload is large. Hence, event
s may be encoded in several FragmentedNotification
s which are
sent sequentially. Multiple FragmentedNotification
objects are
constructed according to the following rules:
- The size of individual fragments (i.e. serialized size of the
FragmentedNotification
objects) must not exceed 100,000 octets - Fragment numbers are in the range
[0, NUMBER-OF-FRAGMENTS - 1]
- The fields which differ among
FragmentedNotification
s for one event are:- The number of the fragment (
FragmentedNotification.data_part
field) - The payload (
FragmentedNotification.notification.data
field) - Which fields of the
Notification
embedded inFragmentedNotification.notification
are present (see below)
- The number of the fragment (
- Each of the
FragmentedNotification
objects contains aNotification
object- The event id (
Notification.event_id
field) is always present (to specify the event to which a fragment belongs) - For the initial fragment (fragment number 0), all fields of the
embedded
Notification
object are present - For subsequent fragments (fragment number >= 1), only the following
fields of the embedded
Notification
object are present:Notification.event_id
Notification.data
- The event id (
Hierarchical Bus¶
The hierarchical bus is created by sending each message to multiple
Spread-groups: a Spread-group corresponding to its
scope as well as Spread-groups corresponding to all
superscopes including the root-scope
(/
) (In Spread terminology this is called “multigroup
multicast”). Spread‘s protocol takes care of only transmitting
the message to interested recipients and transmitting it only once to
each of them.
Example for scope /foo/bar/
:
super-scopes(/foo/bar/, include-self? = yes) = /, /foo/, /foo/bar/
Group Names¶
Group names are created by applying the following steps to the fully formal scope string representation (including trailing slash):
- Hash the scope string using MD5.
- Convert the 16 bytes of output to a 32 character string by concatenating the zero-padded hex (base-16) representations of the individual bytes. Letters of the hex representation have to be lower case.
- Remove the final character of the hex representation of the hash. (Since Spread group names can only be 32 bytes long including the 0-terminator)
Example:
/ -> "6666cd76f96956469e7be39d750cc7d\0"
/foo/ -> "4f87be8f6e593d167f5fd1ab238cfc2\0"
/foo/bar/ -> "1c184f3891344400380281315d9e738\0"
Quality of Service¶
The following table explains how the 2D RSB QoS settings are mapped to Spread message types:
Quality | unreliable | reliable |
---|---|---|
unordered | UNRELIABLE_MESS |
RELIABLE_MESS |
ordered | FIFO_MESS |
FIFO_MESS |
Implementations¶
Language | File(s) |
---|---|
C++ | “0.13” branch of https://code.cor-lab.org/git/rsb.git.spread-cpp at src/rsb/transport/spread |
Java | “0.13” branch of https://code.cor-lab.org/git/rsb.git.java at src/rsb/transport/spread |
Python | /../rsb-python/rsb/transport/rsbspread/__init__.py |
Common Lisp | “0.13” branch of https://code.cor-lab.org/git/rsb.git.cl at src/transport/spread |