more consistency to function names, expand readme, push experimental timer

Author: shikokuchuo

DESCRIPTION

@@ -3,8 +3,10 @@ Type: Package
 Title: NNG (Nanomsg Next Gen) Lightweight Messaging Library
 Version: 0.1.0.9000
 Description: R binding for NNG (Nanomsg Next Gen), a successor to ZeroMQ. NNG is 
-    a socket library providing high-performance scalability protocols, or common
-    communication patterns, the basic building blocks for distributed systems.
+    a socket library providing high-performance scalability protocols,
+    implementing a cross-platform standard for messaging and communications. 
+    Serves as a concurrency framework that can be used for building distributed 
+    systems.
 Authors@R: 
     c(person(given = "Charlie", 
              family = "Gao",

NAMESPACE

@@ -21,13 +21,8 @@ S3method(setopt,nanoListener)
 S3method(setopt,nanoSocket)
 S3method(start,nanoDialer)
 S3method(start,nanoListener)
-export(aio_call)
-export(aio_stop)
+export(call_aio)
 export(context)
-export(ctx_recv)
-export(ctx_rep)
-export(ctx_req)
-export(ctx_send)
 export(dial)
 export(listen)
 export(nano)
@@ -37,12 +32,17 @@ export(nng_timer)
 export(nng_version)
 export(recv)
 export(recv_aio)
+export(recv_ctx)
 export(recv_vec)
+export(reply)
+export(request)
 export(send)
 export(send_aio)
+export(send_ctx)
 export(send_vec)
 export(setopt)
 export(socket)
+export(stop_aio)
 export(subscribe)
 export(unsubscribe)
 importFrom(stats,start)

NEWS.md

@@ -2,17 +2,26 @@
 
 #### New Features
 
-* Implements full async I/O capabilities - `send_aio()` and `recv_aio()` now return Aio objects, for which the results may be called using `aio_call()`.
-* New `ctx_rep()` and `ctx_req()` functions implement the full logic of an RPC server/client. Designed to be run in separate processes, the server will await data and apply an arbitrary function before returning a result, whilst the client will send data to the server and await a response.
+* Implements full async I/O capabilities 
+  + `send_aio()` and `recv_aio()` now return Aio objects, for which the results may be called using `call_aio()`.
+* New `request()` and `reply()` functions implement the full logic of an RPC client/server. 
+  + Designed to be run in separate processes, the reply server will await data and apply a function before returning a result.
+  + The request client performs an async request to the server and returns immediately with an Aio.
+  + This allows processes to run concurrently on the client and server.
 * New `ncurl()` minimalistic http(s) client.
-* Allows setting the environment variable 'NANONEXT_TLS' prior to package installation to enable TLS where the system NNG library has been built with TLS support (using Mbed TLS).
+* Allows setting the environment variable 'NANONEXT_TLS' prior to package installation
+  + Enables TLS where the system NNG library has been built with TLS support (using Mbed TLS).
 * New `nng_timer()` utility as a demonstration of NNG's multithreading capabilities.
 
 #### Updates
 
-* Successful starts of dialers/listeners and successful close operations no longer print a message to stdout for less verbosity by default. The state of respective objects can always be queried by their state attribute using `$state`
-* All send and receive functions, e.g. `send()`/`recv()`, gain a revised 'mode' argument. This now permits the choice of whether to use R serialization, consolidating the functionality of the '_vec' series of functions.
+* Dialer/listener starts and close operations no longer print a message to stderr when successful for less verbosity by default.
+  + The state of respective objects can always be queried using `$state`
+* All send and receive functions, e.g. `send()`/`recv()`, gain a revised 'mode' argument. 
+  + This now permits R serialization as an option, consolidating the functionality of the '_vec' series of functions.
 * Functions 'send_vec' and 'recv_vec' are deprecated and will be removed in a future release.
+* Functions 'ctx_send' and 'ctx_recv' have been renamed `send_ctx()` and `recv_ctx()` for consistency.
+* The `$socket_close()` method of nano objects has been renamed `$close()` to better align with the functional API.
 
 # nanonext 0.1.0
 

R/aio.R

@@ -3,15 +3,17 @@
 #' Call the Result of an Asynchronous AIO Operation
 #'
 #' Retrieve the result of an asynchronous AIO operation. Will wait for the AIO
-#'     operation (blocking) if not yet complete. Once the result is retrieved,
-#'     the Aio is deallocated and further actions cannot be performed on it.
+#'     operation to complete (blocking) if this is still in progress.
 #'
 #' @param aio An Aio (object of class 'sendAio' or 'recvAio').
 #'
-#' @return The original Aio object (invisibly).
+#' @return The passed Aio object (invisibly).
 #'
-#' @details For a 'sendAio', the send result will be attached to the Aio in
-#'     \code{$result}. This will be zero on success.
+#' @details To access the values directly, use for example on a sendAio 'x':
+#'     \code{call_aio(x)$result}.
+#'
+#'     For a 'sendAio', the send result will be attached to the Aio in \code{$result}.
+#'     This will be zero on success.
 #'
 #'     For a 'recvAio', the received raw vector will be attached in \code{$raw}
 #'     (unless 'keep.raw' was set to FALSE when receiving), and the converted R
@@ -21,62 +23,71 @@
 #'     the received raw vector will always be saved in \code{$raw} to allow the
 #'     data to be recovered.
 #'
+#'     Once the result is retrieved, the Aio is deallocated and only the result
+#'     is stored in the Aio object.
+#'
 #' @examples
 #' s1 <- socket("pair", listen = "inproc://nanonext")
 #' s2 <- socket("pair", dial = "inproc://nanonext")
 #'
 #' res <- send_aio(s1, data.frame(a = 1, b = 2), timeout = 100)
 #' res
-#' aio_call(res)
+#' call_aio(res)
 #' res
 #' res$result
 #'
 #' res <- recv_aio(s2, timeout = 100)
 #' res
-#' aio_call(res)$data
+#' call_aio(res)$data
 #' res
 #'
 #' close(s1)
 #' close(s2)
 #'
 #' @export
 #'
-aio_call <- function(aio) {
+call_aio <- function(aio) {
 
-  if (inherits(aio, "recvAio")) {
+  if (length(.subset2(aio, "aio"))) {
 
-    mode <- aio[["callparams"]][[1L]]
-    keep.raw <- aio[["callparams"]][[2L]]
-    res <- .Call(rnng_aio_get_msg, aio[["aio"]])
-    if (keep.raw) aio[["raw"]] <- res
-    is.integer(res) && {
-      message(res, " : ", nng_error(res))
-      return(invisible(aio))
-    }
-    on.exit(expr = {
-      aio[["raw"]] <- res
-      return(invisible(aio))
-    })
-    data <- switch(mode,
-                   serial = unserialize(connection = res),
-                   character = (r <- readBin(con = res, what = mode, n = length(res)))[r != ""],
-                   raw = res,
-                   readBin(con = res, what = mode, n = length(res)))
-    aio[["data"]] <- data
-    on.exit(expr = NULL)
-    invisible(aio)
+    if (inherits(aio, "recvAio")) {
 
-  } else if (inherits(aio, "sendAio")) {
+      mode <- .subset2(aio, "callparams")[[1L]]
+      keep.raw <- .subset2(aio, "callparams")[[2L]]
+      res <- .Call(rnng_aio_get_msg, .subset2(aio, "aio"))
+      if (keep.raw) aio[["raw"]] <- res
+      is.integer(res) && {
+        message(res, " : ", nng_error(res))
+        return(invisible(aio))
+      }
+      on.exit(expr = {
+        aio[["raw"]] <- res
+        return(invisible(aio))
+      })
+      data <- switch(mode,
+                     serial = unserialize(connection = res),
+                     character = (r <- readBin(con = res, what = mode, n = length(res)))[r != ""],
+                     raw = res,
+                     readBin(con = res, what = mode, n = length(res)))
+      aio[["data"]] <- data
+      on.exit(expr = NULL)
+      rm("aio", envir = aio)
+      rm("callparams", envir = aio)
+      invisible(aio)
 
-    res <- .Call(rnng_aio_result, aio[["aio"]])
-    aio[["result"]] <- res
-    if (res) {
-      message(res, " : ", nng_error(res))
+    } else if (inherits(aio, "sendAio")) {
+      res <- .Call(rnng_aio_result, .subset2(aio, "aio"))
+      aio[["result"]] <- res
+      rm("aio", envir = aio)
+      if (res) {
+        message(res, " : ", nng_error(res))
+      }
     }
+
     invisible(aio)
 
   } else {
-    stop("this function may only be used on an Aio")
+    invisible(aio)
   }
 
 }
@@ -96,9 +107,9 @@ aio_call <- function(aio) {
 #'
 #' @export
 #'
-aio_stop <- function(aio) {
+stop_aio <- function(aio) {
 
-  invisible(.Call(rnng_aio_stop, aio[["aio"]]))
+  invisible(.Call(rnng_aio_stop, .subset2(aio, "aio")))
 
 }