update DESCRIPTION

Author: shikokuchuo

DESCRIPTION

@@ -5,8 +5,10 @@ Version: 0.2.0.9005
 Description: R binding for NNG (Nanomsg Next Gen), a successor to ZeroMQ. NNG is 
     a socket library providing high-performance scalability protocols,
     implementing a cross-platform standard for messaging and communications.
-    Leveraging asynchronous execution, serves as a concurrency framework for
-    building distributed applications.
+    Serves as a concurrency framework for building distributed applications,
+    utilising 'Aio' objects which return an unresolved value whilst its
+    asynchronous operation is ongoing, automatically resolving to a final value
+    once complete.
 Authors@R: 
     c(person(given = "Charlie", 
              family = "Gao",

R/nanonext-package.R

@@ -4,9 +4,11 @@
 #'
 #' R binding for NNG (Nanomsg Next Gen), a successor to ZeroMQ. NNG is a socket
 #'     library providing high-performance scalability protocols, implementing a
-#'     cross-platform standard for messaging and communications. Leveraging
-#'     asynchronous execution, serves as a concurrency framework for building
-#'     distributed applications.
+#'     cross-platform standard for messaging and communications. Serves as a
+#'     concurrency framework for building distributed applications, utilising
+#'     'Aio' objects which return an unresolved value whilst its asynchronous
+#'     operation is ongoing, automatically resolving to a final value once
+#'     complete.
 #'
 #' @section Usage notes:
 #'

README.Rmd

@@ -21,7 +21,7 @@ knitr::opts_chunk$set(
 [![R-CMD-check](https://github.com/shikokuchuo/nanonext/workflows/R-CMD-check/badge.svg)](https://github.com/shikokuchuo/nanonext/actions)
 <!-- badges: end -->
 
-R binding for NNG (Nanomsg Next Gen), a successor to ZeroMQ. NNG is a socket library providing high-performance scalability protocols, implementing a cross-platform standard for messaging and communications. Leveraging asynchronous execution, serves as a concurrency framework for building distributed applications.
+R binding for NNG (Nanomsg Next Gen), a successor to ZeroMQ. NNG is a socket library providing high-performance scalability protocols, implementing a cross-platform standard for messaging and communications. Serves as a concurrency framework for building distributed applications, utilising 'Aio' objects which return an unresolved value whilst its asynchronous operation is ongoing, automatically resolving to a final value once complete.
 
 Designed for performance and reliability, the NNG library is written in C and {nanonext} is a lightweight wrapper depending on no other packages. Provides the interface for code and processes to communicate with each other - receive data generated in Python, perform analysis in R, and send results to a C++ program – all on the same computer or on networks spanning the globe.
 
@@ -176,15 +176,26 @@ n$recv(mode = "double")
 
 {nanonext} implements true async send and receive, leveraging NNG as a massively-scaleable concurrency framework.
 
-`send_aio()` and `recv_aio()` functions return immediately but perform their operations async.
-
 ```{r async}
 library(nanonext)
 s1 <- socket("pair", listen = "inproc://nano")
 s2 <- socket("pair", dial = "inproc://nano")
 
 ```
 
+`send_aio()` and `recv_aio()` functions return immediately with an 'Aio' object, but perform their operations async.
+
+An 'Aio' object returns an unresolved value whilst its asynchronous operation is ongoing, automatically resolving to a final value once complete.
+
+```{r async4}
+
+# an async receive is requested, but no mesages are waiting (yet to be sent)
+msg <- recv_aio(s2)
+msg
+msg$data
+
+```
+
 For a 'sendAio' object, the result is stored at `$result`.
 
 ```{r async2}
@@ -203,36 +214,26 @@ For a 'recvAio' object, the message is stored at `$data`, and the raw message at
 
 ```{r async3}
 
-msg <- recv_aio(s2)
-msg
+# now that a message has been sent, the 'recvAio' automatically resolves
 msg$data
 msg$raw
 
 ```
 
-If the async operation is yet to complete, an 'unresolved' logical NA value will be returned. 
-
-```{r async4}
+Auxiliary function `unresolved()` may be used in control flow statements to perform actions which depend on resolution of the Aio, both before and after. This means there is no need to actually wait (block) for an Aio to resolve, as the example below demonstrates.
 
-# an async receive is requested, but no mesages are waiting (yet to be sent)
+```{r async5}
 
 msg <- recv_aio(s2)
-msg$data
-
-```
-
-Auxiliary function `unresolved()` can be used in control flow statements.
-
-```{r async5}
 
 # unresolved() queries for resolution itself so no need to use it again within the while clause
-
 while (unresolved(msg)) {
   # do stuff before checking resolution again
   send_aio(s1, "resolved")
   cat("unresolved")
 }
 
+# perform actions which depend on the Aio value outside the while loop
 msg$data
 ```
 
@@ -282,6 +283,7 @@ aio <- request(ctxq, data = 1e8, recv_mode = "double", keep.raw = FALSE)
 ```
 
 At this point, the client can run additional code concurrent with the server processing the request. 
+
 ```{r rpcclient2}
 # do more...
 ```

README.md

@@ -15,8 +15,10 @@ badge](https://shikokuchuo.r-universe.dev/badges/nanonext?color=3f72af)](https:/
 R binding for NNG (Nanomsg Next Gen), a successor to ZeroMQ. NNG is a
 socket library providing high-performance scalability protocols,
 implementing a cross-platform standard for messaging and communications.
-Leveraging asynchronous execution, serves as a concurrency framework for
-building distributed applications.
+Serves as a concurrency framework for building distributed applications,
+utilising ‘Aio’ objects which return an unresolved value whilst its
+asynchronous operation is ongoing, automatically resolving to a final
+value once complete.
 
 Designed for performance and reliability, the NNG library is written in
 C and {nanonext} is a lightweight wrapper depending on no other
@@ -223,15 +225,30 @@ n$recv(mode = "double")
 {nanonext} implements true async send and receive, leveraging NNG as a
 massively-scaleable concurrency framework.
 
-`send_aio()` and `recv_aio()` functions return immediately but perform
-their operations async.
-
 ``` r
 library(nanonext)
 s1 <- socket("pair", listen = "inproc://nano")
 s2 <- socket("pair", dial = "inproc://nano")
 ```
 
+`send_aio()` and `recv_aio()` functions return immediately with an ‘Aio’
+object, but perform their operations async.
+
+An ‘Aio’ object returns an unresolved value whilst its asynchronous
+operation is ongoing, automatically resolving to a final value once
+complete.
+
+``` r
+# an async receive is requested, but no mesages are waiting (yet to be sent)
+msg <- recv_aio(s2)
+msg
+#> < recvAio >
+#>  - $data for message data
+#>  - $raw for raw message
+msg$data
+#> < unresolved: logi NA >
+```
+
 For a ‘sendAio’ object, the result is stored at `$result`.
 
 ``` r
@@ -251,11 +268,7 @@ For a ‘recvAio’ object, the message is stored at `$data`, and the raw
 message at `$raw` (if kept).
 
 ``` r
-msg <- recv_aio(s2)
-msg
-#> < recvAio >
-#>  - $data for message data
-#>  - $raw for raw message
+# now that a message has been sent, the 'recvAio' automatically resolves
 msg$data
 #>   a b
 #> 1 1 2
@@ -271,30 +284,23 @@ msg$raw
 #> [201] 00 fe
 ```
 
-If the async operation is yet to complete, an ‘unresolved’ logical NA
-value will be returned.
+Auxiliary function `unresolved()` may be used in control flow statements
+to perform actions which depend on resolution of the Aio, both before
+and after. This means there is no need to actually wait (block) for an
+Aio to resolve, as the example below demonstrates.
 
 ``` r
-# an async receive is requested, but no mesages are waiting (yet to be sent)
-
 msg <- recv_aio(s2)
-msg$data
-#> < unresolved: logi NA >
-```
 
-Auxiliary function `unresolved()` can be used in control flow
-statements.
-
-``` r
 # unresolved() queries for resolution itself so no need to use it again within the while clause
-
 while (unresolved(msg)) {
   # do stuff before checking resolution again
   send_aio(s1, "resolved")
   cat("unresolved")
 }
 #> unresolved
 
+# perform actions which depend on the Aio value outside the while loop
 msg$data
 #> [1] "resolved"
 ```
@@ -365,7 +371,7 @@ aio
 #> < recvAio >
 #>  - $data for message data
 str(aio$data)
-#>  num [1:100000000] 1.0964 0.2245 -0.0617 -1.2121 -0.2527 ...
+#>  num [1:100000000] -0.0948 0.4204 0.031 1.9219 -0.23 ...
 ```
 
 As `call_aio()` is blocking and will wait for completion, an alternative
@@ -400,37 +406,37 @@ an environment variable `NANONEXT_LOG`.
 
 ``` r
 logging(level = "info")
-#> 2022-03-04 23:52:52 [ log level ] set to: info
+#> 2022-03-05 14:09:43 [ log level ] set to: info
 
 pub <- socket("pub", listen = "inproc://nanobroadcast")
-#> 2022-03-04 23:52:52 [ sock open ] id: 9 | protocol: pub 
-#> 2022-03-04 23:52:52 [ list start ] sock: 9 | url: inproc://nanobroadcast
+#> 2022-03-05 14:09:43 [ sock open ] id: 9 | protocol: pub 
+#> 2022-03-05 14:09:43 [ list start ] sock: 9 | url: inproc://nanobroadcast
 sub <- socket("sub", dial = "inproc://nanobroadcast")
-#> 2022-03-04 23:52:52 [ sock open ] id: 10 | protocol: sub 
-#> 2022-03-04 23:52:52 [ dial start ] sock: 10 | url: inproc://nanobroadcast
+#> 2022-03-05 14:09:43 [ sock open ] id: 10 | protocol: sub 
+#> 2022-03-05 14:09:43 [ dial start ] sock: 10 | url: inproc://nanobroadcast
 
 sub |> subscribe(topic = "examples")
-#> 2022-03-04 23:52:52 [ subscribe ] sock: 10 | topic: examples
+#> 2022-03-05 14:09:43 [ subscribe ] sock: 10 | topic: examples
 pub |> send(c("examples", "this is an example"), mode = "raw", echo = FALSE)
 sub |> recv(mode = "character", keep.raw = FALSE)
 #> [1] "examples"           "this is an example"
 
 pub |> send(c("other", "this other topic will not be received"), mode = "raw", echo = FALSE)
 sub |> recv(mode = "character", keep.raw = FALSE)
-#> 2022-03-04 23:52:52 [ 8 ] Try again
+#> 2022-03-05 14:09:43 [ 8 ] Try again
 
 # specify NULL to subscribe to ALL topics
 sub |> subscribe(topic = NULL)
-#> 2022-03-04 23:52:52 [ subscribe ] sock: 10 | topic: ALL
+#> 2022-03-05 14:09:43 [ subscribe ] sock: 10 | topic: ALL
 pub |> send(c("newTopic", "this is a new topic"), mode = "raw", echo = FALSE)
 sub |> recv("character", keep.raw = FALSE)
 #> [1] "newTopic"            "this is a new topic"
 
 sub |> unsubscribe(topic = NULL)
-#> 2022-03-04 23:52:52 [ unsubscribe ] sock: 10 | topic: ALL
+#> 2022-03-05 14:09:43 [ unsubscribe ] sock: 10 | topic: ALL
 pub |> send(c("newTopic", "this topic will now not be received"), mode = "raw", echo = FALSE)
 sub |> recv("character", keep.raw = FALSE)
-#> 2022-03-04 23:52:52 [ 8 ] Try again
+#> 2022-03-05 14:09:43 [ 8 ] Try again
 
 # however the topics explicitly subscribed to are still received
 pub |> send(c("examples", "this example will still be received"), mode = "raw", echo = FALSE)
@@ -439,7 +445,7 @@ sub |> recv(mode = "character", keep.raw = FALSE)
 
 # set logging level back to the default of errors only
 logging(level = "error")
-#> 2022-03-04 23:52:52 [ log level ] set to: error
+#> 2022-03-05 14:09:43 [ log level ] set to: error
 
 close(pub)
 close(sub)
@@ -490,7 +496,7 @@ aio2$data
 # after the survey expires, the second resolves into a timeout error
 Sys.sleep(0.5)
 aio2$data
-#> 2022-03-04 23:52:53 [ 5 ] Timed out
+#> 2022-03-05 14:09:44 [ 5 ] Timed out
 #> 'errorValue' int 5
 
 close(sur)
@@ -516,11 +522,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 32 32 61 36 35 35 2d 33 31 31 32 32 33 61 39 35 35 37 35 62 36 31
-#> [101] 39 33 66 36 61 63 63 65 64 22 0a 20 20 7d 0a 7d 0a
+#>  [76] 2d 36 32 32 33 36 66 32 38 2d 31 62 61 30 35 65 31 63 36 34 66 63 63 63 31
+#> [101] 39 34 65 32 37 33 62 62 38 22 0a 20 20 7d 0a 7d 0a
 #> 
 #> $data
-#> [1] "{\n  \"headers\": {\n    \"Host\": \"httpbin.org\", \n    \"X-Amzn-Trace-Id\": \"Root=1-6222a655-311223a95575b6193f6acced\"\n  }\n}\n"
+#> [1] "{\n  \"headers\": {\n    \"Host\": \"httpbin.org\", \n    \"X-Amzn-Trace-Id\": \"Root=1-62236f28-1ba05e1c64fccc194e273bb8\"\n  }\n}\n"
 ```
 
 For advanced use, supports additional HTTP methods such as POST or PUT.