|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Objectjava.lang.Thread
org.rosuda.JRI.Rengine
public class Rengine
Rengine class is the interface between an instance of R and the Java VM. Due to the fact that R has no threading support, you can run only one instance of R withing a multi-threaded application. There are two ways to use R from Java: individual call and full event loop. See the Rengine constructor for details.
Important note: All methods starting with rni (R Native Interface) are low-level native methods that should be avoided if a high-level methods exists. They do NOT attempt any synchronization, so it is the duty of the calling program to ensure that the invocation is safe (see getRsync() for details). At some point in the future when the high-level API is complete they should become private. However, currently this high-level layer is not complete, so they are available for now.
All rni methods use long type to reference SEXPs on R side. Those reference should never be modified or used in arithmetics - the only reason for not using an extra interface class to wrap those references is that rni methods are all native methods and therefore it would be too expensive to handle the unwrapping on the C side.
jri methods are called internally by R and invoke the corresponding method from the even loop handler. Those methods should usualy not be called directly.
| Nested Class Summary |
|---|
| Nested classes/interfaces inherited from class java.lang.Thread |
|---|
Thread.State, Thread.UncaughtExceptionHandler |
| Field Summary | |
|---|---|
static int |
DEBUG
debug flag. |
int |
idleDelay
this value specifies the time (in ms) to spend sleeping between checks for R shutdown requests if R event loop is not used. |
| Fields inherited from class java.lang.Thread |
|---|
MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY |
| Constructor Summary | |
|---|---|
Rengine(String[] args,
boolean runMainLoop,
RMainLoopCallbacks initialCallbacks)
create and start a new instance of R. |
|
| Method Summary | |
|---|---|
void |
addMainLoopCallbacks(RMainLoopCallbacks c)
Add a handler for R callbacks. |
void |
assign(String sym,
boolean[] val)
assign values of an array of booleans to a symbol in R (creating a logical vector). |
void |
assign(String sym,
double[] val)
assign values of an array of doubles to a symbol in R (creating an integer vector). |
void |
assign(String sym,
int[] val)
assign values of an array of integers to a symbol in R (creating a numeric vector). |
void |
assign(String sym,
REXP r)
assign a content of a REXP to a symbol in R. |
void |
assign(String sym,
String ct)
assign a string value to a symbol in R. |
void |
assign(String sym,
String[] val)
assign values of an array of strings to a symbol in R (creating a character vector). |
void |
end()
attempt to shut down R. |
REXP |
eval(String s)
Parses and evaluates an R expression and returns the result. |
REXP |
eval(String s,
boolean convert)
Parses and evaluates an R expression and returns the result. |
static Rengine |
getMainEngine()
return the current main R engine instance. |
Mutex |
getRsync()
returns the synchronization mutex for this engine. |
static long |
getVersion()
API version of the Rengine itself; see also rniGetVersion() for binary version. |
REXP |
idleEval(String s)
This method is very much like eval(String), except that it is non-blocking and returns null if the engine is busy. |
REXP |
idleEval(String s,
boolean convert)
This method is very much like eval(String,boolean), except that it is non-blocking and returns null if the engine is busy. |
void |
jriBusy(int which)
JRI: R_Busy call-back from R |
String |
jriChooseFile(int newFile)
JRI: R_ChooseFile call-back from R |
void |
jriFlushConsole()
JRI: R_FlushConsole call-back from R |
void |
jriLoadHistory(String filename)
JRI: R_loadhistory call-back from R |
String |
jriReadConsole(String prompt,
int addToHistory)
JRI: R_ReadConsole call-back from R. |
void |
jriSaveHistory(String filename)
JRI: R_savehistory call-back from R |
void |
jriShowMessage(String message)
JRI: R_ShowMessage call-back from R |
void |
jriWriteConsole(String text)
JRI: R_WriteConsole call-back from R |
void |
rniAssign(String name,
long exp,
long rho)
RNI: assign a value to an environment |
long |
rniCAR(long exp)
RNI: get CAR of a dotted-pair list (LISTSXP) |
long |
rniCDR(long exp)
RNI: get CDR of a dotted-pair list (LISTSXP) |
long |
rniCons(long head,
long tail)
RNI: create a dotted-pair list (LISTSXP) |
long |
rniEval(long exp,
long rho)
RNI: evaluate R expression (do NOT use directly unless you know exactly what you're doing, where possible use eval(java.lang.String) instead). |
int |
rniExpType(long exp)
RNI: get the SEXP type |
long |
rniGetAttr(long exp,
String name)
RNI: get an attribute |
int[] |
rniGetBoolArrayI(long exp)
RNI: get the contents of a logical vector in its integer array form |
double[] |
rniGetDoubleArray(long exp)
RNI: get the contents of a numeric vector |
int[] |
rniGetIntArray(long exp)
RNI: get the contents of an integer vector |
long[] |
rniGetList(long exp)
RNI: retrieve CAR part of a dotted-part list recursively as an array of references |
String |
rniGetString(long exp)
RNI: get the contents of the first entry of a character vector |
String[] |
rniGetStringArray(long exp)
RNI: get the contents of a character vector |
String |
rniGetSymbolName(long sym)
RNI: retrieve name of a symbol (c.f. |
long[] |
rniGetVector(long exp)
RNI: get the contents of a generic vector (aka list) |
static long |
rniGetVersion()
RNI: return the API version of the native library |
void |
rniIdle()
RNI: run other event handlers in R |
boolean |
rniInherits(long exp,
String cName)
RNI: determines whether an R object instance inherits from a specific class (S3 for now) |
long |
rniInstallSymbol(String sym)
RNI: install a symbol name |
long |
rniParse(String s,
int parts)
RNI: parses a string into R expressions (do NOT use directly unless you know exactly what you're doing, where possible use eval(java.lang.String) instead). |
void |
rniProtect(long exp)
RNI: protect an R object (c.f. |
long |
rniPutBoolArray(boolean[] a)
RNI: create a boolean vector |
long |
rniPutBoolArrayI(int[] a)
RNI: create a boolean vector from an integer vector |
long |
rniPutDoubleArray(double[] a)
RNI: create a numeric vector |
long |
rniPutIntArray(int[] a)
RNI: create an integer vector |
long |
rniPutList(long[] cont)
RNI: create a dotted-pair list (LISTSXP) |
long |
rniPutString(String s)
RNI: create a character vector of the length 1 |
long |
rniPutStringArray(String[] a)
RNI: create a character vector |
long |
rniPutVector(long[] exps)
RNI: create a generic vector (aka a list) |
void |
rniRunMainLoop()
RNI: run the main loop. |
void |
rniSetAttr(long exp,
String name,
long attr)
RNI: set an attribute |
int |
rniStop(int flag)
RNI: interrupt the R process (if possible) |
long |
rniTAG(long exp)
RNI: get TAG of a dotted-pair list (LISTSXP) |
void |
rniUnprotect(int count)
RNI: unprotect last count references (c.f. |
void |
run()
The implementation of the R thread. |
void |
startMainLoop()
if Rengine was initialized with runMainLoop=false then this method can be used to start the main loop at a later point. |
static boolean |
versionCheck()
check API version of this class and the native binary. |
boolean |
waitForR()
check the state of R |
| Methods inherited from class java.lang.Thread |
|---|
activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield |
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
| Field Detail |
|---|
public static int DEBUG
public int idleDelay
Thread.stop() uses interrupt to awake from the idle sleep immediately, but some implementation may not honor that).
| Constructor Detail |
|---|
public Rengine(String[] args,
boolean runMainLoop,
RMainLoopCallbacks initialCallbacks)
args - arguments to be passed to R. Please note that R requires the presence of certain arguments (e.g. --save or --no-save or equivalents), so passing an empty list usually doesn't work.runMainLoop - if set to true the the event loop will be started as soon as possible, otherwise no event loop is started. Running loop requires initialCallbacks to be set correspondingly as well.initialCallbacks - an instance implementing the RMainLoopCallbacks interface that provides methods to be called by R| Method Detail |
|---|
public static long getVersion()
versionCheck()
long in the form 0xMMmmpublic static boolean versionCheck()
true if the API version of the Java code and the native library matches, false otherwisepublic static Rengine getMainEngine()
null if no R engine was started yet.
public long rniParse(String s,
int parts)
eval(java.lang.String) instead). Note that no synchronization is performed!
s - string to parseparts - number of expressions contained in the string
public long rniEval(long exp,
long rho)
eval(java.lang.String) instead). Note that no synchronization is performed!
exp - reference to the expression to evaluaterho - environment to use for evaluation (or 0 for global environemnt)
public void rniProtect(long exp)
exp - reference to protectpublic void rniUnprotect(int count)
count references (c.f. UNPROTECT in C)
count - number of references to unprotectpublic String rniGetString(long exp)
exp - reference to STRSXP
null if the reference is not STRSXPpublic String[] rniGetStringArray(long exp)
exp - reference to STRSXP
null if the reference is not STRSXPpublic int[] rniGetIntArray(long exp)
exp - reference to INTSXP
null if the reference is not INTSXPpublic int[] rniGetBoolArrayI(long exp)
exp - reference to LGLSXP
null if the reference is not LGLSXPpublic double[] rniGetDoubleArray(long exp)
exp - reference to REALSXP
null if the reference is not REALSXPpublic long[] rniGetVector(long exp)
exp - reference to VECSXP
null if the reference is not VECSXPpublic long rniPutString(String s)
s - initial contents of the first entry
public long rniPutStringArray(String[] a)
a - initial contents of the vector
public long rniPutIntArray(int[] a)
a - initial contents of the vector
public long rniPutBoolArrayI(int[] a)
a - initial contents of the vector
public long rniPutBoolArray(boolean[] a)
a - initial contents of the vector
public long rniPutDoubleArray(double[] a)
a - initial contents of the vector
public long rniPutVector(long[] exps)
exps - initial contents of the vector consisiting of an array of references
public long rniGetAttr(long exp,
String name)
exp - reference to the object whose attribute is requestedname - name of the attribute
public void rniSetAttr(long exp,
String name,
long attr)
exp - reference to the object whose attribute is to be modifiedname - attribute nameattr - reference to the object to be used as teh contents of the attribute
public boolean rniInherits(long exp,
String cName)
exp - reference to an objectcName - name of the class to check
true if cName inherits from class cName (see inherits in R)
public long rniCons(long head,
long tail)
head - CARtail - CDR (must be a reference to LISTSXP or 0)
public long rniCAR(long exp)
exp - reference to the list
public long rniCDR(long exp)
exp - reference to the list
public long rniTAG(long exp)
exp - reference to the list
public long rniPutList(long[] cont)
cont - contents as an array of references
public long[] rniGetList(long exp)
exp - reference to a dotted-pair list (LISTSXP)
public String rniGetSymbolName(long sym)
sym - reference to a symbol
null on error or if exp is no symbolpublic long rniInstallSymbol(String sym)
sym - symbol name
public static long rniGetVersion()
public int rniStop(int flag)
flag - currently ignored, must be set to 0
public void rniAssign(String name,
long exp,
long rho)
name - nameexp - valuerho - environment (use 0 for the global environment)public int rniExpType(long exp)
exp - reference to a SEXP
public void rniRunMainLoop()
public void rniIdle()
public void addMainLoopCallbacks(RMainLoopCallbacks c)
public void startMainLoop()
runMainLoop=false then this method can be used to start the main loop at a later point. It has no effect if the loop is running already. This method returns immediately but the loop will be started once the engine is ready. Please note that there is currently no way of stopping the R thread if the R event loop is running other than using quit command in R which closes the entire application.
public void jriWriteConsole(String text)
text - text to displypublic void jriBusy(int which)
which - state
public String jriReadConsole(String prompt,
int addToHistory)
prompt - prompt to display before waiting for the input.addToHistory - flag specifying whether the entered contents should be added to history
null corresponds to an EOF and usually causes R to exit (as in q()).public void jriShowMessage(String message)
message - messagepublic void jriLoadHistory(String filename)
filename - name of the history filepublic void jriSaveHistory(String filename)
filename - name of the history filepublic String jriChooseFile(int newFile)
newFile - flag specifying whether an existing or new file is requested
null if cancelledpublic void jriFlushConsole()
public REXP eval(String s)
eval(s, true).
s - expression (as string) to parse and evaluate
null if something wnet wrong
public REXP eval(String s,
boolean convert)
s - expression (as string) to parse and evaluateconvert - if set to true the resulting REXP will contain native representation of the contents, otherwise an empty REXP will be returned. Depending on the back-end an empty REXP may or may not be used to convert the result at a later point.
null if something wnet wrongpublic REXP idleEval(String s)
eval(String), except that it is non-blocking and returns null if the engine is busy.
s - string to evaluate
null if the engine is busy
public REXP idleEval(String s,
boolean convert)
eval(String,boolean), except that it is non-blocking and returns null if the engine is busy.
s - string to evaluateconvert - flag denoting whether an empty or fully-converted REXP should be returned (see eval(String,boolean) for details)
null if the engine is busypublic Mutex getRsync()
boolean obtainedLock = e.getRsync().safeLock();
try {
// use RNI here ...
} finally {
if (obtainedLock) e.getRsync().unlock();
}
public boolean waitForR()
true if R is alive and false if R died or exittedpublic void end()
public void run()
run in interface Runnablerun in class Thread
public void assign(String sym,
String ct)
sym - symbol name. The symbol name is used as-is, i.e. as if it was quoted in R code (for example assigning to "foo$bar" has the same effect as `foo$bar`<- and NOT foo$bar<-).ct - contents
public void assign(String sym,
REXP r)
sym - symbol name. The symbol name is used as-is, i.e. as if it was quoted in R code (for example assigning to "foo$bar" has the same effect as `foo$bar`<- and NOT foo$bar<-).r - contents as REXP. currently only raw references and basic types (int, double, int[], double[], boolean[]) are supported.
public void assign(String sym,
double[] val)
assign(String, REXP).
sym - symbol nameval - double array to assign
public void assign(String sym,
int[] val)
assign(String, REXP).
sym - symbol nameval - integer array to assign
public void assign(String sym,
boolean[] val)
assign(String, REXP).
sym - symbol nameval - boolean array to assign
public void assign(String sym,
String[] val)
assign(String, REXP).
sym - symbol nameval - string array to assign
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||