Add convenience functions for checking JVM config

After the JVM has started, it is nice to be able to easily check
characteristics of the JVM from the Runtime API, including current and
maximum heap sizes, as well as number of available processors. (It is
also nice to be able to easily split infinitives in a commit message.)

Relatedly, it can be nice to be able to call the garbage collector
directly.

Note that we do not expose the Runtime.getRuntime().freeMemory() method,
because it can be confusing: one would naively expect freeMemory() to
equal maxMemory() - usedMemory(), but in actuality it represents the
amount of free memory within the bounds of the memory already reserved
by the JVM *at the moment*. So it is typically not a very useful number.

Author: ctrueden

src/scyjava/__init__.py

@@ -96,6 +96,8 @@
 )
 from scyjava._java import (  # noqa: F401
     JavaClasses,
+    available_processors,
+    gc,
     is_awt_initialized,
     is_jarray,
     is_jvm_headless,
@@ -107,6 +109,9 @@
     jstacktrace,
     jvm_started,
     jvm_version,
+    memory_max,
+    memory_total,
+    memory_used,
     shutdown_jvm,
     start_jvm,
     when_jvm_starts,

src/scyjava/_java.py

@@ -66,7 +66,7 @@ def java_import(func: Callable[[], str]) -> Callable[[], jpype.JClass]:
         @property
         def inner(self):
             if not jvm_started():
-                raise Exception()
+                raise RuntimeError("JVM has not started yet!")
             try:
                 return jimport(func(self))
             except TypeError:
@@ -302,6 +302,80 @@ def jvm_started() -> bool:
     return jpype.isJVMStarted()
 
 
+def gc() -> None:
+    """
+    Do a round of Java garbage collection.
+
+    This function is a shortcut for Java's System.gc().
+
+    :raise RuntimeError: if the JVM has not yet been started.
+    """
+    _jc.System.gc()
+
+
+def memory_total() -> int:
+    """
+    Get the total amount of memory currently reserved by the JVM.
+
+    This number will always be less than or equal to memory_max().
+
+    In case the JVM was configured with -Xms flag upon startup (e.g. using
+    the scyjava.config.set_heap_min function), the initial value will typically
+    correspond approximately, but not exactly, to the configured value,
+    although it is likely to grow over time as more Java objects are allocated.
+
+    This function is a shortcut for Java's Runtime.getRuntime().totalMemory().
+
+    :return: The total memory in bytes.
+    :raise RuntimeError: if the JVM has not yet been started.
+    """
+    return int(_jc.Runtime.getRuntime().totalMemory())
+
+
+def memory_max() -> int:
+    """
+    Get the maximum amount of memory that the JVM will attempt to use.
+
+    This number will always be greater than or equal to memory_total().
+
+    In case the JVM was configured with -Xmx flag upon startup (e.g. using
+    the scyjava.config.set_heap_max function), the value will typically
+    correspond approximately, but not exactly, to the configured value.
+
+    This function is a shortcut for Java's Runtime.getRuntime().maxMemory().
+
+    :return: The maximum memory in bytes.
+    :raise RuntimeError: if the JVM has not yet been started.
+    """
+    return int(_jc.Runtime.getRuntime().maxMemory())
+
+
+def memory_used() -> int:
+    """
+    Get the amount of memory currently in use by the JVM.
+
+    This function is a shortcut for
+    Runtime.getRuntime().totalMemory() - Runtime.getRuntime().freeMemory().
+
+    :return: The used memory in bytes.
+    :raise RuntimeError: if the JVM has not yet been started.
+    """
+    return memory_total() - int(_jc.Runtime.getRuntime().freeMemory())
+
+
+def available_processors() -> int:
+    """
+    Get the number of processors available to the JVM.
+
+    This function is a shortcut for Java's
+    Runtime.getRuntime().availableProcessors().
+
+    :return: The number of available processors.
+    :raise RuntimeError: if the JVM has not yet been started.
+    """
+    return int(_jc.Runtime.getRuntime().availableProcessors())
+
+
 def is_jvm_headless() -> bool:
     """
     Return true iff Java is running in headless mode.
@@ -575,3 +649,15 @@ def jarray(kind, lengths: Sequence):
         for i in range(len(arr)):
             arr[i] = jarray(kind, lengths[1:])
     return arr
+
+
+# fmt: off
+class _JavaClasses(JavaClasses):
+    @JavaClasses.java_import
+    def Runtime(self):           return "java.lang.Runtime"        # noqa: E272
+    @JavaClasses.java_import
+    def System(self):            return "java.lang.System"         # noqa: E272
+# fmt: on
+
+
+_jc = _JavaClasses()