implements next mode, next_config(), use of serialization refhooks

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: nanonext
 Type: Package
 Title: NNG (Nanomsg Next Gen) Lightweight Messaging Library
-Version: 0.10.2.9006
+Version: 0.10.2.9007
 Description: R binding for NNG (Nanomsg Next Gen), a successor to ZeroMQ. NNG is 
     a socket library providing high-performance scalability protocols, a
     cross-platform standard for messaging and communications. Serves as a

NAMESPACE

@@ -61,6 +61,7 @@ export(nano)
 export(ncurl)
 export(ncurl_aio)
 export(ncurl_session)
+export(next_config)
 export(nng_error)
 export(nng_version)
 export(opt)

NEWS.md

@@ -1,7 +1,8 @@
-# nanonext 0.10.2.9006 (development)
+# nanonext 0.10.2.9007 (development)
 
 #### New Features
 
+* `next_config()` enables native extensions when sending using mode 'next'. Registers hook functions for custom serialization and unserialization of reference objects (such as those accessed via an external pointer).
 * `.until()` contains revised behaviour for this synchronisation primitive that will be ported to `until()` in a future version. The function now returns FALSE instead of TRUE if the timeout has been reached.
 
 #### Updates

R/aio.R

@@ -41,6 +41,8 @@
 #'
 #'     Alternatively, to stop the async operation, use \code{\link{stop_aio}}.
 #'
+#' @inheritSection send Send Modes
+#'
 #' @examples
 #' pub <- socket("pub", dial = "inproc://nanonext")
 #'

R/context.R

@@ -101,21 +101,19 @@ 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 '...'.
-#' @param send_mode [default 'serial'] one of 'serial' to send serialised R objects,
-#'     'raw' to send atomic vectors of any type as a raw byte vector, or 'next'
-#'     to send in a new R-compatible serialisation format. Use 'serial' to ensure
-#'     perfect reproducibility within R, although 'raw' must be used when
-#'     interfacing with external applications which do not understand R
-#'     serialisation. Alternatively, for performance, specify an integer position
-#'     in the vector of choices e.g. 1L for 'serial' or 2L for 'raw' etc.
+#' @param send_mode [default 'serial'] one of 'serial' to send serialised R
+#'     objects, 'raw' to send atomic vectors of any type as a raw byte vector,
+#'     or 'next' (see 'Send Modes' section below). Alternatively, specify an
+#'     integer position in the vector of choices e.g. 1L for 'serial' or 2L for
+#'     'raw' etc.
 #' @param recv_mode [default 'serial'] mode of vector to be received - one of
 #'     'serial', 'character', 'complex', 'double', 'integer', 'logical',
 #'     'numeric', 'raw', or 'string'. The default 'serial' means a serialised R
 #'     object, for the other modes, the raw vector received will be converted
-#'     into the respective mode. Note that 'string' is defined here as a character
-#'     scalar and is a faster alternative to 'character' for receiving a single
-#'     string. Alternatively, for performance, specify an integer position in
-#'     the vector of choices e.g. 1L for 'serial', 2L for 'character' etc.
+#'     into the respective mode. 'string' is a faster alternative to 'character'
+#'     for receiving a length 1 character string. Alternatively, specify an
+#'     integer position in the vector of choices e.g. 1L for 'serial', 2L for
+#'     'character' etc.
 #' @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
@@ -136,6 +134,8 @@ close.nanoContext <- function(con, ...) invisible(.Call(rnng_ctx_close, con))
 #'     to be distinguishable from a possible return value. \code{\link{is_nul_byte}}
 #'     can be used to test for a nul byte.
 #'
+#' @inheritSection send Send Modes
+#'
 #' @examples
 #' req <- socket("req", listen = "tcp://127.0.0.1:6546")
 #' rep <- socket("rep", dial = "tcp://127.0.0.1:6546")
@@ -206,6 +206,8 @@ reply <- function(context,
 #'     is closed when all references to the returned 'recvAio' are removed and
 #'     the object is garbage collected.
 #'
+#' @inheritSection send Send Modes
+#'
 #' @examples
 #' req <- socket("req", listen = "tcp://127.0.0.1:6546")
 #' rep <- socket("rep", dial = "tcp://127.0.0.1:6546")

R/sendrecv.R

@@ -24,17 +24,14 @@
 #' @param data an object (a vector, if mode = 'raw').
 #' @param mode [default 'serial'] one of 'serial' to send serialised R objects,
 #'     'raw' to send atomic vectors of any type as a raw byte vector, or 'next'
-#'     to send in a new R-compatible serialisation format. For Streams, 'raw' is
-#'     the only option and this argument is ignored. Use 'serial' to ensure
-#'     perfect reproducibility within R, although 'raw' must be used when
-#'     interfacing with external applications which do not understand R
-#'     serialisation. Alternatively, for performance, specify an integer position
-#'     in the vector of choices e.g. 1L for 'serial' or 2L for 'raw' etc.
+#'     (see 'Send Modes' section below). Alternatively, specify an integer
+#'     position in the vector of choices e.g. 1L for 'serial' or 2L for 'raw'
+#'     etc. For Streams, 'raw' is the only option and this argument is ignored.
 #' @param block [default NULL] which applies the connection default (see section
-#'     'Blocking' below). Specify 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.
+#'     'Blocking' below). Specify 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.
 #'
 #' @return Integer exit code (zero on success).
 #'
@@ -51,9 +48,26 @@
 #'
 #'     For Streams: the default behaviour is blocking with \code{block = TRUE}.
 #'     This will wait until the send has completed. Set a timeout to ensure that
-#'     the function returns under all scenarios. As the underlying implementation
-#'     uses an asynchronous send with a wait, it is recommended to set a positive
-#'     integer value for \code{block} rather than FALSE.
+#'     the function returns under all scenarios. As the underlying
+#'     implementation uses an asynchronous send with a wait, it is recommended
+#'     to set a positive integer value for \code{block} rather than FALSE.
+#'
+#' @section Send Modes:
+#'
+#'     The default mode 'serial' sends serialised R objects to ensure perfect
+#'     reproducibility within R. When receiving, the corresponding mode 'serial'
+#'     should be used.
+#'
+#'     Mode 'raw' sends atomic vectors of any type as a raw byte vector, and
+#'     must be used when interfacing with external applications or raw system
+#'     sockets, where R serialization is not in use. When receiving, the mode
+#'     corresponding to the vector sent should be used.
+#'
+#'     Mode 'next' sends serialised R objects, with native extensions enabled by
+#'     \code{\link{next_config}}. This allows 'refhook' functions to be
+#'     registered for custom serialization and unserialization of reference
+#'     objects, such as those accessed via an external pointer. When receiving,
+#'     mode 'serial' should be used as 'next' sends are fully compatible.
 #'
 #' @seealso \code{\link{send_aio}} for asynchronous send.
 #' @examples
@@ -90,11 +104,10 @@ send <- function(con, data, mode = c("serial", "raw", "next"), block = NULL)
 #'     'character', 'complex', 'double', 'integer', 'logical', 'numeric', 'raw',
 #'     or 'string'. The default 'serial' means a serialised R object, for the
 #'     other modes, the raw vector received will be converted into the respective
-#'     mode. Note that 'string' is a faster alternative to 'character' for
-#'     receiving a character vector of length 1. For Streams, 'serial' is not an
-#'     option and the default is 'character'. Alternatively, for performance,
-#'     specify an integer position in the vector of choices e.g. 1L for 'serial',
-#'     2L for 'character' etc.
+#'     mode. 'string' is a faster alternative to 'character' for receiving a
+#'     length 1 character string. For Streams, 'serial' is not an option and the
+#'     default is 'character'. Alternatively, specify an integer position in the
+#'     vector of choices e.g. 1L for 'serial', 2L for 'character' etc.
 #' @param n [default 65536L] applicable to Streams only, the maximum number of
 #'     bytes to receive. Can be an over-estimate, but note that a buffer of this
 #'     size is reserved.

R/utils.R

@@ -272,3 +272,49 @@ status_code <- function(x) .Call(rnng_status_code, x)
 #' @export
 #'
 strcat <- function(a, b) .Call(rnng_strcat, a, b)
+
+#' Configure Next Mode
+#'
+#' Configures 'next' mode by registering 'refhook' functions for serialization
+#'     and unserialization. This permits sending and receiving reference
+#'     objects, such as those accessed via an external pointer, between
+#'     different R sessions.
+#'
+#' @param inhook a function (for custom serialization). The signature for this
+#'     function must accept a list and return a raw vector, e.g.
+#'     \code{safetensors::safe_serialize}, or else NULL to reset.
+#' @param outhook a function (for custom unserialization). The signature for
+#'     this function must accept a raw vector and return a list, e.g.
+#'     \code{safetensors::safe_load_file}, or else NULL to reset.
+#'
+#' @return Invisibly, a pairlist comprising the currently-registered 'next'
+#'     configuration.
+#'
+#' @details Calling this function without any arguments returns (invisibly) the
+#'     currently-registered 'next' configuration.
+#'
+#'     Alternatively, calling this function with a configuration pairlist
+#'     previously returned by this function registers the supplied configuration.
+#'
+#' @section Refhook:
+#'
+#'     The 'refhook' functions are a native feature of R's serialization
+#'     mechanism and apply to all non-system reference objects (external
+#'     pointers, weak references, and all environments other than namespace and
+#'     package environments and the Global Environment).
+#'
+#' @examples
+#' cfg <- next_config(inhook = function(x) serialize(x, NULL),
+#'                    outhook = unserialize)
+#' cfg
+#'
+#' nul <- next_config(NULL, NULL)
+#' print(next_config())
+#'
+#' print(next_config(cfg))
+#' print(next_config(nul))
+#'
+#' @export
+#'
+next_config <- function(inhook, outhook)
+  invisible(.Call(rnng_next_config, if (missing(inhook)) "" else inhook, if (missing(outhook)) "" else outhook))