% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/aio.R
\name{recv_aio}
\alias{recv_aio}
\title{Receive Async}
\usage{
recv_aio(
  con,
  mode = c("serial", "character", "complex", "double", "integer", "logical", "numeric",
    "raw", "string"),
  timeout = NULL,
  cv = NULL
)
}
\arguments{
\item{con}{a Socket, Context or Stream.}

\item{mode}{[default 'serial'] character value or integer equivalent - one
of \code{"serial"} (1L), \code{"character"} (2L), \code{"complex"} (3L), \code{"double"} (4L),
\code{"integer"} (5L), \code{"logical"} (6L), \code{"numeric"} (7L), \code{"raw"} (8L), or
\code{"string"} (9L). The default \code{"serial"} means a serialised R object; for
the other modes, received bytes are converted into the respective mode.
\code{"string"} is a faster option for length one character vectors. For
Streams, \code{"serial"} will default to \code{"character"}.}

\item{timeout}{[default NULL] integer value in milliseconds or NULL, which
applies a socket-specific default, usually the same as no timeout.}

\item{cv}{(optional) a 'conditionVariable' to signal when the async receive
is complete.}
}
\value{
A 'recvAio' (object of class 'recvAio') (invisibly).
}
\description{
Receive data asynchronously over a connection (Socket, Context or Stream).
}
\details{
Async receive is always non-blocking and returns a 'recvAio' immediately.

For a 'recvAio', the received message is available at \verb{$data}. An
'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]{call_aio()}} on the returned 'recvAio' object.

Alternatively, to stop the async operation, use \code{\link[=stop_aio]{stop_aio()}}.

In case of an error, an integer 'errorValue' is returned (to be
distiguishable from an integer message value). This can be checked using
\code{\link[=is_error_value]{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{Signalling}{


By supplying a 'conditionVariable', when the receive is complete, the
'conditionVariable' is signalled by incrementing its value by 1. This
happens asynchronously and independently of the R execution thread.
}

\examples{
s1 <- socket("pair", listen = "inproc://nanonext")
s2 <- socket("pair", dial = "inproc://nanonext")

res <- send_aio(s1, data.frame(a = 1, b = 2), timeout = 100)
msg <- recv_aio(s2, timeout = 100)
msg
msg$data

res <- send_aio(s1, c(1.1, 2.2, 3.3), mode = "raw", timeout = 100)
msg <- recv_aio(s2, mode = "double", timeout = 100)
msg
msg$data

res <- send_aio(s1, "example message", mode = "raw", timeout = 100)
msg <- recv_aio(s2, mode = "character", timeout = 100)
call_aio(msg)
msg$data

close(s1)
close(s2)

# Signalling a condition variable

s1 <- socket("pair", listen = "inproc://cv-example")
cv <- cv()
msg <- recv_aio(s1, timeout = 100, cv = cv)
until(cv, 10L)
msg$data
close(s1)

# in another process in parallel
s2 <- socket("pair", dial = "inproc://cv-example")
res <- send_aio(s2, c(1.1, 2.2, 3.3), mode = "raw", timeout = 100)
close(s2)

}
\seealso{
\code{\link[=recv]{recv()}} for synchronous receive.
}
