Microsoft SDK for Java

IJavaHeapMonitor2::
WalkHeap

This method of the IJavaHeapMonitor2 interface initiates a heap dump. This method may only be called from the profiler's BeginContainer callback when C_END is received. It will return E_FAIL if called from a different thread or at any other time. ObjectIDs from the previous heap dump will remain valid across the new heap dump. Unlike passive heap callbacks, C_BEGIN and C_END notifications will not be received. (They convey no useful information because the caller is initiating the dump.)

Syntax

HRESULT WalkHeap([in]IHeapInfoCallback *pihicb, [in]DWORD flags);

Parameters

[in] *pihicb A pointer to the IHeapInfoCallback interface implemented by the profiler.
[in] flags Mask of JVM_WALKHEAP_FLAGS.

Remarks

WalkHeap enables an event monitor to request multiple traversals of the heap within a single garbage collection. It does not replace GetHeapInfo. A profiler must already have an IHeapInfoCallback interface registered in order to use this API.

Although the behavior of WalkHeap's callback is identical to the normal passive callback mechanism, WalkHeap differs from the passive mechanism in the following ways:

  1. This API must be called from within the C_END BeginContainer method of the registered callback, on the thread that received the callback. The API will return E_FAIL under any other conditions.

  2. C_BEGIN and C_END notifications will not be received. (Normal passive heap dumps always receive C_BEGIN and C_END notifications.)

  3. The heap dump is complete when the WalkHeap API call returns. Execution will remain suspended until the calling BeginContainer method returns. (Normal passive heap dumps resume execution when the BeginContainer callback for the C_END container returns.)

  4. ObjectIDs will remain valid across multiple WalkHeap calls within the same garbage collection. (For normal passive heap dumps, all ObjectIDs are invalid when the BeginContainer callback for the C_END container returns.)

  5. Like passive heap dumping, root containers, references from root containers, and objects within the C_HEAP container may or may not be reported in the same order across multiple heap dumps. This also applies to multiple heap dumps within the same garbage collection. References from within objects will always be reported in the same order.

  6. WalkHeap does not cause garbage collection to occur, but should be considered an expensive operation, equivalent in magnitude to performing another garbage collection.

JVM_WALKHEAP_FLAGS

Constant Value Description
JVM_WALKHEAP_NO_ROOTS 1 Bypasses traversal from roots. No BeginContainer or RootReferences calls will be received. (Normal passive heap dumps always traverse roots.)

© 1999 Microsoft Corporation. All rights reserved. Terms of use.