85 lines
2.9 KiB
Text
85 lines
2.9 KiB
Text
|
= nng_bus(7)
|
||
|
|
//
|
||
|
|
// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
|
||
|
|
// Copyright 2018 Capitar IT Group BV <info@capitar.com>
|
||
|
|
//
|
||
|
|
// This document is supplied under the terms of the MIT License, a
|
||
|
|
// copy of which should be located in the distribution where this
|
||
|
|
// file was obtained (LICENSE.txt). A copy of the license may also be
|
||
|
|
// found online at https://opensource.org/licenses/MIT.
|
||
|
|
//
|
||
|
|
|
||
|
|
== NAME
|
||
|
|
|
||
|
|
nng_bus - bus protocol
|
||
|
|
|
||
|
|
== SYNOPSIS
|
||
|
|
|
||
|
|
[source,c]
|
||
|
|
----
|
||
|
|
#include <nng/protocol/bus0/bus.h>
|
||
|
|
----
|
||
|
|
|
||
|
|
== DESCRIPTION
|
||
|
|
|
||
|
|
(((protocol, _bus_)))
|
||
|
|
The ((_bus_ protocol)) provides for building mesh networks where
|
||
|
|
every peer is connected to every other peer.
|
||
|
|
In this protocol, each message sent by a node is sent to every one of
|
||
|
|
its directly connected peers.
|
||
|
|
|
||
|
|
TIP: Messages are only sent to directly connected peers.
|
||
|
|
This means that in the event that a peer is connected indirectly, it will not
|
||
|
|
receive messages.
|
||
|
|
When using this protocol to build mesh networks, it
|
||
|
|
is therefore important that a _fully-connected_ mesh network be constructed.
|
||
|
|
|
||
|
|
All message delivery in this pattern is ((best-effort)), which means that
|
||
|
|
peers may not receive messages.
|
||
|
|
Furthermore, delivery may occur to some,
|
||
|
|
all, or none of the directly connected peers.
|
||
|
|
(Messages are not delivered when peer nodes are unable to receive.)
|
||
|
|
Hence, send operations will never block; instead if the
|
||
|
|
message cannot be delivered for any reason it is discarded.
|
||
|
|
|
||
|
|
TIP: In order to minimize the likelihood of message loss, this protocol
|
||
|
|
should not be used for high throughput communications.
|
||
|
|
Furthermore, the more traffic _in aggregate_ that occurs across the topology,
|
||
|
|
the more likely that message loss is to occur.
|
||
|
|
|
||
|
|
=== Socket Operations
|
||
|
|
|
||
|
|
The xref:nng_bus_open.3.adoc[`nng_bus0_open()`] functions create a bus socket.
|
||
|
|
This socket may be used to send and receive messages.
|
||
|
|
Sending messages will attempt to deliver to each directly connected peer.
|
||
|
|
|
||
|
|
=== Protocol Versions
|
||
|
|
|
||
|
|
Only version 0 of this protocol is supported.
|
||
|
|
(At the time of writing, no other versions of this protocol have been defined.)
|
||
|
|
|
||
|
|
=== Protocol Options
|
||
|
|
|
||
|
|
The _bus_ protocol has no protocol-specific options.
|
||
|
|
|
||
|
|
=== Protocol Headers
|
||
|
|
|
||
|
|
When using a _bus_ socket in xref:nng.7.adoc#raw_mode[raw mode], received messages will
|
||
|
|
contain the incoming xref:nng_pipe.5.adoc[pipe] ID as the sole element in the header.
|
||
|
|
If a message containing such a header is sent using a raw _bus_ socket, then,
|
||
|
|
the message will be delivered to all connected pipes _except_ the one
|
||
|
|
identified in the header.
|
||
|
|
This behavior is intended for use with xref:nng_device.3.adoc[device]
|
||
|
|
configurations consisting of just a single socket.
|
||
|
|
Such configurations are useful in the creation of rebroadcasters, and this
|
||
|
|
capability prevents a message from being routed back to its source.
|
||
|
|
If no header is present, then a message is sent to all connected pipes.
|
||
|
|
|
||
|
|
When using normal (cooked mode) _bus_ sockets, no message headers are present.
|
||
|
|
|
||
|
|
== SEE ALSO
|
||
|
|
|
||
|
|
[.text-left]
|
||
|
|
xref:nng_bus_open.3.adoc[nng_bus_open(3)],
|
||
|
|
xref:nng.7.adoc[nng(7)]
|