documentation updates + bus as default protocol

Author: shikokuchuo

NEWS.md

@@ -9,10 +9,11 @@
 #### Updates
 
 * Protocol-specific helpers `subscribe()`, `unsubscribe()`, and `survey_time()` gain nanoContext methods.
+* Default protocol is now 'bus' when opening a new Socket or nano Object - the choices are now ordered more logically.
 * Closing a stream now strips all attributes on the object rendering it a nil external pointer - this is for safety, eliminating a potential crash if attempting to re-use a closed stream.
 * For receives, if an error occurs in unserialisation or data conversion (e.g. mode was incorrectly specified), the received raw vector is now available at both `$raw` and `$data` if `keep.raw = TRUE`.
 * Setting 'NANONEXT_TLS=1' now allows the downloaded NNG library to be built against a system mbedtls installation.
-* Setting 'NANONEXT_ARM' is no longer required on platforms such as Raspberry Pi - the package configure script should now detect platforms that require the libatomic linker flag to be set automatically.
+* Setting 'NANONEXT_ARM' is no longer required on platforms such as Raspberry Pi - the package configure script now detects platforms requiring the libatomic linker flag automatically.
 * Deprecated `send_ctx()`, `recv_ctx()` and logging removed.
 * All-round internal performance optimisations.
 

R/docs.R

@@ -7,16 +7,7 @@
 #'     For an authoritative guide please refer to the online documentation for
 #'     the NNG library at <https://nng.nanomsg.org/man/>.
 #'
-#' @section Pair (two-way radio):
-#'
-#'     [protocol, pair] The pair protocol implements a peer-to-peer pattern,
-#'     where relationships between peers are one-to-one. Only one peer may be
-#'     connected to another peer at a time, but both may speak freely.
-#'
-#'     Normally, this pattern will block when attempting to send a message
-#'     if no peer is able to receive the message.
-#'
-#' @section Bus (routing):
+#' @section Bus (mesh networks):
 #'
 #'     [protocol, bus] The bus protocol is useful for routing applications or for
 #'     building mesh networks where every peer is connected to every other peer.
@@ -37,24 +28,16 @@
 #'     block; instead if the message cannot be delivered for any reason it is
 #'     discarded.
 #'
-#' @section Request/Reply (I ask, you answer):
-#'
-#'     In a request/reply pattern, a requester sends a message to one replier,
-#'     who is expected to reply with a single answer. This is used for
-#'     synchronous communications, for example remote procedure calls (RPCs).
-#'
-#'     The request is resent automatically if no reply arrives, until a reply is
-#'     received or the request times out.
+#' @section Pair (two-way radio):
 #'
-#'     [protocol, req] The req protocol is one half of a request/reply pattern.
-#'     This socket may be used to send messages (requests), and then to receive
-#'     replies. Generally a reply can only be received after sending a request.
+#'     [protocol, pair] The pair protocol implements a peer-to-peer pattern,
+#'     where relationships between peers are one-to-one. Only one peer may be
+#'     connected to another peer at a time, but both may speak freely.
 #'
-#'     [protocol, rep] The rep protocol is one half of a request/reply pattern.
-#'     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.
+#'     Normally, this pattern will block when attempting to send a message
+#'     if no peer is able to receive the message.
 #'
-#' @section Pipeline (one-way pipe):
+#' @section Push/Pull (one-way pipeline):
 #'
 #'     In the pipeline pattern, pushers distribute messages to pullers, hence
 #'     useful for solving producer/consumer problems.
@@ -84,7 +67,24 @@
 #'     pattern. This socket may be used to receive messages, but is unable to
 #'     send them.
 #'
-#' @section Survey (everyone votes):
+#' @section Request/Reply (RPC):
+#'
+#'     In a request/reply pattern, a requester sends a message to one replier,
+#'     who is expected to reply with a single answer. This is used for
+#'     synchronous communications, for example remote procedure calls (RPCs).
+#'
+#'     The request is resent automatically if no reply arrives, until a reply is
+#'     received or the request times out.
+#'
+#'     [protocol, req] The req protocol is one half of a request/reply pattern.
+#'     This socket may be used to send messages (requests), and then to receive
+#'     replies. Generally a reply can only be received after sending a request.
+#'
+#'     [protocol, rep] The rep protocol is one half of a request/reply pattern.
+#'     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.
+#'
+#' @section Surveyor/Respondent (voting & service discovery):
 #'
 #'     In a survey pattern, a surveyor sends a survey, which is broadcast to all
 #'     peer respondents. The respondents then have a chance to reply (but are

R/nano.R

@@ -51,14 +51,13 @@
 #'
 #' @export
 #'
-nano <- function(protocol = c("pair", "bus", "req", "rep", "push", "pull",
-                              "pub", "sub", "surveyor", "respondent"),
+nano <- function(protocol = c("bus", "pair", "push", "pull", "pub", "sub",
+                              "req", "rep", "surveyor", "respondent"),
                  dial = NULL,
                  listen = NULL,
                  autostart = TRUE) {
 
   protocol <- match.arg(protocol)
-
   nano <- `class<-`(new.env(hash = FALSE), "nanoObject")
   socket <- socket(protocol)
   makeActiveBinding(sym = "socket", fun = function(x) socket, env = nano)

R/ncurl.R

@@ -7,7 +7,7 @@
 #' @param url the URL address.
 #' @param async [default FALSE] logical value whether to perform actions async.
 #' @param convert [default TRUE] logical value whether to attempt conversion of
-#'     the received raw bytes to a character vetor.
+#'     the received raw bytes to a character vector.
 #' @param method (optional) the HTTP method (defaults to 'GET' if not specified).
 #' @param headers (optional) a named list or character vector specifying the
 #'     HTTP request headers e.g. \code{list(`Content-Type` = "text/plain")} or

R/socket.R

@@ -6,8 +6,8 @@
 #'     outgoing connection) or listen (accept an incoming connection) at an
 #'     address.
 #'
-#' @param protocol [default 'pair'] choose protocol - 'pair', 'bus', 'req',
-#'     'rep', 'push', 'pull', 'pub', 'sub', 'surveyor', or 'respondent' - see
+#' @param protocol [default 'bus'] choose protocol - 'bus', 'pair', 'push',
+#'     'pull', 'pub', 'sub', 'req', 'rep', 'surveyor', or 'respondent' - see
 #'     \link{protocols}.
 #' @param dial (optional) a URL to dial, specifying the transport and address as
 #'     a character string e.g. 'inproc://anyvalue' or 'tcp://127.0.0.1:5555'
@@ -40,12 +40,12 @@
 #'
 #'     The following Scalability Protocols (communication patterns) are implemented:
 #'     \itemize{
+#'     \item{Bus (mesh networks) - protocol: 'bus'}
 #'     \item{Pair (two-way radio) - protocol: 'pair'}
-#'     \item{Bus (routing) - protocol: 'bus'}
 #'     \item{Pipeline (one-way pipe) - protocol: 'push', 'pull'}
-#'     \item{Request/Reply (I ask, you answer) - protocol: 'req', 'rep'}
 #'     \item{Publisher/Subscriber (topics & broadcast) - protocol: 'pub', 'sub'}
-#'     \item{Survey (everyone votes) - protocol: 'surveyor', 'respondent'}
+#'     \item{Request/Reply (RPC) - protocol: 'req', 'rep'}
+#'     \item{Survey (voting & service discovery) - protocol: 'surveyor', 'respondent'}
 #'     }
 #'
 #'     Please see \link{protocols} for further documentation.
@@ -57,14 +57,14 @@
 #'
 #' @export
 #'
-socket <- function(protocol = c("pair", "bus", "req", "rep", "push", "pull",
-                                "pub", "sub", "surveyor", "respondent"),
+socket <- function(protocol = c("bus", "pair", "push", "pull", "pub", "sub",
+                                "req", "rep", "surveyor", "respondent"),
                    dial = NULL,
                    listen = NULL,
                    autostart = TRUE) {
 
-  protocol <- match.arg2(protocol, c("pair", "bus", "req", "rep", "push", "pull",
-                                     "pub", "sub", "surveyor", "respondent"))
+  protocol <- match.arg2(protocol, c("bus", "pair", "push", "pull", "pub", "sub",
+                                     "req", "rep", "surveyor", "respondent"))
   sock <- .Call(rnng_protocol_open, protocol)
   is.integer(sock) && return(sock)
   if (!missing(dial)) dial(sock, url = dial, autostart = autostart)

README.Rmd

@@ -28,12 +28,12 @@ Designed for performance and reliability, the NNG library is written in C and {n
 
 Implemented scalability protocols:
 
-- Bus (routing)
+- Bus (mesh networks)
 - Pair (two-way radio)
-- Pipeline (one-way pipe)
+- Push/Pull (one-way pipeline)
 - Publisher/Subscriber (topics & broadcast)
-- Request/Reply (I ask, you answer)
-- Survey (everyone votes)
+- Request/Reply (RPC)
+- Surveyor/Respondent (voting & service discovery)
 
 Supported transports:
 
@@ -42,7 +42,7 @@ Supported transports:
 - TCP (IPv4 or IPv6)
 - WebSocket
 
-Provided web tools:
+Web tools:
 
 - ncurl - (async) http(s) client
 - stream - secure websockets client (and generic low-level socket interface)
@@ -56,7 +56,7 @@ Provided web tools:
 4. [Async and Concurrency](#async-and-concurrency)
 5. [RPC and Distributed Computing](#rpc-and-distributed-computing)
 6. [Publisher / Subscriber Model](#publisher-subscriber-model)
-7. [Surveyor / Repondent Model](#surveyor-respondent-model)
+7. [Surveyor / Respondent Model](#surveyor-respondent-model)
 8. [ncurl: (Async) HTTP Client](#ncurl-async-http-client)
 9. [stream: Websocket Client](#stream-websocket-client)
 10. [Building from source](#building-from-source)

README.md

@@ -30,12 +30,12 @@ spanning the globe.
 
 Implemented scalability protocols:
 
--   Bus (routing)
+-   Bus (mesh networks)
 -   Pair (two-way radio)
--   Pipeline (one-way pipe)
+-   Push/Pull (one-way pipeline)
 -   Publisher/Subscriber (topics & broadcast)
--   Request/Reply (I ask, you answer)
--   Survey (everyone votes)
+-   Request/Reply (RPC)
+-   Surveyor/Respondent (voting & service discovery)
 
 Supported transports:
 
@@ -44,7 +44,7 @@ Supported transports:
 -   TCP (IPv4 or IPv6)
 -   WebSocket
 
-Provided web tools:
+Web tools:
 
 -   ncurl - (async) http(s) client
 -   stream - secure websockets client (and generic low-level socket
@@ -59,7 +59,7 @@ Provided web tools:
 4.  [Async and Concurrency](#async-and-concurrency)
 5.  [RPC and Distributed Computing](#rpc-and-distributed-computing)
 6.  [Publisher / Subscriber Model](#publisher-subscriber-model)
-7.  [Surveyor / Repondent Model](#surveyor-respondent-model)
+7.  [Surveyor / Respondent Model](#surveyor-respondent-model)
 8.  [ncurl: (Async) HTTP Client](#ncurl-async-http-client)
 9.  [stream: Websocket Client](#stream-websocket-client)
 10. [Building from source](#building-from-source)
@@ -395,7 +395,7 @@ aio
 #> < recvAio >
 #>  - $data for message data
 aio$data |> str()
-#>  num [1:100000000] -1.074 0.245 0.744 -0.502 -1.666 ...
+#>  num [1:100000000] 1.5004 -0.1919 -1.5241 0.9783 0.0144 ...
 ```
 
 As `call_aio()` is blocking and will wait for completion, an alternative
@@ -547,11 +547,11 @@ ncurl("http://httpbin.org/headers")
 #>   [1] 7b 0a 20 20 22 68 65 61 64 65 72 73 22 3a 20 7b 0a 20 20 20 20 22 48 6f 73
 #>  [26] 74 22 3a 20 22 68 74 74 70 62 69 6e 2e 6f 72 67 22 2c 20 0a 20 20 20 20 22
 #>  [51] 58 2d 41 6d 7a 6e 2d 54 72 61 63 65 2d 49 64 22 3a 20 22 52 6f 6f 74 3d 31
-#>  [76] 2d 36 32 37 37 61 32 61 32 2d 34 39 36 62 38 32 38 61 34 38 63 35 65 61 66
-#> [101] 33 35 38 66 33 37 65 31 34 22 0a 20 20 7d 0a 7d 0a
+#>  [76] 2d 36 32 37 38 32 66 61 64 2d 37 30 63 35 63 31 61 30 37 39 63 66 62 66 32
+#> [101] 31 37 36 65 33 34 30 65 65 22 0a 20 20 7d 0a 7d 0a
 #> 
 #> $data
-#> [1] "{\n  \"headers\": {\n    \"Host\": \"httpbin.org\", \n    \"X-Amzn-Trace-Id\": \"Root=1-6277a2a2-496b828a48c5eaf358f37e14\"\n  }\n}\n"
+#> [1] "{\n  \"headers\": {\n    \"Host\": \"httpbin.org\", \n    \"X-Amzn-Trace-Id\": \"Root=1-62782fad-70c5c1a079cfbf2176e340ee\"\n  }\n}\n"
 ```
 
 For advanced use, supports additional HTTP methods such as POST or PUT.
@@ -567,7 +567,7 @@ res
 #>  - $raw for raw message
 
 call_aio(res)$data
-#> [1] "{\n  \"args\": {}, \n  \"data\": \"{\\\"key\\\": \\\"value\\\"}\", \n  \"files\": {}, \n  \"form\": {}, \n  \"headers\": {\n    \"Authorization\": \"Bearer APIKEY\", \n    \"Content-Length\": \"16\", \n    \"Content-Type\": \"application/json\", \n    \"Host\": \"httpbin.org\", \n    \"X-Amzn-Trace-Id\": \"Root=1-6277a2a2-6ae6efe31d378db911a099f5\"\n  }, \n  \"json\": {\n    \"key\": \"value\"\n  }, \n  \"origin\": \"78.145.225.121\", \n  \"url\": \"http://httpbin.org/post\"\n}\n"
+#> [1] "{\n  \"args\": {}, \n  \"data\": \"{\\\"key\\\": \\\"value\\\"}\", \n  \"files\": {}, \n  \"form\": {}, \n  \"headers\": {\n    \"Authorization\": \"Bearer APIKEY\", \n    \"Content-Length\": \"16\", \n    \"Content-Type\": \"application/json\", \n    \"Host\": \"httpbin.org\", \n    \"X-Amzn-Trace-Id\": \"Root=1-62782fad-7472b2c32d5af7603e86ae7d\"\n  }, \n  \"json\": {\n    \"key\": \"value\"\n  }, \n  \"origin\": \"78.145.225.121\", \n  \"url\": \"http://httpbin.org/post\"\n}\n"
 ```
 
 In this respect, it may be used as a performant and lightweight method
@@ -597,10 +597,10 @@ s
 #>  - textframes: TRUE
 
 s |> recv(keep.raw = FALSE)
-#> [1] "{\"e\":\"kline\",\"E\":1652007590579,\"s\":\"BTCUSDT\",\"k\":{\"t\":1652007540000,\"T\":1652007599999,\"s\":\"BTCUSDT\",\"i\":\"1m\",\"f\":1351258350,\"L\":1351258570,\"o\":\"34718.38000000\",\"c\":\"34726.74000000\",\"h\":\"34726.74000000\",\"l\":\"34717.06000000\",\"v\":\"3.78973000\",\"n\":221,\"x\":false,\"q\":\"131577.38153510\",\"V\":\"2.16208000\",\"Q\":\"75065.38564240\",\"B\":\"0\"}}"
+#> [1] "{\"e\":\"kline\",\"E\":1652043696064,\"s\":\"BTCUSDT\",\"k\":{\"t\":1652043660000,\"T\":1652043719999,\"s\":\"BTCUSDT\",\"i\":\"1m\",\"f\":1351814911,\"L\":1351815351,\"o\":\"34253.08000000\",\"c\":\"34279.21000000\",\"h\":\"34285.51000000\",\"l\":\"34253.07000000\",\"v\":\"21.53329000\",\"n\":441,\"x\":false,\"q\":\"737928.59980930\",\"V\":\"15.55859000\",\"Q\":\"533152.23838480\",\"B\":\"0\"}}"
 
 s |> recv(keep.raw = FALSE)
-#> [1] "{\"e\":\"kline\",\"E\":1652007592588,\"s\":\"BTCUSDT\",\"k\":{\"t\":1652007540000,\"T\":1652007599999,\"s\":\"BTCUSDT\",\"i\":\"1m\",\"f\":1351258350,\"L\":1351258593,\"o\":\"34718.38000000\",\"c\":\"34729.58000000\",\"h\":\"34729.58000000\",\"l\":\"34717.06000000\",\"v\":\"4.01301000\",\"n\":244,\"x\":false,\"q\":\"139331.29327650\",\"V\":\"2.27211000\",\"Q\":\"78886.44058120\",\"B\":\"0\"}}"
+#> [1] "{\"e\":\"kline\",\"E\":1652043698106,\"s\":\"BTCUSDT\",\"k\":{\"t\":1652043660000,\"T\":1652043719999,\"s\":\"BTCUSDT\",\"i\":\"1m\",\"f\":1351814911,\"L\":1351815367,\"o\":\"34253.08000000\",\"c\":\"34281.51000000\",\"h\":\"34285.51000000\",\"l\":\"34253.07000000\",\"v\":\"21.61695000\",\"n\":457,\"x\":false,\"q\":\"740796.49099100\",\"V\":\"15.64225000\",\"Q\":\"536020.12956650\",\"B\":\"0\"}}"
 
 close(s)
 ```