Module tc_network::gossip

Helper for sending rate-limited gossip messages.

Context

The NetworkService struct provides a way to send notifications to a certain peer through the NetworkService::notification_sender method. This method is quite low level and isn’t expected to be used directly.

The QueuedSender struct provided by this module is built on top of NetworkService::notification_sender and provides a cleaner way to send notifications.

Behaviour

An instance of QueuedSender is specific to a certain combination of PeerId and protocol name. It maintains a buffer of messages waiting to be sent out. The user of this API is able to manipulate that queue, adding or removing obsolete messages.

Creating a QueuedSender also returns a opaque Future whose responsibility it to drain that queue and actually send the messages. If the substream with the given combination of peer and protocol is closed, the queue is silently discarded. It is the role of the user to track which peers we are connected to.

In normal situations, messages sent through a QueuedSender will arrive in the same order as they have been sent. It is possible, in the situation of disconnects and reconnects, that messages arrive in a different order. See also https://github.com/tetcoin/tetcore/issues/6756. However, if multiple instances of QueuedSender exist for the same peer and protocol, or if some other code uses the NetworkService to send notifications to this combination or peer and protocol, then the notifications will be interleaved in an unpredictable way.

Structs

QueueGuard	Locked queue of messages to the given peer.
QueuedSender	Notifications sender for a specific combination of network service, peer, and protocol.