implement blocking timeouts for synchronous send/recv

Author: shikokuchuo

NEWS.md

@@ -2,12 +2,12 @@
 
 #### New Features
 
-* New 'stream' interface exposes low-level byte stream functionality in the NNG library, intended for communicating with non-NNG endpoints, including but not limited to websocket servers.
+* New `stream()` interface exposes low-level byte stream functionality in the NNG library, intended for communicating with non-NNG endpoints, including but not limited to websocket servers.
 
 #### Updates
 
-* Unified synchronous `send()` and `recv()` functions, and their async counterparts `send_aio()` and `recv_aio()`, are now S3 generics and can be used across Sockets, Contexts as well as Streams.
-* A timeout can now be specified directly using the 'block' argument for synchronous sends over a Context/Stream.
+* Unified synchronous `send()` and `recv()` functions, and their asynchronous counterparts `send_aio()` and `recv_aio()`, are now S3 generics and can be used across Sockets, Contexts and Streams.
+* Revised 'block' argument for synchronous `send()` and `recv()` allows setting a timeout for all methods.
 * `send_ctx()` and `recv_ctx()` are deprecated and will be removed in a future package version - the methods for `send()` and `recv()` should be used instead.
 
 # nanonext 0.3.0

R/sendrecv.R

@@ -5,31 +5,36 @@
 #' Send data over a connection (Socket, Context or Stream).
 #'
 #' @param con a Socket, Context or Stream.
-#' @param data an object (if mode = 'raw', a vector).
-#' @param mode whether data will be sent serialized or as a raw vector. Specify
-#'     'serial' for sending and receiving objects within R for perfect
-#'     reproducibility. Specify 'raw' for sending vectors of any type (converted
-#'     to a raw byte vector for sending) - essential when interfacing with
-#'     external applications. For Streams, 'raw' is the only choice and any other
-#'     value is ignored.
-#' @param block <Sockets> [default FALSE] logical flag whether to block until
-#'     successful or return immediately (e.g. if no connection is available).
-#'     <Contexts and Streams> [default TRUE] optionally an integer maximum time
-#'     to block in milliseconds, after which the operation will time out.
-#' @param echo [default TRUE] logical flag whether to return the raw vector of
-#'     sent data. Set to FALSE for performance-critical applications.
+#' @param data an object (a vector, if mode = 'raw').
+#' @param mode either 'serial' for sending serialised R objects, or 'raw' for
+#'     sending vectors of any type (converted to a raw byte vector for sending).
+#'     For Streams, 'raw' is the only choice and any other value is ignored. Use
+#'     'serial' for perfect reproducibility within R, although 'raw' must be used
+#'     when interfacing with external applications that do not understand R
+#'     serialisation.
+#' @param block logical TRUE to block until successful or FALSE to return
+#'     immediately even if unsuccessful  (e.g. if no connection is available),
+#'     or else an integer value specifying the maximum time to block in
+#'     milliseconds, after which the operation will time out.
+#' @param echo [default TRUE] logical TRUE to return the raw vector of sent data,
+#'     or FALSE to return an integer exit code (invisibly).
 #'
 #' @return Raw vector of sent data, or (invisibly) an integer exit code (zero on
 #'     success) if 'echo' is set to FALSE.
 #'
-#' @section Contexts: 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 scenarios.
+#' @section Blocking:
 #'
-#' @section Streams: Sending a byte stream synchronously will block if the send
-#'     is in progress and has not yet completed. Set a timeout to ensure the
-#'     function returns under all scenarios.
+#'     For Sockets: the default behaviour is non-blocking with \code{block = FALSE}.
+#'     This will return immediately with an error if the message could not be
+#'     queued for sending.
+#'
+#'     For Contexts and Streams: the default behaviour is blocking with \code{block = TRUE}.
+#'     This will wait until the send has completed. For Contexts, certain protocol /
+#'     transport combinations may limit the number of messages that can be queued
+#'     if they have yet to be received. Set a timeout in this case to ensure that
+#'     the function returns under all scenarios. As the underlying implementation
+#'     differs to that for Sockets, it is recommended to set a positive integer
+#'     value for \code{block} rather than FALSE.
 #'
 #' @examples
 #' pub <- socket("pub", dial = "inproc://nanonext")
@@ -54,7 +59,11 @@
 #' @rdname send
 #' @export
 #'
-send <- function(con, data, mode, block, echo) UseMethod("send")
+send <- function(con,
+                 data,
+                 mode = c("serial", "raw"),
+                 block,
+                 echo = TRUE) UseMethod("send")
 
 #' @rdname send
 #' @method send nanoSocket
@@ -156,12 +165,19 @@ send.nanoStream <- function(con,
 #'     specified), the received raw vector will always be returned to allow for
 #'     the data to be recovered.
 #'
-#' @section Contexts: Will block while awaiting the receive operation to complete.
-#'     Set a timeout to ensure that the function returns under all scenarios.
+#' @section Blocking:
+#'
+#'     For Sockets: the default behaviour is non-blocking with \code{block = FALSE}.
+#'     This will return immediately with an error if the message could not be
+#'     queued for sending.
 #'
-#' @section Streams: Receivng a byte stream synchronously will block while
-#'     awaiting the receive operation to complete. Set a timeout to ensure that
-#'     the function returns under all scenarios.
+#'     For Contexts and Streams: the default behaviour is blocking with \code{block = TRUE}.
+#'     This will wait until the send has completed. For Contexts, certain protocol /
+#'     transport combinations may limit the number of messages that can be queued
+#'     if they have yet to be received. Set a timeout in this case to ensure that
+#'     the function returns under all scenarios. As the underlying implementation
+#'     differs to that for Sockets, it is recommended to set a positive integer
+#'     value for \code{block} rather than FALSE.
 #'
 #' @examples
 #' s1 <- socket("bus", listen = "inproc://nanonext")
@@ -202,7 +218,7 @@ send.nanoStream <- function(con,
 recv <- function(con,
                  mode = c("serial", "character", "complex", "double",
                           "integer", "logical", "numeric", "raw"),
-                 block = FALSE,
+                 block,
                  keep.raw = TRUE,
                  ...,
                  n) UseMethod("recv")