Merge pull request #63 from scijava/jvm-config-shortcuts

Add JVM config shortcuts

Author: ctrueden

.github/workflows/build.yml

@@ -22,7 +22,6 @@ jobs:
           macos-latest
         ]
         python-version: [
-          '3.7',
           '3.8',
           '3.9',
           '3.10'

README.md

@@ -158,6 +158,15 @@ FUNCTIONS
         Add a converter to the list used by to_python.
         :param converter: A Converter from java to python
 
+    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.
+
     enable_python_scripting(context)
         Adds a Python script runner object to the ObjectService of the given
         SciJava context. Intended for use in conjunction with
@@ -166,6 +175,13 @@ FUNCTIONS
         :param context: The org.scijava.Context containing the ObjectService
             where the PythonScriptRunner should be injected.
 
+    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.
+
     get_version(java_class_or_python_package) -> str
         Return the version of a Java class or Python package.
 
@@ -254,12 +270,21 @@ FUNCTIONS
     jclass(data)
         Obtain a Java class object.
 
-        :param data: The object from which to glean the class.
         Supported types include:
-        A. Name of a class to look up, analogous to
-        Class.forName("java.lang.String");
-        B. A jpype.JClass object analogous to String.class;
-        C. A jpype.JObject instance analogous to o.getClass().
+
+        A. Name of a class to look up -- e.g. "java.lang.String" --
+           which returns the equivalent of Class.forName("java.lang.String").
+
+        B. A static-style class reference -- e.g. String --
+           which returns the equivalent of String.class.
+
+        C. A Java object -- e.g. foo --
+           which returns the equivalent of foo.getClass().
+
+        Note that if you pass a java.lang.Class object, you will get back Class.class,
+        i.e. the Java class for the Class class. :-)
+
+        :param data: The object from which to glean the class.
         :returns: A java.lang.Class object, suitable for use with reflection.
         :raises TypeError: if the argument is not one of the aforementioned types.
 
@@ -297,28 +322,63 @@ FUNCTIONS
         Return true iff a Java virtual machine (JVM) has been started.
 
     jvm_version() -> str
-        Gets the version of the JVM as a tuple,
-        with each dot-separated digit as one element.
-        Characters in the version string beyond only
-        numbers and dots are ignored, in line
-        with the java.version system property.
+        Gets the version of the JVM as a tuple, with each dot-separated digit
+        as one element. Characters in the version string beyond only numbers
+        and dots are ignored, in line with the java.version system property.
 
         Examples:
         * OpenJDK 17.0.1 -> [17, 0, 1]
         * OpenJDK 11.0.9.1-internal -> [11, 0, 9, 1]
         * OpenJDK 1.8.0_312 -> [1, 8, 0]
 
-        If the JVM is already started,
-        this function should return the equivalent of:
+        If the JVM is already started, this function returns the equivalent of:
            jimport('java.lang.System')
              .getProperty('java.version')
              .split('.')
 
-        In case the JVM is not started yet,a best effort is made to deduce
+        In case the JVM is not started yet, a best effort is made to deduce
         the version from the environment without actually starting up the
         JVM in-process. If the version cannot be deduced, a RuntimeError
         with the cause is raised.
 
+    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.
+
+    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.
+
+    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.
+
     shutdown_jvm() -> None
         Shutdown the JVM.
 
@@ -338,6 +398,8 @@ FUNCTIONS
         Note that if the JVM is not already running, then this function does
         nothing! In particular, shutdown hooks are skipped in this situation.
 
+        :raises RuntimeError: if this method is called while in Jep mode.
+
     start_jvm(options=None) -> None
         Explicitly connect to the Java virtual machine (JVM). Only one JVM can
         be active; does nothing if the JVM has already been started. Calling

dev-environment.yml

@@ -19,7 +19,7 @@ channels:
   - conda-forge
   - defaults
 dependencies:
-  - python >= 3.7
+  - python >= 3.8
   # Project dependencies
   - jpype1 >= 1.3.0
   - jgo

environment.yml

@@ -20,7 +20,7 @@ channels:
   - conda-forge
   - defaults
 dependencies:
-  - python >= 3.7
+  - python >= 3.8
   # Project dependencies
   - jpype1 >= 1.3.0
   - jgo

pyproject.toml

@@ -16,7 +16,6 @@ classifiers = [
     "Intended Audience :: Education",
     "Intended Audience :: Science/Research",
     "Programming Language :: Python :: 3 :: Only",
-    "Programming Language :: Python :: 3.7",
     "Programming Language :: Python :: 3.8",
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
@@ -31,7 +30,7 @@ classifiers = [
 ]
 
 # NB: Keep this in sync with environment.yml AND dev-environment.yml!
-requires-python = ">=3.7"
+requires-python = ">=3.8"
 dependencies = [
     "jpype1 >= 1.3.0",
     "jgo",
@@ -77,7 +76,7 @@ exclude = ["bin", "build", "dist"]
 extend-ignore = ["E203"]
 # See https://black.readthedocs.io/en/stable/guides/using_black_with_other_tools.html#flake8
 max-line-length = 88
-min_python_version = "3.7"
+min_python_version = "3.8"
 
 [tool.isort]
 profile = "black"

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()

src/scyjava/_versions.py

@@ -3,7 +3,7 @@
 """
 
 import logging
-from importlib.util import find_spec
+from importlib.metadata import version
 
 from ._java import isjava, jimport
 
@@ -32,20 +32,7 @@ def get_version(java_class_or_python_package) -> str:
         return str(VersionUtils.getVersion(java_class_or_python_package))
 
     # Assume we were given a Python package name.
-
-    if find_spec("importlib.metadata"):
-        # Fastest, but requires Python 3.8+.
-        from importlib.metadata import version
-
-        return version(java_class_or_python_package)
-
-    if find_spec("pkg_resources"):
-        # Slower, but works on Python 3.7.
-        from pkg_resources import get_distribution
-
-        return get_distribution(java_class_or_python_package).version
-
-    raise RuntimeError("Cannot determine version! Is pkg_resources installed?")
+    return version(java_class_or_python_package)
 
 
 def is_version_at_least(actual_version: str, minimum_version: str) -> bool: