ack timeout (compat code path); reorg cv docs

Author: shikokuchuo

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: nanonext
 Type: Package
 Title: NNG (Nanomsg Next Gen) Lightweight Messaging Library
-Version: 0.10.2.9020
+Version: 0.10.2.9021
 Description: R binding for NNG (Nanomsg Next Gen), a successor to ZeroMQ. NNG is
     a socket library implementing 'Scalability Protocols', a reliable,
     high-performance standard for common communications patterns including

NEWS.md

@@ -1,4 +1,4 @@
-# nanonext 0.10.2.9020 (development)
+# nanonext 0.10.2.9021 (development)
 
 #### New Features
 

R/sync.R

@@ -18,10 +18,20 @@
 
 #' Condition Variables
 #'
-#' Creates a new condition variable (protected by a mutex internal to the
-#'     object).
+#' \code{cv} creates a new condition variable (protected by a mutex internal to
+#'     the object).
 #'
-#' @return A 'conditionVariable' object.
+#' @return For \strong{cv}: a 'conditionVariable' object.
+#'
+#'     For \strong{wait} and \strong{until}: (invisibly) logical TRUE, or else
+#'     FALSE if a flag has been set.
+#'
+#'     For \strong{.until}: (invisibly) logical TRUE if signalled, or else FALSE
+#'     if the timeout was reached.
+#'
+#'     For \strong{cv_value}: integer value of the condition variable.
+#'
+#'     For \strong{cv_reset} and \strong{cv_signal}: zero (invisibly).
 #'
 #' @details Pass the 'conditionVariable' to the signalling forms of the
 #'     asynchronous receive functions: \code{\link{recv_aio_signal}} or
@@ -33,7 +43,7 @@
 #'     incrementing it by 1.
 #'
 #'     This will cause the R execution thread waiting on the condition variable
-#'     using \code{\link{wait}} or \code{\link{until}} to wake and continue.
+#'     using \code{wait} or \code{until} to wake and continue.
 #'
 #'     For argument 'msec', non-integer values will be coerced to integer.
 #'     Non-numeric input will be ignored and return immediately.
@@ -42,97 +52,74 @@
 #'
 #'     The condition internal to this 'conditionVariable' maintains a state
 #'     (value). Each signal increments the value by 1. Each time
-#'     \code{\link{wait}} or \code{\link{until}} returns (apart from due to
-#'     timeout), the value is decremented by 1.
+#'     \code{wait} or \code{until} returns (apart from due to timeout), the
+#'     value is decremented by 1.
 #'
-#'     The internal condition may be inspected at any time using
-#'     \code{\link{cv_value}} and reset using \code{\link{cv_reset}}. This
-#'     affords a high degree of flexibility in designing complex concurrent
-#'     applications.
+#'     The internal condition may be inspected at any time using \code{cv_value}
+#'     and reset using \code{cv_reset}. This affords a high degree of
+#'     flexibility in designing complex concurrent applications.
 #'
 #' @section Flag:
 #'
 #'     The condition variable also contains a flag that certain signalling
 #'     functions such as \code{\link{pipe_notify}} can set. When this flag has
-#'     been set, all subsequent \code{\link{wait}} calls will return logical
-#'     FALSE instead of TRUE.
+#'     been set, all subsequent \code{wait} calls will return logical FALSE
+#'     instead of TRUE.
 #'
 #'     Note that the flag is not automatically reset, but may be reset manually
-#'     using \code{\link{cv_reset}}.
+#'     using \code{cv_reset}.
 #'
 #' @examples
 #' cv <- cv()
-#' cv
 #'
 #' @export
 #'
 cv <- function() .Call(rnng_cv_alloc)
 
-#' Wait / Until
+#' Condition Variables - Wait
 #'
 #' \code{wait} waits on a condition being signalled by completion of an
-#'     asynchronous receive.
+#'     asynchronous receive or pipe event.
 #'
 #' @param cv a 'conditionVariable' object.
 #'
-#' @return For \strong{wait} and \strong{until}: (invisibly) logical TRUE, or
-#'     else FALSE if a flag has been set.
-#'
-#'     For \strong{.until}: (invisibly) logical TRUE if signalled, or else FALSE
-#'     if the timeout was reached.
-#'
-#' @details These synchronisation primitives take a 'conditionVariable'. See
-#'     \code{\link{cv}} for further details of how the condition and flag
-#'     operates.
-#'
 #' @examples
-#' cv <- cv()
-#'
 #' # wait(cv) # uncommenting will block until the cv is signalled
 #'
+#' @rdname cv
 #' @export
 #'
 wait <- function(cv) invisible(.Call(rnng_cv_wait, cv))
 
-#' Until
+#' Condition Variables - Until
 #'
 #' \code{until} waits until a future time on a condition being signalled by
-#'     completion of an asynchronous receive.
+#'     completion of an asynchronous receive or pipe event.
 #'
 #' @param msec maximum time in milliseconds to wait for the condition variable
 #'     to be signalled.
 #'
 #' @examples
 #' until(cv, 10L)
 #'
-#' @rdname wait
+#' @rdname cv
 #' @export
 #'
 until <- function(cv, msec) invisible(.Call(rnng_cv_until, cv, msec))
 
-#' @rdname wait
+#' @rdname cv
 #' @export
 #'
 .until <- function(cv, msec) invisible(.Call(rnng_cv_until2, cv, msec))
 
-#' Condition Variables - Utilities
+#' Condition Variables - Value
 #'
 #' \code{cv_value} inspects the internal value of a condition variable.
 #'
-#' @inheritParams wait
-#'
-#' @return For \strong{cv_value}: integer value of the condition variable.
-#'
-#'     For \strong{cv_reset} and \strong{cv_signal}: zero (invisibly).
-#'
-#' @details These functions work with a 'conditionVariable'. See \code{\link{cv}}
-#'     for further details of how the condition and flag operates.
-#'
 #' @examples
-#' cv <- cv()
-#'
 #' cv_value(cv)
 #'
+#' @rdname cv
 #' @export
 #'
 cv_value <- function(cv) .Call(rnng_cv_value, cv)
@@ -144,7 +131,7 @@ cv_value <- function(cv) .Call(rnng_cv_value, cv)
 #' @examples
 #' cv_reset(cv)
 #'
-#' @rdname cv_value
+#' @rdname cv
 #' @export
 #'
 cv_reset <- function(cv) invisible(.Call(rnng_cv_reset, cv))
@@ -154,10 +141,11 @@ cv_reset <- function(cv) invisible(.Call(rnng_cv_reset, cv))
 #' \code{cv_signal} signals a condition variable.
 #'
 #' @examples
+#' cv_value(cv)
 #' cv_signal(cv)
 #' cv_value(cv)
 #'
-#' @rdname cv_value
+#' @rdname cv
 #' @export
 #'
 cv_signal <- function(cv) invisible(.Call(rnng_cv_signal, cv))
@@ -169,9 +157,9 @@ cv_signal <- function(cv) invisible(.Call(rnng_cv_signal, cv))
 #'
 #' @param socket a Socket.
 #' @param cv a 'conditionVariable' to signal.
-#' @param cv2 [default NULL] optionally, if specified, a second 'conditionVariable'
-#'     to signal. Note that this cv is signalled sequentially after the first
-#'     condition variable.
+#' @param cv2 [default NULL] optionally, if specified, a second
+#'     'conditionVariable' to signal. Note that this cv is signalled
+#'     sequentially after the first condition variable.
 #' @param add [default FALSE] logical value whether to signal when a pipe is
 #'     added.
 #' @param remove [default FALSE] logical value whether to signal when a pipe is