SpreadProtocol » History » Version 19
Version 18 (J. Moringen, 10/31/2011 04:29 PM) → Version 19/21 (J. Moringen, 08/12/2012 06:23 PM)
https://docs.cor-lab.org/rsb-manual/trunk/specification-spread.rst h1. SpreadProtocol
{{>toc}}
This wiki page describes the protocol used by the Spread-based connectors.
h2. Data Format
Data exchanged on the wire by the Spread-based transport is encoded using "Google protocol buffers":http://code.google.com/apis/protocolbuffers/. A Spread message always contains a fragment of a notification (source:/trunk/protocol/rsb/protocol/FragmentedNotification.proto) as elementary communication unit. Descriptions of the Notification contents are given as comments on the descriptor files.
h2. Fragmentation
Because Spread has a message size limit, a single @Notification@ may not be sufficient to transport a whole event with a huge amount of user data. Hence, events 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 paylod data (@FragmentedNotification.notification.data@ field)
** Which fields of the @Notification@ embedded in @FragmentedNotification.notification@ are present (see below)
* Each of the @FragmentedNotification@ objects contains a @Notification@ object
** The id of the event (@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@
h2. Hierarchical Bus
The hierarchical bus is created by sending each message to a group corresponding to its scope as well as groups corresponding to all super scopes including "/" (multigroup mulitcast).
_Example_
<pre>
super-scopes(/foo/bar/, include-self? = yes) = /, /foo/, /foo/bar/
</pre>
h2. 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":http://en.wikipedia.org/wiki/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_
<pre>
/ -> "6666cd76f96956469e7be39d750cc7d\0"
/foo/ -> "4f87be8f6e593d167f5fd1ab238cfc2\0"
/foo/bar/ -> "1c184f3891344400380281315d9e738\0"
</pre>
h2. Quality of Service
The following table explains how the 2D RSB QoS settings are mapped to spread message types.
| |_.UNRELIABLE |_.RELIABLE |
|_.UNORDERED | UNRELIABLE_MESS | RELIABLE_MESS |
|_.ORDERED | FIFO_MESS | FIFO_MESS |
h2. Implementations
|_.Language |_.File(s)/Directory |
| C++ | source:trunk/cpp/core/src/rsb/transport/spread |
| Java | source:trunk/java/core/src/rsb/transport/spread |
| Python | source:"trunk/python/core/rsb/rsbspread/__init__.py" |
| Common Lisp | source:trunk/cl/cl-rsb/src/transport/spread |
{{>toc}}
This wiki page describes the protocol used by the Spread-based connectors.
h2. Data Format
Data exchanged on the wire by the Spread-based transport is encoded using "Google protocol buffers":http://code.google.com/apis/protocolbuffers/. A Spread message always contains a fragment of a notification (source:/trunk/protocol/rsb/protocol/FragmentedNotification.proto) as elementary communication unit. Descriptions of the Notification contents are given as comments on the descriptor files.
h2. Fragmentation
Because Spread has a message size limit, a single @Notification@ may not be sufficient to transport a whole event with a huge amount of user data. Hence, events 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 paylod data (@FragmentedNotification.notification.data@ field)
** Which fields of the @Notification@ embedded in @FragmentedNotification.notification@ are present (see below)
* Each of the @FragmentedNotification@ objects contains a @Notification@ object
** The id of the event (@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@
h2. Hierarchical Bus
The hierarchical bus is created by sending each message to a group corresponding to its scope as well as groups corresponding to all super scopes including "/" (multigroup mulitcast).
_Example_
<pre>
super-scopes(/foo/bar/, include-self? = yes) = /, /foo/, /foo/bar/
</pre>
h2. 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":http://en.wikipedia.org/wiki/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_
<pre>
/ -> "6666cd76f96956469e7be39d750cc7d\0"
/foo/ -> "4f87be8f6e593d167f5fd1ab238cfc2\0"
/foo/bar/ -> "1c184f3891344400380281315d9e738\0"
</pre>
h2. Quality of Service
The following table explains how the 2D RSB QoS settings are mapped to spread message types.
| |_.UNRELIABLE |_.RELIABLE |
|_.UNORDERED | UNRELIABLE_MESS | RELIABLE_MESS |
|_.ORDERED | FIFO_MESS | FIFO_MESS |
h2. Implementations
|_.Language |_.File(s)/Directory |
| C++ | source:trunk/cpp/core/src/rsb/transport/spread |
| Java | source:trunk/java/core/src/rsb/transport/spread |
| Python | source:"trunk/python/core/rsb/rsbspread/__init__.py" |
| Common Lisp | source:trunk/cl/cl-rsb/src/transport/spread |