Request over Context (RPC Client for Req/Rep Protocol)

Implements a caller/client for the req node of the req/rep protocol. Sends data to the rep node (executor/server) and returns an Aio, which can be called when the result is required.

request(
  context,
  data,
  send_mode = c("serial", "raw"),
  recv_mode = c("serial", "character", "complex", "double", "integer", "logical",
    "numeric", "raw"),
  timeout = NULL,
  keep.raw = FALSE
)

Arguments

context

a Context.

data

an object (if send_mode = 'raw', a vector).

send_mode

[default 'serial'] whether data will be sent serialized or as a raw vector. Use 'serial' for sending and receiving within R to ensure perfect reproducibility. Use 'raw' for sending vectors of any type (converted to a raw byte vector for sending) - essential when interfacing with external applications. Alternatively, for performance, specify an integer position in the vector of choices i.e. 1L for 'serial' or 2L for 'raw'.

recv_mode

[default 'serial'] mode of vector to be received - one of 'serial', 'character', 'complex', 'double', 'integer', 'logical', 'numeric', or 'raw'. The default 'serial' means a serialised R object, for the other modes, the raw vector received will be converted into the respective mode. Alternatively, for performance, specify an integer position in the vector of choices e.g. 1L for 'serial', 2L for 'character' etc.

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 result.

keep.raw

[default FALSE] logical flag whether to keep and return the received raw vector along with the converted data. Supplying a non-logical value will error.

Value

A 'recvAio' (object of class 'recvAio') (invisibly).

Details

Sending the request and receiving the result are both performed async, hence the function will return immediately with a 'recvAio' object. Access the return value at $data.

This is designed so that the process on the server can run concurrently without blocking the client.

Optionally use call_aio on the 'recvAio' to call (and wait for) the result.

If an error occured in the server process, a nul byte 00 will be received (as $data if 'recv_mode' = 'serial', as $raw otherwise). This allows an error to be easily distinguished from a NULL return value. is_nul_byte can be used to test for a nul byte.

Examples

req <- socket("req", listen = "tcp://127.0.0.1:6546")
rep <- socket("rep", dial = "tcp://127.0.0.1:6546")

ctxq <- context(req)
ctxp <- context(rep)

# works if req and rep are running in parallel in different processes
reply(ctxp, execute = function(x) x + 1, timeout = 10)
#> 'errorValue' int 5 | Timed out
aio <- request(ctxq, data = 2022, timeout = 10)
call_aio(aio)$data
#> 'errorValue' int 5 | Timed out

close(req)
close(rep)