Apache Harmony is retired at the Apache Software Foundation since Nov 16, 2011.

The information on these pages may be out of date, or may refer to resources that have moved or have been made read-only.
For more information please refer to the Apache Attic

JVMTI Pop Frame

  1. About This Document
  2. Introduction
  3. How to Pop a Frame
  4. Implementation Specifics
  5. Related Information

About This Document

Here is a description of how popping a frame is currently implemented in the DRLVM tool interface (JVMTI). For a definition of the pop frame functionality, consult the JVMTI specification [1]. For generic information on JVMTI in the DRL virtual machine and for definition of related terms, see the developer's guide.


Popping a stack frame becomes necessary when execution is in a native function and a managed-to-native frame (M2nFrame) is on the stack. This means that the JVMTI component pops the M2nFrame and the Java frame above it. A frame is popped each time the JVMTI function PopFrame() is called. The current pop-frame implementation is based on the exception handling mechanism for transferring execution control. This way, VM pops frames on the current thread only. To pop frames on other threads, VM uses the M2nFrame flag system and callbacks.

How to Pop a Frame

To pop a frame on the current thread, refer to the following core functions:

Function Name Role
jvmti_jit_prepare_pop_frame Finds register context for the previous frame using the stack iterator.
jvmti_jit_complete_pop_frame Transfers control to the saved register context for the popped frame.
jvmti_ji_do_pop_frame Transfers control to the previous frame. This function is a simple and fast combination of sequential calls of jvmti_jit_prepare_pop_frame and jvmti_jit_complete_pop_frame.

The state of a frame with regard to popping is indicated in the frame_type field. This field can have the following values:

Flag Name Meaning
FRAME_UNPOPABLE The frame cannot be popped.
FRAME_POPABLE The frame can be popped but is not.
FRAME_POP_NOW The frame is popped and the state of VM can be unpredictable and unexpected. JVMTI cannot work in this state and waits until the popped frame is resumed and the frame state is changed.
FRAME_POP_DONE = FRAME_POPABLE |FRAME_POP_NOW The frame is popped now but VM state is OK and JVMTI can work without thread resume.

In the current implementation, popping a frame goes in the following way:

  1. VM suspends the popped thread in one of these functions: thread_suspend_disable() or in hythread_safe_point().
  2. The JVMTI Agent calls PopFrame() and does the following:
    • Checks that the flag for the topmost M2nFrame is set to FRAME_POPABLE, which means that the frame can be popped.
    • Changes the flag to FRAME_POP_NOW.
    • Sets the safe point for the callback function. The suspended thread executes the callback while staying in the function where the thread is suspended.
  3. The callback function pops the frame in one of the following ways depending on the function and on area of the stack:
    • For hythread_safe_point():
      • VM finds the register context for the previous frame and saves it in the current M2nFrame. The frame type flag changed to FRAME_POP_DONE.
      • VM exits the safe point and checks the frame status. If the frame is popped, VM transfers control to the saved register context. Otherwise, VM exits normally.
    • For the suspend_disable() function in an unwindable area of the stack:
      • The callback explicitly calls hythread_safe_point() to stop the current thread in the safe point and wait until the thread is resumed by another thread.
      • When the thread is resumed, the callback pops the frame for the current thread and transfers control to the previous frame.
    • For the suspend_disable() function in a non-unwindable area of the stack:
      • VM raises a special exception object and waits for the end of the area.
      • After exiting the area, VM checks whether the exception is set and pops the frame for the current thread and transfers control to the previous frame.

Implementation Specifics

Related Information

[1] JVM Tool Interface Specification, http://java.sun.com/j2se/1.5.0/docs/guide/jvmti/jvmti.html

Back to top