Package org.plumelib.util

Class SystemPlume

java.lang.Object
org.plumelib.util.SystemPlume
public final class SystemPlume extends Object
Utility methods relating to the JVM runtime system: sleep and garbage collection.

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    gc()
    Perform garbage collection.
    static double
    gcPercentage()
    Calls `gcPercentage(60)`.
    static double
    gcPercentage(int seconds)
    Returns the fraction of time spent garbage collecting, in the past seconds seconds.
    static @Nullable String
    gcUsageMessage(double cpuThreshold, int seconds)
    If the fraction of time spent garbage collecting in the past seconds seconds is less than cpuThreshold, returns null.
    static boolean
    getBooleanSystemProperty(String key)
    Determines whether a system property has a string value that represents true: "true", "yes", or "1".
    static boolean
    getBooleanSystemProperty(String key, boolean defaultValue)
    Determines whether a system property has a string value that represents true: "true", "yes", or "1".
    static void
    sleep(long millis)
    Like Thread.sleep, but does not throw any checked exceptions, so it is easier for clients to use.
    static long
    usedMemory()
    Returns the amount of used memory in the JVM.
    static long
    usedMemory(boolean forceGc)
    Returns the amount of used memory in the JVM.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • getBooleanSystemProperty

      @Pure public static boolean getBooleanSystemProperty(String key, boolean defaultValue)
      Determines whether a system property has a string value that represents true: "true", "yes", or "1". Errs if the property is set to a value that is not one of "true", "false", "yes", "no", "1", or "0".
      Parameters:
      key - name of the property to look up
      defaultValue - the value to return if the property is not set
      Returns:
      true iff the property has a string value that represents true

    • getBooleanSystemProperty

      @Pure public static boolean getBooleanSystemProperty(String key)
      Determines whether a system property has a string value that represents true: "true", "yes", or "1". Errs if the property is set to a value that is not one of "true", "false", "yes", "no", "1", or "0".
      Parameters:
      key - name of the property to look up
      Returns:
      true iff the property has a string value that represents true

    • sleep

      public static void sleep(long millis)
      Like Thread.sleep, but does not throw any checked exceptions, so it is easier for clients to use. Causes the currently executing thread to sleep (temporarily cease execution) for the specified number of milliseconds.
      Parameters:
      millis - the length of time to sleep in milliseconds

    • usedMemory

      public static long usedMemory()
      Returns the amount of used memory in the JVM.

      To force a garbage collection, which gives a more accurate overapproximation of the memory used, but is also slower, use usedMemory(boolean)

      Returns:
      the amount of used memory

    • usedMemory

      public static long usedMemory(boolean forceGc)
      Returns the amount of used memory in the JVM.
      Parameters:
      forceGc - if true, force a garbage collection, which gives a more accurate overapproximation of the memory used, but is also slower
      Returns:
      the amount of used memory

    • gc

      public static void gc()
      Perform garbage collection. Like System.gc, but waits to return until garbage collection has completed.

    • gcPercentage

      public static double gcPercentage()
      Calls `gcPercentage(60)`.
      Returns:
      the percentage of time spent garbage collecting, in the past minute
      See Also:

    • gcPercentage

      public static double gcPercentage(int seconds)
      Returns the fraction of time spent garbage collecting, in the past seconds seconds. This is generally a value between 0 and 1. This method might return a value greater than 1 if multiple threads are spending all their time collecting. Returns 0 if gcPercentage was not first called more than seconds seconds ago.

      This method also discards all GC history older than seconds seconds.

      Instead of calling this method directly, a client program might call gcUsageMessage(double, int).

      Parameters:
      seconds - the size of the time window, in seconds
      Returns:
      the percentage of time spent garbage collecting, in the past seconds seconds

    • gcUsageMessage

      public static @Nullable String gcUsageMessage(double cpuThreshold, int seconds)
      If the fraction of time spent garbage collecting in the past seconds seconds is less than cpuThreshold, returns null. Otherwise, returns a string indicating garbage collection CPU usage and memory statistics. The string is multiple lines long, but does not end with a line separator.

      A typical use is to put the following in an outer loop that takes a significant amount of time (more than a second) to execute: 

      
 String message = gcUsageMessage(.25, 60);
 if (message != null) {
   System.err.println(message);
 }
      Parameters:
      cpuThreshold - the maximum fraction of CPU that should be spent garbage collecting; a number between 0 and 1
      seconds - the time window in which to compute the garbage collection CPU usage
      Returns:
      a GC usage message string, or null