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.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private static class 
    SystemPlume.GcHistoryItem
    A triple of (timestamp, collection time, subsequent timestamp).

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static Deque<SystemPlume.GcHistoryItem>
    gcHistory
    The history of recent garbage collection runs.
    private static Runtime
    runtime
    The Runtime instance for the current execution.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    SystemPlume()
    This class is a collection of methods; it does not represent anything.

  • 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".
    private static long
    getCollectionCount()
    Returns the number of garbage collections that have occurred.
    private static long
    getCollectionTime()
    Returns the cumulative garbage collection time in milliseconds, across all threads.
    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

  • Field Details

    • runtime

      private static Runtime runtime
      The Runtime instance for the current execution.

    • gcHistory

      private static Deque<SystemPlume.GcHistoryItem> gcHistory
      The history of recent garbage collection runs. The queue is never empty.

  • Constructor Details

    • SystemPlume

      private SystemPlume()
      This class is a collection of methods; it does not represent anything.

  • 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.

    • getCollectionCount

      private static long getCollectionCount()
      Returns the number of garbage collections that have occurred.
      Returns:
      the number of garbage collections that have occurred

    • getCollectionTime

      private static long getCollectionTime()
      Returns the cumulative garbage collection time in milliseconds, across all threads.
      Returns:
      the cumulative garbage collection time in milliseconds

    • 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