RSclient (version 0.7-0)

RCC: Functions to talk to an Rserve instance (new version)

Description

Rserve is a server providing R functionality via sockets. The following functions allow another R session to start new Rserve sessions and evaluate commands.

Usage

RS.connect(host = NULL, port = 6311L, tls = FALSE)
RS.login(rsc, user, password, pubkey, authkey)
RS.eval(rsc, x, wait = TRUE)
RS.collect(rsc, timeout = Inf)
RS.close(rsc)
RS.assign(rsc, name, value)
RS.switch(rsc, protocol = "TLS")
RS.authkey(rsc, type = "rsa-authkey")
RS.oobCallbacks(rsc, send, msg)

Arguments

host

host to connect to or socket path or NULL for local host

port

TCP port to connect to or 0 if unix socket is to be used

tls

if TRUE then SSL/TLS encrypted connection is started

rsc

Rserve connection as obtained from RS.connect

user

username for authentication (mandatory)

password

password for authentication

pubkey

public key for authentication

authkey

authkey (as obtained from RS.authkey) for secure authentication

x

expression to evaluate

wait

if TRUE then the result is delivered synchronously, if FALSE then NULL is returned instead and the result can be collected later with RS.collect

timeout

timeout (in seconds) to wait before giving up

name

string, name of the symbol to assign to

value

value to assign

protocol

protocol to switch to (string)

type

type of the authentication to perform (string)

send

callback function for OOB_SEND

msg

callback function for OOB_MSG

Details

RS.connect creates a connection to a Rserve. The returned handle is to be used in all subsequent calls to client functions. The session associated witht he connection is alive until closed via RS.close.

RS.close closes the Rserve connection.

RS.login performs authentication with the Rserve. The user entry is mandatory and at least one of password, pubkey and authkey must be provided. Typical secure authentication is performed with RS.login(rsc, "username", "password", authkey=RS.authkey()) which ensures that the authentication request is encrypted and cannot be spoofed. When using TLS connections RS.authkey is not necessary as the connection is already encrypted.

RS.eval evaluates the supplied expression remotely.

RS.collect collects results from RS.eval(..., wait = FALSE) calls. Note that it this case rsc can be either one connection or a list of connections.

RS.assign assigns a value to the remote global workspace. RS.switch attempts to switch the protocol currently used for communication with Rserve.

RS.oobCallbacks sets or retrieves the callback functions associated with OOB_SEND and OOB_MSG out-of-band commands. If neither send nor msg is specified then RS.oobCallbacks simply returns the current callback functions, otherwise it replaces the existing ones. Both functions have the form function(code, payload) where code is the OOB sub-code (scalar integer) and payload is the content passed in the OOB command. For OOB_SEND the result of the callback is disarded, for OOB_MSG the result is encoded and sent back to the server. Note that OOB commands in this client are only processed when waiting for the response to another command (typically RS.eval). OOB commands must be explicitly enabled in the server in order to be used (they are disabled by default).

Examples

c <- RS.connect()
  RS.eval(c, data(stackloss))
  RS.eval(c, library(MASS))
  RS.eval(c, rlm(stack.loss ~ ., stackloss)$coeff)
  RS.eval(c, getwd())
  RS.close(c)