reflow socket, send + recv docs

Author: shikokuchuo

R/sendrecv.R

@@ -23,43 +23,43 @@
 #' @param con a Socket, Context or Stream.
 #' @param data an object (a vector, if mode = \sQuote{raw}).
 #' @param mode [default 'serial'] character value or integer equivalent - either
-#'     \sQuote{serial} (1L) to send serialised R objects, or \sQuote{raw} (2L)
-#'     to send atomic vectors of any type as a raw byte vector. For Streams,
-#'     \sQuote{raw} is the only option and this argument is ignored.
+#'   \sQuote{serial} (1L) to send serialised R objects, or \sQuote{raw} (2L) to
+#'   send atomic vectors of any type as a raw byte vector. For Streams,
+#'   \sQuote{raw} is the only option and this argument is ignored.
 #' @param block [default NULL] which applies the connection default (see section
-#'     \sQuote{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.
+#'   \sQuote{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).
 #'
 #' @section Blocking:
 #'
-#'     For Sockets and Contexts: 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. Certain protocol / transport
-#'     combinations may limit the number of messages that can be queued if they
-#'     have yet to be received.
+#' For Sockets and Contexts: 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. Certain protocol / transport
+#' combinations may limit the number of messages that can be queued if they have
+#' yet to be received.
 #'
-#'     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 small positive value for \code{block} rather than FALSE.
+#' 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 small positive
+#' value for \code{block} rather than FALSE.
 #'
 #' @section Send Modes:
 #'
-#'     The default mode \sQuote{serial} sends serialised R objects to ensure
-#'     perfect reproducibility within R. When receiving, the corresponding mode
-#'     \sQuote{serial} should be used. Custom serialization and unserialization
-#'     functions for reference objects may be enabled by the function
-#'     \code{\link{serial_config}}.
+#' The default mode \sQuote{serial} sends serialised R objects to ensure perfect
+#' reproducibility within R. When receiving, the corresponding mode
+#' \sQuote{serial} should be used. Custom serialization and unserialization
+#' functions for reference objects may be enabled by the function
+#' \code{\link{serial_config}}.
 #'
-#'     Mode \sQuote{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 \sQuote{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.
 #'
 #' @seealso \code{\link{send_aio}} for asynchronous send.
 #' @examples
@@ -93,39 +93,40 @@ send <- function(con, data, mode = c("serial", "raw"), block = NULL)
 #'
 #' @inheritParams send
 #' @param mode [default 'serial'] character value or integer equivalent - 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. For Streams,
-#'     \sQuote{serial} is not an option and the default is \sQuote{character}.
+#'   \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. For Streams,
+#'   \sQuote{serial} is not an option and the default is \sQuote{character}.
 #' @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.
+#'   bytes to receive. Can be an over-estimate, but note that a buffer of this
+#'   size is reserved.
 #'
 #' @return The received data in the \sQuote{mode} specified.
 #'
-#' @details In case of an error, an integer \sQuote{errorValue} is returned (to
-#'     be distiguishable from an integer message value). This can be verified
-#'     using \code{\link{is_error_value}}.
+#' @section Errors:
 #'
-#'     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).
+#' In case of an error, an integer \sQuote{errorValue} is returned (to be
+#' distiguishable from an integer message value). This can be verified using
+#' \code{\link{is_error_value}}.
+#'
+#' 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).
 #'
 #' @section Blocking:
 #'
-#'     For Sockets and Contexts: the default behaviour is non-blocking with
-#'     \code{block = FALSE}. This will return immediately with an error if no
-#'     messages are available.
+#' For Sockets and Contexts: the default behaviour is non-blocking with
+#' \code{block = FALSE}. This will return immediately with an error if no
+#' messages are available.
 #'
-#'     For Streams: the default behaviour is blocking with \code{block = TRUE}.
-#'     This will wait until a message is received. Set a timeout to ensure that
-#'     the function returns under all scenarios. As the underlying
-#'     implementation uses an asynchronous receive with a wait, it is
-#'     recommended to set a small positive value for \code{block} rather than
-#'     FALSE.
+#' For Streams: the default behaviour is blocking with \code{block = TRUE}. This
+#' will wait until a message is received. Set a timeout to ensure that the
+#' function returns under all scenarios. As the underlying implementation uses
+#' an asynchronous receive with a wait, it is recommended to set a small
+#' positive value for \code{block} rather than FALSE.
 #'
 #' @seealso \code{\link{recv_aio}} for asynchronous receive.
 #' @examples

R/socket.R

@@ -19,78 +19,78 @@
 #' Open Socket
 #'
 #' Open a Socket implementing \sQuote{protocol}, and optionally dial (establish
-#'     an outgoing connection) or listen (accept an incoming connection) at an
-#'     address.
+#' an outgoing connection) or listen (accept an incoming connection) at an
+#' address.
+#'
+#' NNG presents a socket view of networking. The sockets are constructed using
+#' protocol-specific functions, as a given socket implements precisely one
+#' protocol.
+#'
+#' Each socket may be used to send and receive messages (if the protocol
+#' supports it, and implements the appropriate protocol semantics). For example,
+#' sub sockets automatically filter incoming messages to discard those for
+#' topics that have not been subscribed.
+#'
+#' This function (optionally) binds a single Dialer and/or Listener to a Socket.
+#' More complex network topologies may be created by binding further Dialers /
+#' Listeners to the Socket as required using \code{\link{dial}} and
+#' \code{\link{listen}}.
+#'
+#' New contexts may also be created using \code{\link{context}} if the protocol
+#' supports it.
 #'
 #' @param protocol [default 'bus'] choose protocol - \sQuote{bus}, \sQuote{pair},
-#'     \sQuote{poly}, \sQuote{push}, \sQuote{pull}, \sQuote{pub}, \sQuote{sub},
-#'     \sQuote{req}, \sQuote{rep}, \sQuote{surveyor}, or \sQuote{respondent} -
-#'     see \link{protocols}.
+#'   \sQuote{poly}, \sQuote{push}, \sQuote{pull}, \sQuote{pub}, \sQuote{sub},
+#'   \sQuote{req}, \sQuote{rep}, \sQuote{surveyor}, or \sQuote{respondent} - see
+#'   \link{protocols}.
 #' @param dial (optional) a URL to dial, specifying the transport and address as
-#'     a character string e.g. 'inproc://anyvalue' or 'tcp://127.0.0.1:5555'
-#'     (see \link{transports}).
+#'   a character string e.g. 'inproc://anyvalue' or 'tcp://127.0.0.1:5555' (see
+#'   \link{transports}).
 #' @param listen (optional) a URL to listen at, specifying the transport and
-#'     address as a character string e.g. 'inproc://anyvalue' or
-#'     'tcp://127.0.0.1:5555' (see \link{transports}).
+#'   address as a character string e.g. 'inproc://anyvalue' or
+#'   'tcp://127.0.0.1:5555' (see \link{transports}).
 #' @param autostart [default TRUE] whether to start the dialer/listener. Set to
-#'     FALSE if setting configuration options on the dialer/listener as it is
-#'     not generally possible to change these once started. For dialers only:
-#'     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.
+#'   FALSE if setting configuration options on the dialer/listener as it is not
+#'   generally possible to change these once started. For dialers only: 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.
 #' @param raw [default FALSE] whether to open raw mode sockets. Note: not for
-#'     general use - do not enable unless you have a specific need (refer to NNG
-#'     documentation).
+#'   general use - do not enable unless you have a specific need (refer to NNG
+#'   documentation).
 #' @inheritParams dial
 #'
 #' @return A Socket (object of class \sQuote{nanoSocket} and \sQuote{nano}).
 #'
-#' @details NNG presents a socket view of networking. The sockets are
-#'     constructed using protocol-specific functions, as a given socket
-#'     implements precisely one protocol.
-#'
-#'     Each socket may be used to send and receive messages (if the protocol
-#'     supports it, and implements the appropriate protocol semantics). For
-#'     example, sub sockets automatically filter incoming messages to discard
-#'     those for topics that have not been subscribed.
-#'
-#'     This function (optionally) binds a single Dialer and/or Listener to a
-#'     Socket. More complex network topologies may be created by binding further
-#'     Dialers/Listeners to the Socket as required using \code{\link{dial}} and
-#'     \code{\link{listen}}.
-#'
-#'     New contexts may also be created using \code{\link{context}} if the
-#'     protocol supports it.
-#'
 #' @section Protocols:
 #'
-#'     The following Scalability Protocols (communication patterns) are
-#'     implemented:
-#'     \itemize{
-#'     \item Bus (mesh networks) - protocol: 'bus'
-#'     \item Pair (two-way radio) - protocol: 'pair'
-#'     \item Poly (one-to-one of many) - protocol: 'poly'
-#'     \item Pipeline (one-way pipe) - protocol: 'push', 'pull'
-#'     \item Publisher/Subscriber (topics & broadcast) - protocol: 'pub', 'sub'
-#'     \item Request/Reply (RPC) - protocol: 'req', 'rep'
-#'     \item Survey (voting & service discovery) - protocol: 'surveyor',
-#'     'respondent'
-#'     }
-#'
-#'     Please see \link{protocols} for further documentation.
+#' The following Scalability Protocols (communication patterns) are implemented:
+#' \itemize{
+#'   \item Bus (mesh networks) - protocol: 'bus'
+#'   \item Pair (two-way radio) - protocol: 'pair'
+#'   \item Poly (one-to-one of many) - protocol: 'poly'
+#'   \item Pipeline (one-way pipe) - protocol: 'push', 'pull'
+#'   \item Publisher/Subscriber (topics & broadcast) - protocol: 'pub', 'sub'
+#'   \item Request/Reply (RPC) - protocol: 'req', 'rep'
+#'   \item Survey (voting & service discovery) - protocol: 'surveyor',
+#'   'respondent'
+#' }
+#'
+#' Please see \link{protocols} for further documentation.
 #'
 #' @section Transports:
 #'
-#'     The following communications transports may be used:
-#'     \itemize{
-#'     \item Inproc (in-process) - url: 'inproc://'
-#'     \item IPC (inter-process communications) - url: 'ipc://' (or
-#'     'abstract://' on Linux)
-#'     \item TCP and TLS over TCP - url: 'tcp://' and 'tls+tcp://'
-#'     \item WebSocket and TLS over WebSocket - url: 'ws://' and 'wss://'
-#'     }
+#' The following communications transports may be used:
+#'
+#' \itemize{
+#'   \item Inproc (in-process) - url: 'inproc://'
+#'   \item IPC (inter-process communications) - url: 'ipc://' (or 'abstract://'
+#'   on Linux)
+#'   \item TCP and TLS over TCP - url: 'tcp://' and 'tls+tcp://'
+#'   \item WebSocket and TLS over WebSocket - url: 'ws://' and 'wss://'
+#' }
 #'
-#'     Please see \link{transports} for further documentation.
+#' Please see \link{transports} for further documentation.
 #'
 #' @examples
 #' s <- socket(protocol = "req", listen = "inproc://nanosocket")
@@ -118,15 +118,15 @@ socket <- function(protocol = c("bus", "pair", "poly", "push", "pull", "pub",
 #' Collect the Pipe from an Aio
 #'
 #' This function retrieves the Pipe used to receive a message from the Aio. It
-#'     will block if the Aio has yet to complete. The message is still available
-#'     for retrieval by the usual means. A Pipe is a low-level object and it is
-#'     not normally necessary to deal with them directly.
+#' will block if the Aio has yet to complete. The message is still available for
+#' retrieval by the usual means. A Pipe is a low-level object and it is not
+#' normally necessary to deal with them directly.
 #'
-#' @param x a 'recvAio' object.
+#' As Pipes are always owned by a Socket, removing (and garbage collecting) a
+#' Pipe does not close it or free its resources. A Pipe may, however, be
+#' explicitly closed.
 #'
-#' @details As Pipes are always owned by a Socket, removing (and garbage
-#'     collecting) a Pipe does not close it or free its resources. A Pipe may,
-#'     however, be explicitly closed.
+#' @param x a 'recvAio' object.
 #'
 #' @return A Pipe (object of class \sQuote{nanoPipe}).
 #'
@@ -152,38 +152,37 @@ collect_pipe <- function(x) .Call(rnng_aio_collect_pipe, x)
 #' Close Connection
 #'
 #' Close Connection on a Socket, Context, Dialer, Listener, Stream, Pipe, or
-#'     ncurl Session.
+#' ncurl Session.
 #'
-#' @param con a Socket, Context, Dialer, Listener, Stream, Pipe, or
-#'     \sQuote{ncurlSession}.
-#' @param ... not used.
+#' Closing an object explicitly frees its resources. An object can also be
+#' removed directly in which case its resources are freed when the object is
+#' garbage collected.
 #'
-#' @return Invisibly, an integer exit code (zero on success).
+#' Closing a Socket associated with a Context also closes the Context.
 #'
-#' @details Closing an object explicitly frees its resources. An object can also
-#'     be removed directly in which case its resources are freed when the object
-#'     is garbage collected.
+#' Dialers and Listeners are implicitly closed when the Socket they are
+#' associated with is closed.
 #'
-#'     Closing a Socket associated with a Context also closes the Context.
+#' Closing a Socket or a Context: messages that have been submitted for sending
+#' may be flushed or delivered, depending upon the transport. Closing the Socket
+#' while data is in transmission will likely lead to loss of that data. There is
+#' no automatic linger or flush to ensure that the Socket send buffers have
+#' completely transmitted.
 #'
-#'     Dialers and Listeners are implicitly closed when the Socket they are
-#'     associated with is closed.
+#' Closing a Stream: if any send or receive operations are pending, they will be
+#' terminated and any new operations will fail after the connection is closed.
 #'
-#'     Closing a Socket or a Context: messages that have been submitted for
-#'     sending may be flushed or delivered, depending upon the transport. Closing
-#'     the Socket while data is in transmission will likely lead to loss of that
-#'     data. There is no automatic linger or flush to ensure that the Socket
-#'     send buffers have completely transmitted.
+#' Closing an \sQuote{ncurlSession} closes the http(s) connection.
 #'
-#'     Closing a Stream: if any send or receive operations are pending, they
-#'     will be terminated and any new operations will fail after the connection
-#'     is closed.
+#' As Pipes are owned by the corresponding Socket, removing (and garbage
+#' collecting) a Pipe does not close it or free its resources. A Pipe may,
+#' however, be explicitly closed.
 #'
-#'     Closing an \sQuote{ncurlSession} closes the http(s) connection.
+#' @param con a Socket, Context, Dialer, Listener, Stream, Pipe, or
+#'   \sQuote{ncurlSession}.
+#' @param ... not used.
 #'
-#'     As Pipes are owned by the corresponding Socket, removing (and garbage
-#'     collecting) a Pipe does not close it or free its resources. A Pipe may,
-#'     however, be explicitly closed.
+#' @return Invisibly, an integer exit code (zero on success).
 #'
 #' @seealso \code{\link{reap}}
 #'
@@ -207,16 +206,16 @@ close.nanoPipe <- function(con, ...) invisible(.Call(rnng_pipe_close, con))
 #' Reap
 #'
 #' An alternative to \code{close} for Sockets, Contexts, Listeners, Dialers and
-#'     Pipes avoiding S3 method dispatch.
+#' Pipes avoiding S3 method dispatch.
+#'
+#' May be used on unclassed external pointers e.g. those created by
+#' \code{\link{.context}}. Returns silently and does not warn or error, nor does
+#' it update the state of object attributes.
 #'
 #' @param con a Socket, Context, Listener, Dialer or Pipe.
 #'
 #' @return An integer exit code (zero on success).
 #'
-#' @details May be used on unclassed external pointers e.g. those created by
-#'     \code{\link{.context}}. Returns silently and does not warn or error, nor
-#'     does it update the state of object attributes.
-#'
 #' @seealso \code{\link{close}}
 #'
 #' @examples