HeapGraph.kt

TLDR

The file HeapGraph.kt contains the definition of the HeapGraph interface, which provides a way to navigate through the heap graph of objects in the shark package.

Methods

There are several methods defined in the HeapGraph interface:

findObjectById(objectId: Long): HeapObject

Returns the HeapObject corresponding to the provided objectId, or throws an IllegalArgumentException if the object cannot be found.

findObjectByIndex(objectIndex: Int): HeapObject

Returns the HeapObject corresponding to the provided objectIndex, or throws an IllegalArgumentException if the index is out of range.

findObjectByIdOrNull(objectId: Long): HeapObject?

Returns the HeapObject corresponding to the provided objectId, or null if the object cannot be found.

findClassByName(className: String): HeapClass?

Returns the HeapClass corresponding to the provided className, or null if the class cannot be found.

objectExists(objectId: Long): Boolean

Returns true if the provided objectId exists in the heap dump, false otherwise.

findHeapDumpIndex(objectId: Long): Int

Returns the 1-based index in the heap dump of the object corresponding to the provided objectId, or throws an IllegalArgumentException if the object cannot be found.

findObjectByHeapDumpIndex(heapDumpIndex: Int): HeapObject

Returns the HeapObject corresponding to the provided heapDumpIndex, or throws an IllegalArgumentException if the index is out of range.

END

package shark

import shark.HeapObject.HeapClass
import shark.HeapObject.HeapInstance
import shark.HeapObject.HeapObjectArray
import shark.HeapObject.HeapPrimitiveArray

/**
 * Enables navigation through the heap graph of objects.
 */
interface HeapGraph {
  val identifierByteSize: Int

  /**
   * In memory store that can be used to store objects this [HeapGraph] instance.
   */
  val context: GraphContext

  val objectCount: Int

  val classCount: Int

  val instanceCount: Int

  val objectArrayCount: Int

  val primitiveArrayCount: Int

  /**
   * All GC roots which type matches types known to this heap graph and which point to non null
   * references. You can retrieve the object that a GC Root points to by calling [findObjectById]
   * with [GcRoot.id], however you need to first check that [objectExists] returns true because
   * GC roots can point to objects that don't exist in the heap dump.
   */
  val gcRoots: List<GcRoot>

  /**
   * Sequence of all objects in the heap dump.
   *
   * This sequence does not trigger any IO reads.
   */
  val objects: Sequence<HeapObject>

  /**
   * Sequence of all classes in the heap dump.
   *
   * This sequence does not trigger any IO reads.
   */
  val classes: Sequence<HeapClass>

  /**
   * Sequence of all instances in the heap dump.
   *
   * This sequence does not trigger any IO reads.
   */
  val instances: Sequence<HeapInstance>

  /**
   * Sequence of all object arrays in the heap dump.
   *
   * This sequence does not trigger any IO reads.
   */
  val objectArrays: Sequence<HeapObjectArray>

  /**
   * Sequence of all primitive arrays in the heap dump.
   *
   * This sequence does not trigger any IO reads.
   */
  val primitiveArrays: Sequence<HeapPrimitiveArray>

  /**
   * Returns the [HeapObject] corresponding to the provided [objectId], and throws
   * [IllegalArgumentException] otherwise.
   */
  @Throws(IllegalArgumentException::class)
  fun findObjectById(objectId: Long): HeapObject

  /**
   * Returns the [HeapObject] corresponding to the provided [objectIndex], and throws
   * [IllegalArgumentException] if [objectIndex] is less than 0 or more than [objectCount] - 1.
   */
  @Throws(IllegalArgumentException::class)
  fun findObjectByIndex(objectIndex: Int): HeapObject

  /**
   * Returns the [HeapObject] corresponding to the provided [objectId] or null if it cannot be
   * found.
   */
  fun findObjectByIdOrNull(objectId: Long): HeapObject?

  /**
   * Returns the [HeapClass] corresponding to the provided [className], or null if the
   * class cannot be found.
   */
  fun findClassByName(className: String): HeapClass?

  /**
   * Returns true if the provided [objectId] exists in the heap dump.
   */
  fun objectExists(objectId: Long): Boolean

  /**
   * Returns the 1-based index in the heap dump of the object corresponding to the provided
   * [objectId], and throws [IllegalArgumentException] otherwise.
   *
   * This is the object index that YourKit provides in its Java profiler.
   */
  fun findHeapDumpIndex(objectId: Long): Int

  /**
   * Returns the [HeapObject] corresponding to the provided [heapDumpIndex], and throws
   * [IllegalArgumentException] if [heapDumpIndex] is less than 1 or more than [objectCount].
   *
   * This is the object index that YourKit provides in its Java profiler.
   */
  fun findObjectByHeapDumpIndex(heapDumpIndex: Int): HeapObject
}