From d38c90f0b429df3c13fb13f87481b73465d2eae5 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 30 Mar 2024 14:36:35 -0700 Subject: Reorganization in progress. --- docs/reference/src/protocols/bus.md | 58 ----------------------------------- docs/reference/src/protocols/index.md | 1 - docs/reference/src/protocols/pub.md | 40 ------------------------ docs/reference/src/protocols/rep.md | 56 --------------------------------- 4 files changed, 155 deletions(-) delete mode 100644 docs/reference/src/protocols/bus.md delete mode 100644 docs/reference/src/protocols/index.md delete mode 100644 docs/reference/src/protocols/pub.md delete mode 100644 docs/reference/src/protocols/rep.md (limited to 'docs/reference/src/protocols') diff --git a/docs/reference/src/protocols/bus.md b/docs/reference/src/protocols/bus.md deleted file mode 100644 index 8583ed65..00000000 --- a/docs/reference/src/protocols/bus.md +++ /dev/null @@ -1,58 +0,0 @@ -# BUS Protocol - -{{hi:protocol, _BUS_}} -The {{i:_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 {{i: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 [`nng_bus0_open()`](../api/nng_bus_open.md) 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 [raw mode](../overview/raw.md), received messages will -contain the incoming [pipe](../api/nng_pipe.md) 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 [device](../api/nng_device.md) -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. diff --git a/docs/reference/src/protocols/index.md b/docs/reference/src/protocols/index.md deleted file mode 100644 index 8d9f7317..00000000 --- a/docs/reference/src/protocols/index.md +++ /dev/null @@ -1 +0,0 @@ -# Protocols diff --git a/docs/reference/src/protocols/pub.md b/docs/reference/src/protocols/pub.md deleted file mode 100644 index bd49b1d3..00000000 --- a/docs/reference/src/protocols/pub.md +++ /dev/null @@ -1,40 +0,0 @@ -# PUB Protocol - -The {{i:_PUB_ protocol}}{{hi:protocol, _PUB_} is one half of a {{i:publisher}}/subscriber pattern. -In this pattern, a publisher sends data, which is broadcast to all -subscribers. -The subscribing applications only see the data to which -they have subscribed. - -The _PUB_ protocol is the publisher side, and the -[_SUB_](sub.md) protocol is the subscriber side. - -> [!NOTE] -> In this implementation, the publisher delivers all messages to all -> subscribers. -> The subscribers maintain their own subscriptions, and filter them locally. -> Thus, this pattern should not be used in an attempt to reduce bandwidth -> consumption. - -The topics that subscribers subscribe to is just the first part of -the message body. -Applications should construct their messages accordingly. - -## Socket Operations - -The [`nng_pub0_open()`](../api/nng_pub_open.md) functions create a publisher socket. -This socket may be used to send messages, but is unable to receive them. -Attempts to receive messages will result in `NNG_ENOTSUP`. - -## 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 _PUB_ protocol has no protocol-specific options. - -## Protocol Headers - -The _PUB_ protocol has no protocol-specific headers. diff --git a/docs/reference/src/protocols/rep.md b/docs/reference/src/protocols/rep.md deleted file mode 100644 index cb602e47..00000000 --- a/docs/reference/src/protocols/rep.md +++ /dev/null @@ -1,56 +0,0 @@ -# REP Protocol - -{{hi:protocol, _REP_}} -The {{i:_REP_ protocol}} is one half of a {{i:request/reply pattern}}. -In this pattern, a requester sends a message to one replier, who -is expected to reply. -The request is resent if no reply arrives, -until a reply is received or the request times out. - -> [!TIP] -> This protocol is useful in setting up RPC-like services. -> It is also reliable, in that a requester will keep retrying until -> a reply is received. - -The _REP_ protocol is the replier side, and the -[_REP_](req.md) protocol is the requester side. - -## Socket Operations - -The [`nng_rep0_open()`](nng_rep_open.md) functions create a replier socket. -This socket may be used to receive messages (requests), and then to send -replies. - -Generally a reply can only be sent after receiving a request. - -Send operations will result in `NNG_ESTATE` if no corresponding request -was previously received. - -Likewise, only one receive operation may be pending at a time. -Any additional concurrent receive operations will result in `NNG_ESTATE`. - -[Raw](../overview/raw.md) mode sockets ignore all these restrictions. - -## Context Operations - -This protocol supports the creation of [contexts](../api/nng_ctx.md) for concurrent use cases using [`nng_ctx_open()`](../api/nng_ctx_open.md). - -Each context may have at most one outstanding request, and operates -independently of the others. -The restrictions for order of operations with sockets apply equally -well for contexts, except that each context will be treated as if it were -a separate socket. - -## 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 _REP_ protocol has no protocol-specific options. - -## Protocol Headers - -The _REP_ protocol uses a {{ii:backtrace}} in the header. -This is more fully documented in the [_REQ_](req.md) chapter. -- cgit v1.2.3-70-g09d2