sp: hub: Introduce hub proto

Add hub protocol.
Protocol with star topology and
send/receive guarantees.

Protocol is compatible with pair0

Author: apokriff

cmake/NNGOptions.cmake

@@ -1,5 +1,6 @@
 #
 # Copyright 2020 Staysail Systems, Inc. <[email protected]>
+# Copyright 2022 Cogent Embedded, Inc.
 #
 # This software is supplied under the terms of the MIT License, a
 # copy of which should be located in the distribution where this
@@ -46,6 +47,9 @@ mark_as_advanced(NNG_ENABLE_STATS)
 option (NNG_PROTO_BUS0 "Enable BUSv0 protocol." ON)
 mark_as_advanced(NNG_PROTO_BUS0)
 
+option (NNG_PROTO_HUB0 "Enable HUBv0 protocol." ON)
+mark_as_advanced(NNG_PROTO_HUB0)
+
 option (NNG_PROTO_PAIR0 "Enable PAIRv0 protocol." ON)
 mark_as_advanced(NNG_PROTO_PAIR0)
 

docs/man/CMakeLists.txt

@@ -82,6 +82,7 @@ if (NNG_ENABLE_DOC)
             nng_aio_wait
             nng_alloc
             nng_bus_open
+            nng_hub_open
             nng_close
             nng_ctx_close
             nng_ctx_get
@@ -379,6 +380,7 @@ if (NNG_ENABLE_DOC)
     set(NNG_MAN7
             nng
             nng_bus
+            nng_hub
             nng_inproc
             nng_ipc
             nng_pair

docs/man/libnng.3.adoc

@@ -4,6 +4,7 @@
 // Copyright 2018 Capitar IT Group BV <[email protected]>
 // Copyright 2019 Devolutions <[email protected]>
 // Copyright 2020 Dirac Research <[email protected]>
+// Copyright 2022 Cogent Embedded, Inc.
 //
 // This document is supplied under the terms of the MIT License, a
 // copy of which should be located in the distribution where this
@@ -193,6 +194,7 @@ The following functions are used to construct a socket with a specific protocol:
 
 |===
 |xref:nng_bus_open.3.adoc[nng_bus_open()]|open a bus socket
+|xref:nng_hub_open.3.adoc[nng_hub_open()]|open a hub socket
 |xref:nng_pair_open.3.adoc[nng_pair_open()]|open a pair socket
 |xref:nng_pub_open.3.adoc[nng_pub_open()]|open a pub socket
 |xref:nng_pull_open.3.adoc[nng_pull_open()]|open a pull socket

docs/man/nng.7.adoc

@@ -1,5 +1,6 @@
 = nng(7)
 //
+// Copyright 2022 Cogent Embedded, Inc.
 // Copyright 2019 Staysail Systems, Inc. <[email protected]>
 // Copyright 2018 Capitar IT Group BV <[email protected]>
 //
@@ -54,6 +55,7 @@ other languages please check the http://nanomsg.org/[website].
 
 [horizontal]
 xref:nng_bus.7.adoc[nng_bus(7)]:: Bus protocol
+xref:nng_hub.7.adoc[nng_hub(7)]:: Hub protocol
 xref:nng_pair.7.adoc[nng_pair(7)]:: Pair protocol
 xref:nng_pub.7.adoc[nng_pub(7)]:: Publisher side of publish/subscribe protocol
 xref:nng_pull.7.adoc[nng_pull(7)]:: Pull side of pipeline protocol

docs/man/nng_hub.7.adoc

@@ -0,0 +1,58 @@
+= nng_hub(7)
+//
+// Copyright 2022 Cogent Embedded, Inc.
+//
+// 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_hub - hub protocol
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nng/protocol/hub0/hub.h>
+----
+
+== DESCRIPTION
+
+(((protocol, _hub_)))
+The ((_hub_ protocol)) provides for building star networks where
+all peers are connected to one peer.
+In this protocol, each message sent by a node is sent to every one of
+its directly connected peers.
+
+All message delivery in this pattern is guaranteed.
+
+This protocol is compatible with pair0
+
+=== Socket Operations
+
+The xref:nng_hub_open.3.adoc[`nng_hub0_open()`] functions create a hub socket.
+This socket may be used to send and receive messages.
+Sending messages will attempt to deliver to each 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 _hub_ protocol has no protocol-specific options.
+
+=== Protocol Headers
+
+No message headers are present.
+
+== SEE ALSO
+
+[.text-left]
+xref:nng_hub_open.3.adoc[nng_hub_open(3)],
+xref:nng_pair.7.adoc[nng_pair],
+xref:nng.7.adoc[nng(7)]

docs/man/nng_hub_open.3.adoc

@@ -0,0 +1,45 @@
+= nng_hub_open(3)
+//
+// Copyright 2022 Cogent Embedded, Inc.
+//
+// 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_hub_open - create hub socket
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nng/nng.h>
+#include <nng/protocol/hub0/hub.h>
+
+int nng_hub0_open(nng_socket *s);
+----
+
+== DESCRIPTION
+
+The `nng_hub0_open()` function creates a xref:nng_hub.7.adoc[_hub_] version 0
+xref:nng_socket.5.adoc[socket] and returns it at the location pointed to by _s_.
+
+== RETURN VALUES
+
+These functions return 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+[horizontal]
+`NNG_ENOMEM`:: Insufficient memory is available.
+`NNG_ENOTSUP`:: The protocol is not supported.
+
+== SEE ALSO
+
+[.text-left]
+xref:nng_socket.5.adoc[nng_socket(5)],
+xref:nng_hub.7.adoc[nng_hub(7)],
+xref:nng.7.adoc[nng(7)]

include/nng/protocol/hub0/hub.h

@@ -0,0 +1,31 @@
+//
+// Copyright 2022 Cogent Embedded, Inc.
+//
+// This software 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.
+//
+#ifndef NNG_PROTOCOL_HUB0_HUB_H
+#define NNG_PROTOCOL_HUB0_HUB_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define NNG_HUB0_SELF 0x10
+#define NNG_HUB0_PEER 0x10
+#define NNG_HUB0_SELF_NAME "hub"
+#define NNG_HUB0_PEER_NAME "hub"
+
+NNG_DECL int nng_hub0_open(nng_socket *);
+
+#ifndef nng_hub_open
+#define nng_hub_open nng_hub0_open
+#endif
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* NNG_PROTOCOL_HUB0_HUB_H_ */

src/sp/protocol/CMakeLists.txt

@@ -1,5 +1,6 @@
 #
 # Copyright 2020 Staysail Systems, Inc. <[email protected]>
+# Copyright 2022 Cogent Embedded, Inc.
 #
 # This software is supplied under the terms of the MIT License, a
 # copy of which should be located in the distribution where this
@@ -11,6 +12,7 @@
 nng_directory(protocol)
 
 add_subdirectory(bus0)
+add_subdirectory(hub0)
 add_subdirectory(pair0)
 add_subdirectory(pair1)
 add_subdirectory(pipeline0)

src/sp/protocol/hub0/CMakeLists.txt

@@ -0,0 +1,16 @@
+#
+# Copyright 2022 Cogent Embedded, Inc.
+#
+# This software 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.
+#
+
+nng_directory(hub0)
+
+nng_sources_if(NNG_PROTO_HUB0 hub.c)
+nng_headers_if(NNG_PROTO_HUB0 nng/protocol/hub0/hub.h)
+nng_defines_if(NNG_PROTO_HUB0 NNG_HAVE_HUB0)
+
+nng_test(hub_test)