add .jvmState(), closes #259

Author: s-u

NEWS

@@ -19,6 +19,8 @@
 
     o	Work around a crash in RStudio on UCRT Windows. (#296)
 
+    o	add .jvmState() reporting the state of the JVM. (#259)
+
 
 1.0-6	2021-12-10
     o	remove obsolete autoconf macros

R/jfirst.R

@@ -22,6 +22,7 @@
                     "RgetShortArrayCont", "RgetStringArrayCont", "RidenticalRef", "RgetSimpleClassNames",
                     "RisAssignableFrom", "RpollException", "RsetField", "RthrowException",
                     "javaObjectCache", "initRJavaTools", "newRJavaLookupTable", "useDynamicSymbols",
+                    "RgetJVMstate",
                      # .External
                     "RcreateObject", "RgetStringValue", "RinitJVM", "RtoString", "RcallMethod",
                      # .C

R/jinit.R

@@ -230,3 +230,5 @@
   } # if #rcp>0
   invisible(.jcall("java/lang/System","S","getProperty","java.class.path"))
 }
+
+.jvmState <- function() .Call(RgetJVMstate)

man/jinit.Rd

@@ -1,15 +1,19 @@
 \name{jinit}
 \alias{.jinit}
+\alias{.jvmState}
 \title{
   Initialize Java VM
 }
 \description{
   \code{.jinit} initializes the Java Virtual Machine (JVM). This
   function must be called before any rJava functions can be used.
+
+  \code{.jvmState() returns the state of the current JVM.}
 }
 \usage{
 .jinit(classpath = NULL, parameters = getOption("java.parameters"), ...,
 silent = FALSE, force.init = FALSE)
+.jvmState()
 }
 \arguments{
   \item{classpath}{Any additional classes to include in the Java class
@@ -33,6 +37,20 @@ silent = FALSE, force.init = FALSE)
   initialization and positive values signify partially successful
   initilization (i.e. the VM is up, but parameters or class path could
   not be set due to an existing or incompatible VM).
+
+  \code{.jvmState} returns a named list with at least the following
+  elements:
+  \item{initialized}{\code{TRUE} if rJava is initialized and has a
+    runing JVM, \code{FALSE} otherwise.}
+  \item{state}{string representing the current state of the JVM. One of
+    the following values:
+    \code{"none"} if there is no JVM, \code{"created"} if the current
+    JVM has been created by rJava, \code{"attached"} if rJava attached
+    into an existing JVM (typically when R is embedded into a running
+    JVM via JRI), \code{"detached"} if there is a JVM (such as embedded
+    R), but rJava has not been initialized to use it, \code{"dead"} if
+    the process is about to die due to the JVM forcing en exit or
+    \code{"destroyed"} if a JVM existed before, but was destroyed.}
 }
 \details{
   Starting with version 0.5 rJava provides a custom class loader that can
@@ -59,7 +77,18 @@ silent = FALSE, force.init = FALSE)
   At any rate, it is impossible to change any other VM parameters of a
   running VM, so when using \code{.jinit} in a package, be generous with
   limits and don't use VM parameters to unnecessarily restrict
-  resources (or preferably use \code{\link{.jpackage}} instead).
+  resources (or preferably use \code{\link{.jpackage}} instead). JVM
+  parameters can only be set if the initial state of the JVM is
+  \code{"none"}.
+
+  There is a subtle difference between \code{"initialized"} and the JVM
+  state. It is in theory possible for \code{"initialized"} to be
+  \code{FALSE} and still \code{"state"} to be \code{"created"} or
+  \code{"attached"} in case where JVM was created but rJava has not been
+  able to initialize for other reasons, although such state should be
+  rare and problematic in either case. Behavior of rJava functions other
+  than \code{.jinit} and \code{.jvmState} is undefined unless
+  \code{.jvmState()$initialized} is \code{TRUE}.
 }
 \seealso{
   \code{\link{.jpackage}}
@@ -69,6 +98,7 @@ silent = FALSE, force.init = FALSE)
 ## set heap size limit to 512MB (see java -X) and
 ## use "myClasses.jar" as the class path
 .jinit(classpath="myClasses.jar", parameters="-Xmx512m")
+.jvmState()
 }
 }
 \keyword{interface}

src/Rglue.c

@@ -1124,3 +1124,24 @@ END_RJAVA_CALL
   INTEGER(res)[0]=tr;
   return res;
 }
+
+extern int existingJVMs(); /* init.c */
+
+REPC SEXP RgetJVMstate() {
+    const char *names[] = { "initialized", "state", "" };
+    SEXP res = PROTECT(Rf_mkNamed(VECSXP, names));
+    const char *st = "unknown";
+    switch (rJava_JVM_state) {
+    case JVM_STATE_NONE: /* could be detached */
+	st = (existingJVMs() > 0) ? "detached" : "none";
+	break;
+    case JVM_STATE_CREATED:   st = "created"; break;
+    case JVM_STATE_ATTACHED:  st = "attached"; break;
+    case JVM_STATE_DEAD:      st = "dead"; break;
+    case JVM_STATE_DESTROYED: st = "destroyed"; break;
+    }
+    SET_VECTOR_ELT(res, 0, Rf_ScalarLogical(rJava_initialized));
+    SET_VECTOR_ELT(res, 1, Rf_mkString(st));
+    UNPROTECT(1);
+    return res;
+}

src/init.c

@@ -9,6 +9,9 @@ JavaVM *jvm;
 /* this will be set when Java tries to exit() but we carry on */
 int java_is_dead = 0;
 
+/* current JVM state */
+int rJava_JVM_state = JVM_STATE_NONE;
+
 /* cached, global objects */
 
 jclass javaStringClass;
@@ -78,13 +81,20 @@ static int JNICALL vfprintf_hook(FILE *f, const char *fmt, va_list ap) {
 static void JNICALL exit_hook(int status) {
     /* REprintf("\nJava requested System.exit(%d), trying to raise R error - this may crash if Java is in a bad state.\n", status); */
     java_is_dead = 1;
+    rJava_JVM_state = JVM_STATE_DEAD;
     Rf_error("Java called System.exit(%d) requesting R to quit - trying to recover", status);
     /* FIXME: we could do something smart here such as running a call-back
        into R ... jump into R event loop ... at any rate we cannot return,
        but we don't want to kill R ... */
     exit(status);
 }
 
+int existingJVMs() {
+    jsize vms = 0;
+    JavaVM *jvms[32];
+    return (JNI_GetCreatedJavaVMs(jvms, 32, &vms) >= 0) ? vms : 0;
+}
+
 /* in reality WIN64 implies WIN32 but to make sure ... */
 #if defined(_WIN64) || defined(_WIN32)
 #include <io.h>
@@ -186,6 +196,7 @@ static int initJVM(const char *user_classpath, int opts, char **optv, int hooks,
   if (!eenv)
     error("Cannot obtain JVM environment");
 
+  rJava_JVM_state = JVM_STATE_CREATED;
 #if defined(_WIN64) || defined(_WIN32)
   _setmode(0, _O_TEXT);
 #endif
@@ -217,6 +228,8 @@ static void *initJVMthread(void *classpath)
   thInitResult=initJVM((char*)classpath, jvm_opts, jvm_optv, default_hooks, 0);
   if (thInitResult) return 0;
 
+  rJava_JVM_state = JVM_STATE_CREATED;
+
   init_rJava();
 
   lenv = eenv; /* we make a local copy before unlocking just in case
@@ -357,7 +370,10 @@ static SEXP RinitJVM_real(SEXP par, int disableGuardPages)
       while (i<vms) {
 	if (jvms[i]) {
 	  if (!(*jvms[i])->AttachCurrentThread(jvms[i], (void**)&eenv, NULL)) {
-            _dbg(rjprintf("RinitJVM: Attached to existing JVM #%d.\n", i+1));
+	      /* attaching our own created JVM doesn't change it to attached */
+	      if (rJava_JVM_state != JVM_STATE_CREATED)
+		  rJava_JVM_state = JVM_STATE_ATTACHED;
+	      _dbg(rjprintf("RinitJVM: Attached to existing JVM #%d.\n", i+1));
 	    break;
 	  }
 	}
@@ -389,6 +405,8 @@ static SEXP RinitJVM_real(SEXP par, int disableGuardPages)
   _dbg(rjprintf("RinitJVM(threads): attach\n"));
   /* since JVM was initialized by another thread, we need to attach ourselves */
   (*jvm)->AttachCurrentThread(jvm, (void**)&eenv, NULL);
+  if (rJava_JVM_state != JVM_STATE_CREATED)
+      rJava_JVM_state = JVM_STATE_ATTACHED;
   _dbg(rjprintf("RinitJVM(threads): done.\n"));
   r = thInitResult;
 #else
@@ -752,6 +770,7 @@ REP void doneJVM() {
   (*jvm)->DestroyJavaVM(jvm);
   jvm = 0;
   eenv = 0;
+  rJava_JVM_state = JVM_STATE_DESTROYED;
 }
 
 /**

src/rJava.h

@@ -136,6 +136,14 @@ REPC SEXP RgetSimpleClassNames( SEXP, SEXP );
 extern JavaVM *jvm;
 extern int rJava_initialized;
 
+#define JVM_STATE_NONE      0  /* no JVM */
+#define JVM_STATE_CREATED   1  /* JVM was created by us */
+#define JVM_STATE_ATTACHED  2  /* we attached to another JVM */
+#define JVM_STATE_DEAD      4  /* set when Java exit handler was called */
+#define JVM_STATE_DESTROYED 8  /* JVM was destroyed */
+
+extern int rJava_JVM_state;
+
 extern int java_is_dead;
 
 extern jclass javaStringClass;