Rserve - Binary R server
RForge.net

Rserve

About Rserve
Documentation
Examples
FAQ
Download/Files
 
GIT access
Technical Info
Check results
Package R docs

Frequently Asked Questions (FAQ) for Rserve

How to start Rserve?
Rserve runs but neither Rcli nor the Java client are able to connect
How do I get textual output of commands from Rserve?
How can I get error messages from Rserve?
How can I prevent exit on error?
How can I retrieve multidimensional arrays or matrices from R?
How can I debug Rserve or see the structure of the evaluated data?
What is the format of the passwords file?
What are the limits of Rserve in terms of data size?
Which platforms/operating systems are supported by Rserve?
Where are Rcli and C/C++ client sources?
 

How to start Rserve?
One way to start Rserve is from within R, just type
library(Rserve)
Rserve()
That command knows how to find Rserve, how to setup the environment and how to start it, regardless of your platform.

Note: depending on how you are running R, it may require additional parameters such as --no-save (R will tell you). In that case you have to pass that parameter in the args argument such as

Rserve(args="--no-save")

However, Rserve is a stand-alone program, so it can be started directly as well. If you installed Rserve from a source package (on unix), type:

R CMD Rserve
in the shell/terminal. You should get something like this:
R version 2.9.1 (2009-06-26)
Copyright (C) 2009 The R Foundation for Statistical Computing
ISBN 3-900051-07-0

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.

Rserv started in daemon mode.
You can check whether Rserve runs with:
ps ax|grep Rserve
(or ps -A|grep Rserve depending on your unix).
You should get something like this:
2822  ??  Ss     0:00.73 /usr/local/lib/R/bin/Rserve

Windows users: If you downloaded Rserve.exe, put it in R's bin directory and start Rserve by double-clicking on the Rserve.exe file. While it is running it will appear in the task manager and there should be an output window.

Rserve runs but neither Rcli nor Java client are able to connect
         If you are running Rserve in local mode (which is the default), you must use the same machine for both the server and the client. Make sure you have no local firewall software running. The default Rserve port is 6311, make sure it is accessible. You can test whether Rserve responds by typing
telnet localhost 6311
If Rserve works, you should get:
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Rsrv0103QAP1

-------------- 
If you're trying to connect a remote Rserve, make sure remote access is enabled in the config file of the server (remote enable must be in the config file). You can test whether Rserve responds with the telnet command as in local connect case. Also check that there is no firewall between the client and the server, or that it is configured properly.
How do I get textual output of commands from Rserve?
Rserve doesn't return any output printed by the evaluated expressions. The idea is to return data in binary form, which is faster and more flexible. Nevertheless sometimes it may be convenient to simply reproduce the printed output given in R (such as a model summary). The R function capture.output can be used for that purpose - it returns a vector of strings (each entry correspnds to one line of output).

An example:

String s=c.eval("paste(capture.output(print(summary(mymodel))),collapse='\\n')").asString();
System.out.println(s);
Note: Don't forget to use print function if you want any output, because there is no implicit print() as in the REPL event loop (used by most GUIs)!
How can I get error messages from Rserve?
The question should really be "how can I get error messages from R", because Rserve is just a direct interface, so all the usual R rules apply. In fact there are two separate steps involved: parsing and evaluation. First, let's assume the expression can be parsed without an error so a potential error can occur only at the evaluation time (the most common case). The easiest way is to run try(..., silent=TRUE) since that guarantees a result in any case (except for a crash in R) and returns the verbatim error back. For example:
REXP r = c.parseAndEval("try("+myCode+",silent=TRUE)");
if (r.inherits("try-error")) System.err.println("Error: "+r.asString());
else { // success ... }
Alternatively it is possible to catch the REngineException and attempt to use c.parseAndEval("geterrmessage()").toString() - however that exception can also be thrown in other cases where there is no error description in R so it is less safe.

In cases where there is a potential for a parse error (think twice about your application if that's the case since it shows an inherent security flaw in your design!) and you want the full error string, you have to use the parse() function in R, beause there is no C API in R for obtaining the parse error string. It may look somewhat like:

c.assign(".tmp.", myCode);
REXP r = c.parseAndEval("try(eval(parse(text=.tmp.)),silent=TRUE)");
if (r.inherits("try-error")) System.err.println("Error: "+r.toString())
else { // success .. }
How can I prevent exit on error?
R has two modes that it can operate in - interactive and non-interactive. Unless instructed otherwise on error R returns to the top level in the interactive mode, but it quits in non-interactive mode - see the error option in ?options. If you are running R in non-interactive mode (by using interactive no in your Rserve config file since 0.6-2 or on Windows before that) you can prevent R from quitting by setting the error option, for example:
option(error=function() NULL)
It is not needed if R is run in the interactive mode.
How can I retrieve multidimensional arrays or matrices from R?
For matrices or 2-dimensional arrays see asDoubleMatrix/asIntMatrix accessor methods in REXP. In general all arrays and matrices are one-dimensional vectors in R stored in column-major format with dimensions as attributes.
How can I debug Rserve or see the structure of the evaluated data?
There is a special debug version of Rserve which displays a lot of information when run, among others all packets sent and results on the R side. By default it is compiled along with the regular version and can be found in the $RHOME/library/Rserve directory as Rserve.dbg. One way to run it is to use Rserve(TRUE) in R to start it. Another way (in unix) is to copy the Rserve.dbg file into $RHOME/bin and run it via
R CMD Rserve.dbg
Unlike the regular version this one doesn't daemonize but prints everything on the stdout. It is really verbose and much slower than the regular version, so use it for debugging purposes or if you want to analyze the R objects resulting from the evaluation.

BTW: Since 0.3-3 you can specify the number of array elements and dumped bytes that are printed. Use --RS-dumplimit <amount> command line parameter to change that setting. Default is 128 and specifying 0 means no limit.

What is the format of the passwords file?
It is a plain text (ASCII) file of the form
user password
one line for each user, password in clear text (so make sure you restrict the permissions on the file correspondingly). The user/password has nothing to do with your system users, so feel free to use anything.
What are the limits of Rserve in terms of data size?
Limits in versions up to 0.2-x:
  • Maximum size of a single REXP: 16MB (both ways, fixed)
  • Default packet size: 2MB (max. 1GB) configurable via CMD_setBufSize resp. setBufferSize in JRclient
Limits in version 0.3:
  • Maximum size of a single REXP: 2GB (on 32-bit platforms), theoretical limit is 2^55 on 64-bit platforms.
  • Packet size is auto-adjusted, configured by maxinbuf and maxsendbuf config entries. (maximum 2GB)
    The maxinbuf (max. packet from client to Rserve) and maxsendbuf (max. packet from Rserve to client) options in the configuration file allow you to set limits in order to prevent memory overflow on machines that act as servers for multiple connections. The defaults are 16MB and unlimited respectively.
BTW: 16MB corresponds roughly to 2 mio real numbers, so 1000x2000 matrices is about as big as you can go in versions 0.2 and lower. A work-around is to transmit data per-partes, e.g. by column or row (or use Rserve 0.3 or higher).

Data conversion on-the-fly (at least outgoing) is planned for future releases of Rserve (maybe).

Which platforms/operating systems are supported by Rserve?
Rserve should work on any plarform supporting shared libraries which is also supported by R. The following platforms were tested and are known to work:
  • Linux (PPC, x86)
  • Windows (x86)
  • Mac OS X / Darwin (PPC, x86)
  • AIX (PPC since version 0.1-10)
  • SunOS (sun4u since version 0.2)
  • HP-UX (HP-9000 since version 0.3-15)
All platforms except Windows support parallel connections and local (unix) sockets.
Where are Rcli and C/C++ client sources?
Rcli C client was removed from recent Rserve sources, because it was compatible only with Rserve version 0.1 and no one seemd to use it anyway (there's a nice direct C API to R). You can still find Rcli.c in the old source releases. It is obsolete by now since the C++ client was released in Rserve version 0.3-14. It can be found in the src/client/cxx directory. The C++ client can be compiled without R, just run the configure script in the Rserve directory and make in the src/client/cxx directory. There are also two examples supplied - see the ReadMe file supplied with the client (also useful for instructions how to compile it on Windows).