implements lazy loading of later package

Author: shikokuchuo

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: nanonext
 Type: Package
 Title: NNG (Nanomsg Next Gen) Lightweight Messaging Library
-Version: 0.13.6.9016
+Version: 0.13.6.9017
 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

NAMESPACE

@@ -97,7 +97,6 @@ export(until_)
 export(wait)
 export(wait_)
 export(write_cert)
-importFrom(later,run_now)
 importFrom(stats,start)
 importFrom(tools,md5sum)
 importFrom(utils,.DollarNames)

NEWS.md

@@ -1,10 +1,11 @@
-# nanonext 0.13.6.9016 (development)
+# nanonext 0.13.6.9017 (development)
 
 #### New Features
 
 * Integrates with the `later` package to provide the foundation for truly event-driven (non-polling) promises (thanks @jcheng5 for the initial prototype in #28), where side-effects are enacted asynchronously upon aio completion.
   + `request()` and `request_signal()` modified internally to support conversion of 'recvAio' to event-driven promises.
   + adds dependency on the `later` package to ensure asynchronous R code is always run on the main R thread.
+  + `later` is lazily loaded the first time a promise is used, and does not impact performance otherwise.
 
 #### Updates
 

R/aio.R

@@ -26,18 +26,18 @@
 #' @param timeout [default NULL] integer value in milliseconds or NULL, which
 #'     applies a socket-specific default, usually the same as no timeout.
 #'
-#' @return A 'sendAio' (object of class 'sendAio') (invisibly).
+#' @return A \sQuote{sendAio} (object of class \sQuote{sendAio}) (invisibly).
 #'
-#' @details Async send is always non-blocking and returns a 'sendAio'
+#' @details Async send is always non-blocking and returns a \sQuote{sendAio}
 #'     immediately.
 #'
-#'     For a 'sendAio', the send result is available at \code{$result}. An
-#'     'unresolved' logical NA is returned if the async operation is yet to
-#'     complete. The resolved value will be zero on success, or else an integer
-#'     error code.
+#'     For a \sQuote{sendAio}, the send result is available at \code{$result}.
+#'     An \sQuote{unresolved} logical NA is returned if the async operation is
+#'     yet to complete. The resolved value will be zero on success, or else an
+#'     integer error code.
 #'
 #'     To wait for and check the result of the send operation, use
-#'     \code{\link{call_aio}} on the returned 'sendAio' object.
+#'     \code{\link{call_aio}} on the returned \sQuote{sendAio} object.
 #'
 #'     Alternatively, to stop the async operation, use \code{\link{stop_aio}}.
 #'
@@ -67,21 +67,22 @@ send_aio <- function(con, data, mode = c("serial", "raw", "next"), timeout = NUL
 #' @inheritParams recv
 #' @inheritParams send_aio
 #'
-#' @return A 'recvAio' (object of class 'recvAio') (invisibly).
+#' @return A \sQuote{recvAio} (object of class \sQuote{recvAio}) (invisibly).
 #'
-#' @details Async receive is always non-blocking and returns a 'recvAio'
+#' @details Async receive is always non-blocking and returns a \sQuote{recvAio}
 #'     immediately.
 #'
-#'     For a 'recvAio', the received message is available at \code{$data}. An
-#'     'unresolved' logical NA is returned if the async operation is yet to
-#'     complete.
+#'     For a \sQuote{recvAio}, the received message is available at \code{$data}.
+#'     An \sQuote{unresolved} logical NA is returned if the async operation is
+#'     yet to complete.
 #'
 #'     To wait for the async operation to complete and retrieve the received
-#'     message, use \code{\link{call_aio}} on the returned 'recvAio' object.
+#'     message, use \code{\link{call_aio}} on the returned \sQuote{recvAio}
+#'     object.
 #'
 #'     Alternatively, to stop the async operation, use \code{\link{stop_aio}}.
 #'
-#'     In case of an error, an integer 'errorValue' is returned (to be
+#'     In case of an error, an integer \sQuote{errorValue} is returned (to be
 #'     distiguishable from an integer message value). This can be checked using
 #'     \code{\link{is_error_value}}.
 #'
@@ -122,16 +123,16 @@ recv_aio <- function(con,
 
 #' Receive Async and Signal a Condition
 #'
-#' A signalling version of the function takes a 'conditionVariable' as an
+#' A signalling version of the function takes a \sQuote{conditionVariable} as an
 #'     additional argument and signals it when the async receive is complete.
 #'
-#' @param cv \strong{For the signalling version}: a 'conditionVariable' to
-#'     signal when the async receive is complete.
+#' @param cv \strong{For the signalling version}: a \sQuote{conditionVariable}
+#'     to signal when the async receive is complete.
 #'
 #' @details \strong{For the signalling version}: when the receive is complete,
-#'     the supplied 'conditionVariable' is signalled by incrementing its value
-#'     by 1. This happens asynchronously and independently of the R execution
-#'     thread.
+#'     the supplied \sQuote{conditionVariable} is signalled by incrementing its
+#'     value by 1. This happens asynchronously and independently of the R
+#'     execution thread.
 #'
 #' @examples
 #' # Signalling a condition variable
@@ -166,34 +167,38 @@ recv_aio_signal <- function(con,
 #' \code{call_aio} retrieves the value of an asynchronous Aio operation, waiting
 #'     for the operation to complete if still in progress.
 #'
-#' @param aio an Aio (object of class 'sendAio', 'recvAio' or 'ncurlAio').
+#' @param aio an Aio (object of class \sQuote{sendAio}, \sQuote{recvAio} or
+#'     \sQuote{ncurlAio}).
 #'
 #' @return The passed object (invisibly).
 #'
-#' @details For a 'recvAio', the received value may be retrieved at \code{$data}.
+#' @details For a \sQuote{recvAio}, the received value may be retrieved at
+#'     \code{$data}.
 #'
-#'     For a 'sendAio', the send result may be retrieved at \code{$result}. This
-#'     will be zero on success, or else an integer error code.
+#'     For a \sQuote{sendAio}, the send result may be retrieved at
+#'     \code{$result}. This will be zero on success, or else an integer error
+#'     code.
 #'
-#'     To access the values directly, use for example on a 'recvAio' \code{x}:
-#'     \code{call_aio(x)$data}.
+#'     To access the values directly, use for example on a \sQuote{recvAio}
+#'     \code{x}: \code{call_aio(x)$data}.
 #'
-#'     For a 'recvAio', if an error occurred in unserialization or conversion of
-#'     the message data to the specified mode, a raw vector will be returned
-#'     instead to allow recovery (accompanied by a warning).
+#'     For a \sQuote{recvAio}, if an error occurred in unserialization or
+#'     conversion of the message data to the specified mode, a raw vector will
+#'     be returned instead to allow recovery (accompanied by a warning).
 #'
 #'     Once the value has been successfully retrieved, the Aio is deallocated
 #'     and only the value is stored in the Aio object.
 #'
-#'     Note this function operates silently and does not error even if 'aio' is
-#'     not an active Aio, always returning invisibly the passed object.
+#'     Note this function operates silently and does not error even if
+#'     \sQuote{aio} is not an active Aio, always returning invisibly the passed
+#'     object.
 #'
 #' @section Alternatively:
 #'
-#'     Aio values may be accessed directly at \code{$result} for a 'sendAio',
-#'     and \code{$data} for a 'recvAio'. If the Aio operation is yet to complete,
-#'     an 'unresolved' logical NA will be returned. Once complete, the resolved
-#'     value will be returned instead.
+#'     Aio values may be accessed directly at \code{$result} for a
+#'     \sQuote{sendAio}, and \code{$data} for a \sQuote{recvAio}. If the Aio
+#'     operation is yet to complete, an \sQuote{unresolved} logical NA will be
+#'     returned. Once complete, the resolved value will be returned instead.
 #'
 #'     \code{\link{unresolved}} may also be used, which returns TRUE only if an
 #'     Aio or Aio value has yet to resolve and FALSE otherwise. This is suitable
@@ -237,14 +242,14 @@ call_aio_ <- function(aio) invisible(.Call(rnng_wait_thread_create, aio))
 #'
 #' @return Invisible NULL.
 #'
-#' @details Stops the asynchronous I/O operation associated with 'aio' by
+#' @details Stops the asynchronous I/O operation associated with \sQuote{aio} by
 #'     aborting, and then waits for it to complete or to be completely aborted,
-#'     and for the callback associated with the 'aio' to have completed
-#'     executing. If successful, the 'aio' will resolve to an 'errorValue' 20
-#'     (Operation canceled).
+#'     and for the callback associated with the \sQuote{aio} to have completed
+#'     executing. If successful, the \sQuote{aio} will resolve to an
+#'     \sQuote{errorValue} 20 (Operation canceled).
 #'
-#'     Note this function operates silently and does not error even if 'aio' is
-#'     not an active Aio, always returning invisible NULL.
+#'     Note this function operates silently and does not error even if
+#'     \sQuote{aio} is not an active Aio, always returning invisible NULL.
 #'
 #' @export
 #'
@@ -255,16 +260,17 @@ stop_aio <- function(aio) invisible(.Call(rnng_aio_stop, aio))
 #' Query whether an Aio or Aio value remains unresolved. Unlike
 #'     \code{\link{call_aio}}, this function does not wait for completion.
 #'
-#' @param aio an Aio (object of class 'sendAio' or 'recvAio'), or Aio value
-#'     stored in \code{$result} or \code{$data} as the case may be.
+#' @param aio an Aio (object of class \sQuote{sendAio} or \sQuote{recvAio}), or
+#'     Aio value stored in \code{$result} or \code{$data} as the case may be.
 #'
-#' @return Logical TRUE if 'aio' is an unresolved Aio or Aio value, or FALSE
-#'     otherwise.
+#' @return Logical TRUE if \sQuote{aio} is an unresolved Aio or Aio value, or
+#'     FALSE otherwise.
 #'
 #' @details Suitable for use in control flow statements such as \code{while} or
 #'     \code{if}.
 #'
-#'     Note: querying resolution may cause a previously unresolved Aio to resolve.
+#'     Note: querying resolution may cause a previously unresolved Aio to
+#'     resolve.
 #'
 #' @examples
 #' s1 <- socket("pair", listen = "inproc://nanonext")
@@ -292,11 +298,11 @@ unresolved <- function(aio) .Call(rnng_unresolved, aio)
 #'     altering its state in any way i.e. not attempting to retrieve the result
 #'     or message.
 #'
-#' @param aio an Aio (object of class 'sendAio' or 'recvAio').
+#' @param aio an Aio (object of class \sQuote{sendAio} or \sQuote{recvAio}).
 #'
-#' @return Logical TRUE if 'aio' is an unresolved Aio, or FALSE otherwise.
+#' @return Logical TRUE if \sQuote{aio} is an unresolved Aio, or FALSE otherwise.
 #'
-#' @details \code{.unresolved()} is not intended to be used for 'recvAio'
+#' @details \code{.unresolved()} is not intended to be used for \sQuote{recvAio}
 #'     returned by a signalling function, in which case \code{\link{unresolved}}
 #'     must be used in all cases.
 #'

R/context.R

@@ -24,7 +24,7 @@
 #'
 #' @param socket a Socket.
 #'
-#' @return A Context (object of class 'nanoContext' and 'nano').
+#' @return A Context (object of class \sQuote{nanoContext} and \sQuote{nano}).
 #'
 #' @details Contexts allow the independent and concurrent use of stateful
 #'     operations using the same socket. For example, two different contexts
@@ -101,17 +101,18 @@ close.nanoContext <- function(con, ...) invisible(.Call(rnng_ctx_close, con))
 #' @param execute a function which takes the received (converted) data as its
 #'     first argument. Can be an anonymous function of the form
 #'     \code{function(x) do(x)}. Additional arguments can also be passed in
-#'     through '...'.
+#'     through \sQuote{...}.
 #' @param send_mode [default 'serial'] character value or integer equivalent -
-#'     one of 'serial' (1L) to send serialised R objects, 'raw' (2L) to send
-#'     atomic vectors of any type as a raw byte vector, or 'next' (3L) - see
-#'     'Send Modes' section below.
+#'     one of \sQuote{serial} (1L) to send serialised R objects, \sQuote{raw}
+#'     (2L) to send atomic vectors of any type as a raw byte vector, or
+#'     \sQuote{next} (3L) - see \sQuote{Send Modes} section below.
 #' @param recv_mode [default 'serial'] character value or integer equivalent -
-#'     one of 'serial' (1L), 'character' (2L), 'complex' (3L), 'double' (4L),
-#'     'integer' (5L), 'logical' (6L), 'numeric' (7L), 'raw' (8L), or 'string'
-#'     (9L). The default 'serial' means a serialised R object; for the other
-#'     modes, received bytes are converted into the respective mode. 'string' is
-#'     a faster option for length one character vectors.
+#'     one of \sQuote{serial} (1L), \sQuote{character} (2L), \sQuote{complex}
+#'     (3L), \sQuote{double} (4L), \sQuote{integer} (5L), \sQuote{logical} (6L),
+#'     \sQuote{numeric} (7L), \sQuote{raw} (8L), or \sQuote{string} (9L). The
+#'     default \sQuote{serial} means a serialised R object; for the other
+#'     modes, received bytes are converted into the respective mode.
+#'     \sQuote{string} is a faster option for length one character vectors.
 #' @param timeout [default NULL] integer value in milliseconds or NULL, which
 #'     applies a socket-specific default, usually the same as no timeout. Note
 #'     that this applies to receiving the request. The total elapsed time would
@@ -180,21 +181,21 @@ reply <- function(context,
 #'
 #' @inheritParams reply
 #' @inheritParams recv
-#' @param data an object (if send_mode = 'raw', a vector).
+#' @param data an object (if send_mode = \sQuote{raw}, a vector).
 #' @param timeout [default NULL] integer value in milliseconds or NULL, which
 #'     applies a socket-specific default, usually the same as no timeout.
 #'
-#' @return A 'recvAio' (object of class 'recvAio') (invisibly).
+#' @return A \sQuote{recvAio} (object of class \sQuote{recvAio}) (invisibly).
 #'
 #' @details Sending the request and receiving the result are both performed
-#'     async, hence the function will return immediately with a 'recvAio'
+#'     async, hence the function will return immediately with a \sQuote{recvAio}
 #'     object. Access the return value at \code{$data}.
 #'
 #'     This is designed so that the process on the server can run concurrently
 #'     without blocking the client.
 #'
-#'     Optionally use \code{\link{call_aio}} on the 'recvAio' to call (and wait
-#'     for) the result.
+#'     Optionally use \code{\link{call_aio}} on the \sQuote{recvAio} to call
+#'     (and wait for) the result.
 #'
 #'     If an error occured in the server process, a nul byte \code{00} will be
 #'     received. This allows an error to be easily distinguished from a NULL
@@ -203,8 +204,8 @@ reply <- function(context,
 #'
 #'     It is recommended to use a new context for each request to ensure
 #'     consistent state tracking. For safety, the context used for the request
-#'     is closed when all references to the returned 'recvAio' are removed and
-#'     the object is garbage collected.
+#'     is closed when all references to the returned \sQuote{recvAio} are
+#'     removed and the object is garbage collected.
 #'
 #' @inheritSection send Send Modes
 #'
@@ -232,15 +233,15 @@ request <- function(context,
 
 #' Request and Signal a Condition Variable (RPC Client for Req/Rep Protocol)
 #'
-#' A signalling version of the function takes a 'conditionVariable' as an
+#' A signalling version of the function takes a \sQuote{conditionVariable} as an
 #'     additional argument and signals it when the async receive is complete.
 #'
 #' @inheritParams recv_aio_signal
 #'
 #' @details \strong{For the signalling version}: when the receive is complete,
-#'     the supplied 'conditionVariable' is signalled by incrementing its value
-#'     by 1. This happens asynchronously and independently of the R execution
-#'     thread.
+#'     the supplied \sQuote{conditionVariable} is signalled by incrementing its
+#'     value by 1. This happens asynchronously and independently of the R
+#'     execution thread.
 #'
 #' @examples
 #' # Signalling a condition variable
@@ -279,11 +280,11 @@ request_signal <- function(context,
 #'     \code{\link{request_signal}}.
 #' @param ctx the context environment.
 #'
-#' @details The object passed as 'x' is returned regardless of whether the
-#'     promise context was set successfully or not. If successful, 'x' is
-#'     modified in place with the promise context.
+#' @details The object passed as \sQuote{x} is returned regardless of whether
+#'     the promise context was set successfully or not. If successful,
+#'     \sQuote{x} is modified in place with the promise context.
 #'
-#' @return The object 'x'.
+#' @return The object \sQuote{x}.
 #'
 #' @keywords internal
 #' @export

R/listdial.R

@@ -27,18 +27,18 @@
 #' @param tls [default NULL] for secure tls+tcp:// or wss:// connections only,
 #'     provide a TLS configuration object created by \code{\link{tls_config}}.
 #' @param autostart [default TRUE] whether to start the dialer (by default
-#'     asynchronously). Set to NA to start synchronously - this is less resilient
-#'     if a connection is not immediately possible, but avoids subtle errors
-#'     from attempting to use the socket before an asynchronous dial has completed.
-#'     Set to FALSE if setting configuration options on the dialer as it is not
-#'     generally possible to change these once started.
+#'     asynchronously). Set to NA to start synchronously - this is less
+#'     resilient if a connection is not immediately possible, but avoids subtle
+#'     errors from attempting to use the socket before an asynchronous dial has
+#'     completed. Set to FALSE if setting configuration options on the dialer as
+#'     it is not generally possible to change these once started.
 #' @param error [default FALSE] behaviour on error: if FALSE, returns an integer
 #'     exit code accompanied by a warning, or, if TRUE, generates an error and
 #'     halts execution.
 #'
 #' @return Invisibly, an integer exit code (zero on success). A new Dialer
-#'     (object of class 'nanoDialer' and 'nano') is created and bound to the
-#'     Socket if successful.
+#'     (object of class \sQuote{nanoDialer} and \sQuote{nano}) is created and
+#'     bound to the Socket if successful.
 #'
 #' @details To view all Dialers bound to a socket use \code{$dialer} on the
 #'     socket, which returns a list of Dialer objects. To access any individual
@@ -100,12 +100,12 @@ dial <- function(socket, url = "inproc://nanonext", tls = NULL, autostart = TRUE
 #'     possible to change these once started.
 #'
 #' @return Invisibly, an integer exit code (zero on success). A new Listener
-#'     (object of class 'nanoListener' and 'nano') is created and bound to the
-#'     Socket if successful.
+#'     (object of class \sQuote{nanoListener} and \sQuote{nano}) is created and
+#'     bound to the Socket if successful.
 #'
 #' @details To view all Listeners bound to a socket use \code{$listener} on the
-#'     socket, which returns a list of Listener objects. To access any individual
-#'     Listener (e.g. to set options on it), index into the list e.g.
+#'     socket, which returns a list of Listener objects. To access any
+#'     individual Listener (e.g. to set options on it), index into the list e.g.
 #'     \code{$listener[[1]]} to return the first Listener.
 #'
 #'     A listener is an external pointer to a listener object, which accepts

R/messenger.R

@@ -45,9 +45,9 @@
 #'
 #'     \code{:q} is the command to quit.
 #'
-#'     Both parties must supply the same argument for 'auth', otherwise the
-#'     party trying to connect will receive an 'authentication error' and be
-#'     disconnected immediately.
+#'     Both parties must supply the same argument for \sQuote{auth}, otherwise
+#'     the party trying to connect will receive an \sQuote{authentication error}
+#'     and be immediately disconnected.
 #'
 #' @export
 #'

R/nano.R

@@ -23,7 +23,7 @@
 #'
 #' @inheritParams socket
 #'
-#' @return A nano object of class 'nanoObject'.
+#' @return A nano object of class \sQuote{nanoObject}.
 #'
 #' @details This function encapsulates a Socket, Dialer and/or Listener, and its
 #'     associated methods.