Class HeapMonitor

java.lang.Object
com.oracle.truffle.tools.profiler.HeapMonitor
All Implemented Interfaces:
Closeable, AutoCloseable
public final class HeapMonitor extends Object implements Closeable
Implementation of a heap allocation monitor for Truffle languages built on top of the Truffle instrumentation framework.

The HeapMonitor only tracks allocations while the heap monitor is collecting data. This means that allocations that were performed while the heap monitor was not collecting data are not tracked.

Usage example: 

try (Context context = Context.create()) {
    HeapMonitor monitor = HeapMonitor.find(context.getEngine());
    monitor.setCollecting(true);
    final Thread thread = new Thread(() -> {
        context.eval("...", "...");
    });
    thread.start();
    for (int i = 0; i < 10; i++) {
        final HeapSummary summary = monitor.takeSummary();
        final long aliveInstances = summary.getAliveInstances();
        final long totalInstances = summary.getTotalInstances();
        // ...
        Thread.sleep(100);
    }
    monitor.setCollecting(false);
}
// Print the number of live instances per meta object every 100ms.
Since:
19.0
See Also:

  • Method Details

    • find

      public static HeapMonitor find(org.graalvm.polyglot.Engine engine)
      Returns the HeapMonitor associated with a given engine.
      Parameters:
      engine - the engine to find debugger for
      Returns:
      an instance of associated HeapMonitor
      Since:
      19.0

    • setCollecting

      public void setCollecting(boolean collecting)
      Controls whether the HeapMonitor is collecting data or not.
      Parameters:
      collecting - the new state of the monitor.
      Throws:
      IllegalStateException - if the heap monitor was already closed
      Since:
      19.0

    • isCollecting

      public boolean isCollecting()
      Returns true if the heap monitor is collecting data, else false.
      Since:
      19.0

    • takeSummary

      public HeapSummary takeSummary()
      Returns a summary of the current state of the heap.

      The HeapMonitor only tracks allocations while the heap monitor is collecting data. This means that allocations that were performed while the heap monitor was not collecting data are not tracked.

      Throws:
      IllegalStateException - if the heap monitor was already closed
      Since:
      19.0

    • takeMetaObjectSummary

      public Map<com.oracle.truffle.api.nodes.LanguageInfo, Map<String, HeapSummary>> takeMetaObjectSummary()
      Returns a summary of the current state of the heap grouped by language and meta object name.

      The HeapMonitor only tracks allocations while the heap monitor is collecting data. This means that allocations that were performed while the heap monitor was not collecting are ignored. In other words the HeapMonitor reports snapshots as if the heap was completely empty when it was "enabled".

      Throws:
      IllegalStateException - if the heap monitor was already closed
      Since:
      19.0

    • clearData

      public void clearData()
      Erases all the data gathered by the HeapMonitor.
      Since:
      19.0

    • hasData

      public boolean hasData()
      Returns true if the HeapMonitor has collected any data, else false.
      Since:
      19.0

    • close

      public void close()
      Closes the HeapMonitor for further use, deleting all the gathered data.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Since:
      19.0