Add 'mode' to send/recv, deprecate _vec series of functions

Author: shikokuchuo

NEWS.md

@@ -2,6 +2,7 @@
 
 * Add `ncurl()` minimalistic http(s) client.
 * Allow 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).
+* All send and receive functions, e.g. `send()`/`recv()`, gain the argument 'mode' for choosing whether or not to serialize R objects, consolidating the functionality of the '_vec' series of functions, e.g. send_vec()/recv_vec(). The '_vec' series of functions is consequently deprecated. 
 
 # nanonext 0.1.0
 

R/context.R

@@ -52,8 +52,7 @@ context <- function(socket) {
 #' Send over Context (Async)
 #'
 #' Send any number of R objects asynchronously over a Context, with the ability
-#'     to set (optional) send timeouts. For sending and receiving within R -
-#'     objects are sent serialized to ensure perfect reproducibility.
+#'     to set send timeouts.
 #'
 #' @param context a Context.
 #' @inheritParams send_aio
@@ -63,7 +62,7 @@ context <- function(socket) {
 #' @details Will block if the send is in progress and has not yet completed -
 #'     certain protocol / transport combinations may limit the number of messages
 #'     that can be queued if they have yet to be received. Set a timeout to
-#'     ensure the function returns under all conditions.
+#'     ensure the function returns under all scenarios.
 #'
 #' @examples
 #' req <- socket("req", listen = "inproc://nanonext")
@@ -73,56 +72,23 @@ context <- function(socket) {
 #' out <- ctx_send(ctx, data.frame(a = 1, b = 2), data.frame(c = 3, d = 4), timeout = 100)
 #' out
 #'
-#' close(req)
-#' close(rep)
-#'
-#' @export
-#'
-ctx_send <- function(context, ..., timeout) {
-
-  if (missing(timeout)) timeout <- -2L
-  data <- lapply(list(...), serialize, connection = NULL)
-  res <- .Call(rnng_ctx_send, context, data, timeout)
-  for (i in seq_along(res)) {
-    if (res[i]) message("[", i, "] ", res[i], " : ", nng_error(res[i]))
-  }
-  invisible(res)
-
-}
-
-#' Send Vector over Context (Async)
-#'
-#' Send any number of R vectors asynchronously over a Context, with the ability
-#'     to set (optional) send timeouts. Data will be sent as binary without R
-#'     serialisation, hence appropriate for interfacing with external programs.
-#'
-#' @inheritParams ctx_send
-#' @inheritParams send_vec_aio
+#' msg <- recv_aio(rep, n = 2L, timeout = 100)
 #'
-#' @return A vector of zeros (invisibly) on success.
-#'
-#' @details Will block if the send is in progress and has not yet completed -
-#'     certain protocol / transport combinations may limit the number of messages
-#'     that can be queued if they have yet to be received. Set a timeout to
-#'     ensure the function returns under all conditions.
-#'
-#' @examples
-#' req <- socket("req", listen = "inproc://nanonext")
-#' rep <- socket("rep", dial = "inproc://nanonext")
-#'
-#' ctx <- context(req)
-#' out <- ctx_send_vec(ctx, c(1.1, 2.2), c(3.3, 4.4), timeout = 1000)
+#' out <- ctx_send(ctx, c(1.1, 2.2), c(3.3, 4.4), mode = "raw", timeout = 100)
 #' out
 #'
 #' close(req)
 #' close(rep)
 #'
 #' @export
 #'
-ctx_send_vec <- function(context, ..., timeout) {
+ctx_send <- function(context, ..., mode = c("serial", "raw"), timeout) {
 
+  mode <- match.arg(mode)
   if (missing(timeout)) timeout <- -2L
-  data <- lapply(list(...), writeBin, con = raw())
+  data <- switch(mode,
+                 serial = lapply(list(...), serialize, connection = NULL),
+                 raw = lapply(list(...), writeBin, con = raw()))
   res <- .Call(rnng_ctx_send, context, data, timeout)
   for (i in seq_along(res)) {
     if (res[i]) message("[", i, "] ", res[i], " : ", nng_error(res[i]))
@@ -133,26 +99,26 @@ ctx_send_vec <- function(context, ..., timeout) {
 
 #' Receive over Context (Async)
 #'
-#' Receive serialised data asynchronously over a Context (with ability to set a
-#'     timeout). For sending and receiving within R.
+#' Receive any number of R objects asynchronously over a Context, with the
+#'     ability to set receive timeouts.
 #'
 #' @inheritParams ctx_send
 #' @inheritParams recv_aio
 #'
 #' @return Named list of 2 elements: 'raw' containing a list of received raw
-#'     vectors and 'data' containing a list of unserialised R objects, or else a
-#'     list of unserialised R objects if keep.raw is set to FALSE.
+#'     vectors and 'data' containing a list of converted R objects, or else a
+#'     list of converted R objects if keep.raw is set to FALSE.
 #'
 #'     Note: a list of lists is always returned even when n = 1. To access the
 #'     first raw element, for example, use \code{$raw[[1]]} and the first data
 #'     element use \code{$data[[1]]}.
 #'
 #' @details Async recv will block while awaiting all 'n' messages to arrive. Set
-#'     a timeout to ensure that the function returns under all conditions.
+#'     a timeout to ensure that the function returns under all scenarios.
 #'
-#'     In case of an error in unserialisation (e.g. the data was not sent
-#'     serialised), the function will still return a list of received raw vectors
-#'     to allow the data to be recovered.
+#'     In case of an error in unserialisation or data conversion, the function
+#'     will still return a list of received raw vectors to allow the data to be
+#'     recovered.
 #'
 #' @examples
 #' req <- socket("req", listen = "inproc://nanonext")
@@ -163,32 +129,80 @@ ctx_send_vec <- function(context, ..., timeout) {
 #' ctx_send(ctxq, data.frame(a = 1, b = 2), data.frame(c = 3, d = 4), timeout = 100)
 #' ctx_recv(ctxp, 2L, timeout = 100)
 #'
+#' ctx_send(ctxq, c(1.1, 2.2), c(3.3, 4.4), mode = "raw", timeout = 100)
+#' ctx_recv(ctxp, n = 2L, mode = "double", timeout = 100)
+#'
 #' close(req)
 #' close(rep)
 #'
 #' @export
 #'
-ctx_recv <- function(context, n = 1L, timeout, keep.raw = TRUE) {
+ctx_recv <- function(context,
+                     n = 1L,
+                     mode = c("serial", "character", "complex", "double",
+                              "integer", "logical", "numeric", "raw"),
+                     timeout,
+                     keep.raw = TRUE) {
 
+  mode <- match.arg(mode)
   if (missing(timeout)) timeout <- -2L
   res <- .Call(rnng_ctx_recv, context, n, timeout)
   on.exit(expr = return(res))
   data <- vector(mode = "list", length = length(res))
   for (i in seq_along(res)) {
     if (is.integer(res[[i]])) message("[", i, "] ", res[[i]], " : ", nng_error(res[[i]])) else
-      data[[i]] <- unserialize(res[[i]])
+      data[[i]] <- switch(mode,
+                          serial = unserialize(res[[i]]),
+                          character = (r <- readBin(con = res[[i]], what = mode, n = length(res[[i]])))[r != ""],
+                          raw = res[[i]],
+                          readBin(con = res[[i]], what = mode, n = length(res[[i]])))
   }
   on.exit(expr = NULL)
   if (missing(keep.raw) || isTRUE(keep.raw)) list(raw = res, data = data) else data
 
 }
 
+# Deprecated - may be removed at any time - do not use -------------------------
+
+#' Send Vector over Context (Async)
+#'
+#' DEPRECATED [Use ctx_send specifying mode = 'raw'] Send any number of R vectors
+#'     asynchronously over a Context, with the ability to set (optional) send
+#'     timeouts. Data will be sent as binary without R serialisation, hence
+#'     appropriate for interfacing with external programs.
+#'
+#' @inheritParams ctx_send
+#' @inheritParams send_vec_aio
+#'
+#' @return A vector of zeros (invisibly) on success.
+#'
+#' @details Will block if the send is in progress and has not yet completed -
+#'     certain protocol / transport combinations may limit the number of messages
+#'     that can be queued if they have yet to be received. Set a timeout to
+#'     ensure the function returns under all conditions.
+#'
+#' @keywords internal
+#' @export
+#'
+ctx_send_vec <- function(context, ..., timeout) {
+
+  if (missing(timeout)) timeout <- -2L
+  data <- lapply(list(...), writeBin, con = raw())
+  res <- .Call(rnng_ctx_send, context, data, timeout)
+  for (i in seq_along(res)) {
+    if (res[i]) message("[", i, "] ", res[i], " : ", nng_error(res[i]))
+  }
+  invisible(res)
+
+}
+
 #' Receive Vector over Context (Async)
 #'
-#' Receive vector data asynchronously over a Context (with ability to set a
-#'     timeout). The counterpart to \code{\link{ctx_send_vec}}, data will be
-#'     re-created from the raw vector according to the specified mode. Can be
-#'     used when interfacing with external programs.
+#' DEPRECATED [Use ctx_recv specifying mode] Receive vector data asynchronously
+#'     over a Context (with ability to set a timeout). The counterpart to
+#'     \code{\link{ctx_send_vec}}, data will be re-created from the raw vector
+#'     according to the specified mode. Can be used when interfacing with
+#'     external programs.
 #'
 #' @inheritParams ctx_recv
 #' @inheritParams recv_vec
@@ -205,18 +219,7 @@ ctx_recv <- function(context, n = 1L, timeout, keep.raw = TRUE) {
 #' @details Async recv will block while awaiting all 'n' messages to arrive. Set
 #'     a timeout to ensure that the function returns under all conditions.
 #'
-#' @examples
-#' req <- socket("req", listen = "inproc://nanonext")
-#' rep <- socket("rep", dial = "inproc://nanonext")
-#'
-#' ctxq <- context(req)
-#' ctxp <- context(rep)
-#' ctx_send_vec(ctxq, c(1.1, 2.2), c(3.3, 4.4), timeout = 100)
-#' ctx_recv_vec(ctxp, "double", 2L, timeout = 100)
-#'
-#' close(req)
-#' close(rep)
-#'
+#' @keywords internal
 #' @export
 #'
 ctx_recv_vec <- function(context,

R/nano.R

@@ -43,8 +43,8 @@
 #' nano$listener
 #'
 #' nano1 <- nano("bus", dial = "inproc://nanonext")
-#' nano$send_vec("example test")
-#' nano1$recv_vec("character")
+#' nano$send("example test", mode = "raw")
+#' nano1$recv("character")
 #'
 #' nano$socket_close()
 #' nano1$socket_close()
@@ -90,51 +90,36 @@ nano <- function(protocol = c("pair", "bus", "push", "pull", "req", "rep",
                                autostart = TRUE) listen(nano,
                                                         url = url,
                                                         autostart = autostart)
-  nano[["recv"]] <- function(block = FALSE, keep.raw = TRUE) recv(socket,
-                                                                  block = block,
-                                                                  keep.raw = keep.raw)
+  nano[["recv"]] <- function(mode = c("serial", "character", "complex", "double",
+                                      "integer", "logical", "numeric", "raw"),
+                             block = FALSE,
+                             keep.raw = TRUE) recv(socket,
+                                                   mode = mode,
+                                                   block = block,
+                                                   keep.raw = keep.raw)
   nano[["recv_aio"]] <- function(n = 1L,
+                                 mode = c("serial", "character", "complex", "double",
+                                          "integer", "logical", "numeric", "raw"),
                                  timeout,
                                  keep.raw = TRUE) recv_aio(socket,
                                                            n = n,
-                                                           timeout = timeout,
-                                                           keep.raw = keep.raw)
-  nano[["recv_vec"]] <- function(mode = c("character", "complex", "double", "integer",
-                                          "logical", "numeric", "raw"),
-                                 block = FALSE,
-                                 keep.raw = TRUE) recv_vec(socket,
                                                            mode = mode,
-                                                           block = block,
+                                                           timeout = timeout,
                                                            keep.raw = keep.raw)
-  nano[["recv_vec_aio"]] <- function(mode = c("character", "complex", "double", "integer",
-                                              "logical", "numeric", "raw"),
-                                     n = 1L,
-                                     timeout,
-                                     keep.raw = TRUE) recv_vec_aio(socket,
-                                                                   mode = mode,
-                                                                   n = n,
-                                                                   timeout = timeout,
-                                                                   keep.raw = keep.raw)
   nano[["send"]] <- function(data,
+                             mode = c("serial", "raw"),
                              block = FALSE,
                              echo = TRUE) send(socket,
                                                data = data,
+                                               mode = mode,
                                                block = block,
                                                echo = echo)
   nano[["send_aio"]] <- function(...,
+                                 mode = c("serial", "raw"),
                                  timeout) send_aio(socket,
                                                    ...,
+                                                   mode = mode,
                                                    timeout = timeout)
-  nano[["send_vec"]] <- function(data,
-                                 block = FALSE,
-                                 echo = TRUE) send_vec(socket,
-                                                       data = data,
-                                                       block = block,
-                                                       echo = echo)
-  nano[["send_vec_aio"]] <- function(...,
-                                     timeout) send_vec_aio(socket,
-                                                           ...,
-                                                           timeout = timeout)
   nano[["socket_close"]] <- function() close(socket)
   nano[["socket_setopt"]] <- function(type = c("bool", "int", "ms", "size",
                                                "string", "uint64"),