Details

    • Author:
      Mandy Chung
    • JEP Type:
      Feature
    • Exposure:
      Open
    • Scope:
      SE
    • Discussion:
      core dash libs dash dev at openjdk dot java dot net
    • Effort:
      M
    • Duration:
      M
    • Alert Status:
       Green
    • JEP Number:
      259

      Description

      Summary

      Define an efficient standard API for stack walking that allows easy filtering of, and lazy access to, the information in stack traces.

      Non-Goal

      • It is not a goal to convert all existing stack walking code in the JDK to use this new API.

      Motivation

      There is no standard API to traverse selected frames on the execution stack efficiently and access the Class instance of each frame.

      There are existing APIs that provide access to a thread's stack:

      • Throwable::getStackTrace and Thread::getStackTrace return an array of StackTraceElement objects, which contain the class name and method name of each stack-trace element.

      • SecurityManager::getClassContext is a protected method, which allows a SecurityManager subclass to access the class context.

      These APIs require the VM to eagerly capture a snapshot of the entire stack, and they return information representing the entire stack. There is no way to avoid the cost of examining all the frames if the caller is only interested in the top few frames on the stack. Both the Throwable::getStackTrace and Thread::getStackTrace methods return an array of StackTraceElement objects, which contain class names and method names but not the actual Class instances. For applications interested in the entire stack, the specification allows the VM implementation to omit some frames in the stack for performance. In other words, Thread::getStackTrace may return a partial stack trace.

      These APIs do not satisfy the use cases that currently depend upon the JDK-internal sun.reflect.Reflection::getCallerClass method, or else their performance overhead is intolerable. These use cases include:

      • Walk the stack until the immediate caller's class is found. Every JDK caller-sensitive API looks up its immediate caller's class in order to determine the behavior of the API. For example, the Class::forName and ResourceBundle::getBundle methods use the immediate caller's class loader to load a class and a resource bundle respectively. Reflective APIs such as Class::getMethod use the immediate caller's class loader to determine the security checks to be performed.

      • Walk the stack, filtering out the stack frames of specific implementation classes to find the first non-filtered frame. The java.util.logging API, Log4j, and the Groovy runtime filter intermediate stack frames (typically implementation-specific and reflection frames) to find the caller's class.

      • Walk the stack to find all protection domains, until the first privileged frame is reached. This is required in order to do permission checks.

      • Walk the entire stack, possibly with a depth limit. This is required to generate the stack trace of any Throwable object, and to implement the Thread::dumpStack method.

      Description

      This JEP will define a stack-walking API that allows laziness and frame filtering, supports short walks that stop at a frame matching given criteria, and also supports long walks that traverse the entire stack.

      The JVM will be enhanced to provide a flexible mechanism to traverse and materialize the required stack-frame information and allow efficient lazy access to additional stack frames when required. Native JVM transitions will be minimized. The implementation will need to have a stable view of a thread's stack: Returning a stream holding a stack pointer for further manipulation in an uncontrolled manner will not work since, as soon as the stream factory returns, the JVM will be free to reorganize the control stack (via deoptimization, for example). This will influence the API's definition.

      The API will specify its behavior when running with a security manager, so that access to the Class objects in stack frames do not compromise security.

      The proposal is to define a capability-based StackWalker API to traverse the stack. The security permission check will be performed on each StackWalker object when it is constructed rather than each time it is used. It will define the following methods:

      public <T> T walk(Function<Stream<StackFrame>, T> function);
      public Class<?> getCallerClass();

      The walk method opens a sequential stream of StackFrame for the current thread and then applies the function with the StackFrame stream. The spliterator of the stream performs the stack frame traversal in an ordered manner. The Stream<StackFrame> object can only be traversed once and will be closed when the walk method returns. The stream becomes invalid to use once it is closed. For example, to find the first caller filtering a known list of implementation class:

      Optional<Class<?>> frame = new StackWalker().walk((s) ->
      {
          s.filter(f -> interestingClasses.contains(f.getDeclaringClass()))
           .map(StackFrame::getDeclaringClass)
           .findFirst();
      }); 

      To snapshot the stack trace of the current thread,

      List<StackFrame> stack =
           new StackWalker().walk((s) -> s.collect(Collectors.toList())); 

      The getCallerClass() method is for convenience to find the caller's frame and is the replacement for sun.reflect.Reflection.getCallerClass. An equivalent way to get the caller class using the walk method is:

      walk((s) -> s.map(StackFrame::declaringClass).skip(2).findFirst());

      Alternatives

      An alternative API choice would be for the walk method to return Stream<StackFrame>. Such an alternative will not work as the returned stream object may be used in an uncontrolled manner for further manipulation. When a stream of stack frames is created, as soon as the stream factory returns, the JVM is free to reorganize the control stack (via deoptimization, for example) and there is no robust way to detect if the stack has been mutated.

      Instead, similar to AccessController::doPrivileged, at least one native method must be created which will establish its own stack frame and then provide controlled access to the JVM's stack walking logic, for older frames. When this native method returns, that capability must be deactivated, or else made inaccessible in some other way. In this way, we can do efficient lazy access to stack frames, on a stable view of the thread's own control stack.

        Issue Links

          Activity

          mchung Mandy Chung created issue -
          mchung Mandy Chung made changes -
          Field Original Value New Value
          Description Goal
          ----

          Define a standard API for stack walking that will be efficient
          and allows easy filtering and lazy access to stack traces.

          Motivation
          ----------

          There is no standard API to obtain information about the caller's class
          and traverse the execution stack in a performant way. Existing libraries
          and frameworks such as Log4j and Groovy have to resort to using the
          JDK internal API `sun.reflect.Reflection.getCallerClass(int depth)`
          or creating an exception and parsing the stack trace.

          This JEP proposes to define a standard API for stack walking that will
          be efficient and also enable the implementation up
          level the stack walk machinery from the VM to Java and replaces
          the current mechanism of `Throwable.fillInStackTrace.

          Description
          -----------

          There is no standard API to traverse certain frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are APIs that allow to access the stack trace information:
            - `Throwable.getStackTrace()` and `Thread.getStackTrace()` that returns
               an array of `StackTraceElement` which contains the classname
               and method name of a stack trace.
            - `SecurityManager.getClassContext()` which is a protected method
               such that only `SecurityManager` subclass can access the class
               context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack trace and returns the information representing the entire stack.
          There is no other way to avoid the cost to examine all frames if
          the caller is only interested in the top few frames on the stack.
          Both `Throwable.getStackTrace()` and `Thread.getStackTrace()` methods
          return an array of `StackTraceElement` that contains the classname and
          method name of a stack frame but not the `Class` instance.

          In fact, for applications interested in the entire stack, the specification
          allows VM implementation to omit some frames in the stack for performance.
          In other words, `Thread.getStackTrace()` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend on
          the `getCallerClass(int depth)` method or its performance overhead
          is intolerable. The use cases include:

          The following lists several use cases to do stack walking:

            - Walk the stack until it finds the immediate caller's class

              JDK caller-sensitive APIs look up its immediate caller's class
              which will be used to determine the behavior of the API. For example
              `Class.forName(String classname)` and
              `ResourceBundle.getBundle(String rbname)` methods use the immediate
              caller's class loader to load a class and a resource bundle respectively.
              `Class.getMethod` etc will use the immediate caller's class loader
              to determine the security checks to be performed.

            - Walk the stack, filter the stack frames of specific implementation classes
              and find the first non-filtered frame

              `java.util.logging`, Log4j and Groovy runtime filter the intermediary
              stack frames (typically implementation-specific and reflection frames)
              and find the caller's class to be used by the runtime of such library
              or framework.

            - Walk the stack and finds all protection domains until it reachs
              the first privileged frame

              AccessControlContext represents the context for the current execution
              stack and used for permission check.

            - Walk the entire stack and possibly with a depth limit

              `Thread.dumpStack` and the stack trace of a `Throwbale`
              traverse the entire stack trace


          This JEP will define a stack walk API that allows laziness, frame filtering,
          supports short reaches to stop at a frame matching some criteria
          as well as long reaches to traverse the entire stack trace. This would
          need the JVM to provide a flexible mechanism to traverse and materialize
          the specific stack frame information to be used and allow efficient
          lazy access to additional stack frames when required.
          Native JVM transitions should be minimzed.

          The API will define how it works when running with a security manager
          that allows access to a `Class` instance
          of any frame ensuring that the security is not compromised.
          Below lists some possible API sketch to give an idea:

          The new stream API is a very good match for this problem:
             Stream<StackFrameInfo> stackStream()

          and we would need to take into acccount that safe and lazy traversal
          of the stack should only happen at the terminal operation.

          Another consideration could be taking a callback to be invoked
          for each frame traversed:
             Thread.walkStack(Consumer<StackFrameInfo> action, int depthLimit)

          A variant of the walkStack method will take a predicate for
          stack frame filtering.

             Thread.getCaller(Function<StackFrameInfo, R> function)
             Thread.findCaller(Predicate<StackFrameInfo> predicate,
                               Function<StackFrameInfo, R> function)

          finds the caller frame with or without filtering.

          Testing
          -------

          Unit tests and JCK tests for the new SE API will need to be developed.
          In addition, the performance of the new API for different use cases
          will be assessed.


          Impact
          ------

            - Performance/scalability: performance measurement shall be performed
              using micro-benchmarks as well as real world usage of `getCallerClass`
              replaced with the new API.

            - TCK: New JCK test cases shall be developed.
          Goal
          ----

          Define a standard API for stack walking that will be efficient
          and allows easy filtering and lazy access to stack traces.

          Motivation
          ----------

          There is no standard API to obtain information about the caller's class
          and traverse the execution stack in a performant way. Existing libraries
          and frameworks such as Log4j and Groovy have to resort to using the
          JDK internal API `sun.reflect.Reflection.getCallerClass(int depth)`
          or creating an exception and parsing the stack trace.

          This JEP proposes to define a standard API for stack walking that will
          be efficient and also enable the implementation up
          level the stack walk machinery from the VM to Java and replaces
          the current mechanism of `Throwable.fillInStackTrace`.

          Description
          -----------

          There is no standard API to traverse certain frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are APIs that allow to access the stack trace information:

             - `Throwable.getStackTrace()` and `Thread.getStackTrace()` that returns
               an array of `StackTraceElement` which contains the classname
               and method name of a stack trace.

             - `SecurityManager.getClassContext()` which is a protected method
               such that only `SecurityManager` subclass can access the class
               context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack trace and returns the information representing the entire stack.
          There is no other way to avoid the cost to examine all frames if
          the caller is only interested in the top few frames on the stack.
          Both `Throwable.getStackTrace()` and `Thread.getStackTrace()` methods
          return an array of `StackTraceElement` that contains the classname and
          method name of a stack frame but not the `Class` instance.

          In fact, for applications interested in the entire stack, the specification
          allows VM implementation to omit some frames in the stack for performance.
          In other words, `Thread.getStackTrace()` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend on
          the `getCallerClass(int depth)` method or its performance overhead
          is intolerable. The use cases include:

          The following lists several use cases to do stack walking:

            - Walk the stack until it finds the immediate caller's class

              JDK caller-sensitive APIs look up its immediate caller's class
              which will be used to determine the behavior of the API. For example
              `Class.forName(String classname)` and
              `ResourceBundle.getBundle(String rbname)` methods use the immediate
              caller's class loader to load a class and a resource bundle respectively.
              `Class.getMethod` etc will use the immediate caller's class loader
              to determine the security checks to be performed.

            - Walk the stack, filter the stack frames of specific implementation classes
              and find the first non-filtered frame

              `java.util.logging`, Log4j and Groovy runtime filter the intermediary
              stack frames (typically implementation-specific and reflection frames)
              and find the caller's class to be used by the runtime of such library
              or framework.

            - Walk the stack and finds all protection domains until it reaches
              the first privileged frame

              `AccessControlContext` represents the context for the current execution
              stack and used for permission check.

            - Walk the entire stack and possibly with a depth limit

              `Thread.dumpStack` and the stack trace of a `Throwable`
              traverse the entire stack trace


          This JEP will define a stack walk API that allows laziness, frame filtering,
          supports short reaches to stop at a frame matching some criteria
          as well as long reaches to traverse the entire stack trace. This would
          need the JVM to provide a flexible mechanism to traverse and materialize
          the specific stack frame information to be used and allow efficient
          lazy access to additional stack frames when required.
          Native JVM transitions should be minimzed.

          The API will define how it works when running with a security manager
          that allows access to a `Class` instance
          of any frame ensuring that the security is not compromised.
          Some possible API sketch to give an idea:

             - The new stream API is a very good match for this problem: `Stream<StackFrameInfo> stackStream()` and we would need to take into acccount that safe and lazy traversal of the stack should only happen at the terminal operation.

             - Another consideration could be taking a callback to be invoked for each frame traversed: `Thread.walkStack(Consumer<StackFrameInfo> action, int depthLimit)`

             - A variant of the walkStack method will take a predicate for stack frame filtering e.g. `Thread.getCaller(Function<StackFrameInfo, R> function)` or `Thread.findCaller(Predicate<StackFrameInfo> predicate, Function<StackFrameInfo, R> function)` to find the caller frame with or without filtering.

          Testing
          -------

          Unit tests and JCK tests for the new SE API will need to be developed.
          In addition, the performance of the new API for different use cases
          will be assessed.


          Impact
          ------

             - Performance/scalability: performance measurement shall be performed
              using micro-benchmarks as well as real world usage of `getCallerClass`
              replaced with the new API.

             - TCK: New JCK test cases shall be developed.
          mchung Mandy Chung made changes -
          Security Confidential [ 10000 ]
          mchung Mandy Chung made changes -
          Status Draft [ 10001 ] Submitted [ 10002 ]
          mchung Mandy Chung made changes -
          Security Confidential [ 10000 ]
          briangoetz Brian Goetz made changes -
          Reviewed By briangoetz
          jehung Jeannette Hung made changes -
          Labels team-corelibs
          squierts Tony Squier made changes -
          Reviewed By [NEW] [briangoetz]
          jehung Jeannette Hung made changes -
          Fix Version/s 9 [ 14949 ]
          squierts Tony Squier made changes -
          Owner mchung
          jehung Jeannette Hung made changes -
          Labels team-corelibs a360_1190575 team-corelibs
          squierts Tony Squier made changes -
          shnarasi Shobana Narasimhan made changes -
          Labels a360_1190575 team-corelibs a360_1190575_candidate team-corelibs
          jehung Jeannette Hung made changes -
          Link This issue is blocked by JDK-8054692 [ JDK-8054692 ]
          jehung Jeannette Hung made changes -
          Link This issue is blocked by JDK-8054693 [ JDK-8054693 ]
          jehung Jeannette Hung made changes -
          Link This issue is blocked by JDK-8054697 [ JDK-8054697 ]
          jehung Jeannette Hung made changes -
          Link This issue is blocked by JDK-8054698 [ JDK-8054698 ]
          jehung Jeannette Hung made changes -
          Link This issue is blocked by JDK-8054706 [ JDK-8054706 ]
          jehung Jeannette Hung made changes -
          Link This issue is blocked by JDK-8054707 [ JDK-8054707 ]
          jehung Jeannette Hung made changes -
          Link This issue is blocked by JDK-8054708 [ JDK-8054708 ]
          sfriberg Staffan Friberg (Inactive) made changes -
          Link This issue is blocked by JDK-8058167 [ JDK-8058167 ]
          jehung Jeannette Hung made changes -
          Assignee Mandy Chung [ mchung ] Mark Reinhold [ mr ]
          jehung Jeannette Hung made changes -
          Labels a360_1190575_candidate team-corelibs a360_1190575 team-corelibs
          skonchad Sandeep Konchady made changes -
          Link This issue is blocked by JDK-8061568 [ JDK-8061568 ]
          mchung Mandy Chung made changes -
          Security Confidential [ 10000 ]
          Effort S [ 19110 ] M [ 19111 ]
          mchung Mandy Chung made changes -
          Link This issue relates to JDK-8020968 [ JDK-8020968 ]
          mchung Mandy Chung made changes -
          Fix Version/s 10 [ 16302 ]
          Fix Version/s 9 [ 14949 ]
          mchung Mandy Chung made changes -
          Description Goal
          ----

          Define a standard API for stack walking that will be efficient
          and allows easy filtering and lazy access to stack traces.

          Motivation
          ----------

          There is no standard API to obtain information about the caller's class
          and traverse the execution stack in a performant way. Existing libraries
          and frameworks such as Log4j and Groovy have to resort to using the
          JDK internal API `sun.reflect.Reflection.getCallerClass(int depth)`
          or creating an exception and parsing the stack trace.

          This JEP proposes to define a standard API for stack walking that will
          be efficient and also enable the implementation up
          level the stack walk machinery from the VM to Java and replaces
          the current mechanism of `Throwable.fillInStackTrace`.

          Description
          -----------

          There is no standard API to traverse certain frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are APIs that allow to access the stack trace information:

             - `Throwable.getStackTrace()` and `Thread.getStackTrace()` that returns
               an array of `StackTraceElement` which contains the classname
               and method name of a stack trace.

             - `SecurityManager.getClassContext()` which is a protected method
               such that only `SecurityManager` subclass can access the class
               context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack trace and returns the information representing the entire stack.
          There is no other way to avoid the cost to examine all frames if
          the caller is only interested in the top few frames on the stack.
          Both `Throwable.getStackTrace()` and `Thread.getStackTrace()` methods
          return an array of `StackTraceElement` that contains the classname and
          method name of a stack frame but not the `Class` instance.

          In fact, for applications interested in the entire stack, the specification
          allows VM implementation to omit some frames in the stack for performance.
          In other words, `Thread.getStackTrace()` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend on
          the `getCallerClass(int depth)` method or its performance overhead
          is intolerable. The use cases include:

          The following lists several use cases to do stack walking:

            - Walk the stack until it finds the immediate caller's class

              JDK caller-sensitive APIs look up its immediate caller's class
              which will be used to determine the behavior of the API. For example
              `Class.forName(String classname)` and
              `ResourceBundle.getBundle(String rbname)` methods use the immediate
              caller's class loader to load a class and a resource bundle respectively.
              `Class.getMethod` etc will use the immediate caller's class loader
              to determine the security checks to be performed.

            - Walk the stack, filter the stack frames of specific implementation classes
              and find the first non-filtered frame

              `java.util.logging`, Log4j and Groovy runtime filter the intermediary
              stack frames (typically implementation-specific and reflection frames)
              and find the caller's class to be used by the runtime of such library
              or framework.

            - Walk the stack and finds all protection domains until it reaches
              the first privileged frame

              `AccessControlContext` represents the context for the current execution
              stack and used for permission check.

            - Walk the entire stack and possibly with a depth limit

              `Thread.dumpStack` and the stack trace of a `Throwable`
              traverse the entire stack trace


          This JEP will define a stack walk API that allows laziness, frame filtering,
          supports short reaches to stop at a frame matching some criteria
          as well as long reaches to traverse the entire stack trace. This would
          need the JVM to provide a flexible mechanism to traverse and materialize
          the specific stack frame information to be used and allow efficient
          lazy access to additional stack frames when required.
          Native JVM transitions should be minimzed.

          The API will define how it works when running with a security manager
          that allows access to a `Class` instance
          of any frame ensuring that the security is not compromised.
          Some possible API sketch to give an idea:

             - The new stream API is a very good match for this problem: `Stream<StackFrameInfo> stackStream()` and we would need to take into acccount that safe and lazy traversal of the stack should only happen at the terminal operation.

             - Another consideration could be taking a callback to be invoked for each frame traversed: `Thread.walkStack(Consumer<StackFrameInfo> action, int depthLimit)`

             - A variant of the walkStack method will take a predicate for stack frame filtering e.g. `Thread.getCaller(Function<StackFrameInfo, R> function)` or `Thread.findCaller(Predicate<StackFrameInfo> predicate, Function<StackFrameInfo, R> function)` to find the caller frame with or without filtering.

          Testing
          -------

          Unit tests and JCK tests for the new SE API will need to be developed.
          In addition, the performance of the new API for different use cases
          will be assessed.


          Impact
          ------

             - Performance/scalability: performance measurement shall be performed
              using micro-benchmarks as well as real world usage of `getCallerClass`
              replaced with the new API.

             - TCK: New JCK test cases shall be developed.
          Goal
          ----

          Define a standard API for stack walking that will be efficient
          and allows easy filtering and lazy access to stack traces.

          Motivation
          ----------

          There is no standard API to obtain information about the caller's class
          and traverse the execution stack in a performant way. Existing libraries
          and frameworks such as Log4j and Groovy have to resort to using the
          JDK internal API `sun.reflect.Reflection.getCallerClass(int depth)`
          or creating an exception and parsing the stack trace.

          This JEP proposes to define a standard API for stack walking that will
          be efficient and also enable the implementation up
          level the stack walk machinery from the VM to Java and replaces
          the current mechanism of `Throwable.fillInStackTrace`.

          Description
          -----------

          There is no standard API to traverse certain frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are APIs that allow to access the stack trace information:

             - `Throwable.getStackTrace()` and `Thread.getStackTrace()` that returns
               an array of `StackTraceElement` which contains the classname
               and method name of a stack trace.

             - `SecurityManager.getClassContext()` which is a protected method
               such that only `SecurityManager` subclass can access the class
               context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack trace and returns the information representing the entire stack.
          There is no other way to avoid the cost to examine all frames if
          the caller is only interested in the top few frames on the stack.
          Both `Throwable.getStackTrace()` and `Thread.getStackTrace()` methods
          return an array of `StackTraceElement` that contains the classname and
          method name of a stack frame but not the `Class` instance.

          In fact, for applications interested in the entire stack, the specification
          allows VM implementation to omit some frames in the stack for performance.
          In other words, `Thread.getStackTrace()` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend on
          the `getCallerClass(int depth)` method or its performance overhead
          is intolerable. The use cases include:

          The following lists several use cases to do stack walking:

            - Walk the stack until it finds the immediate caller's class

              JDK caller-sensitive APIs look up its immediate caller's class
              which will be used to determine the behavior of the API. For example
              `Class.forName(String classname)` and
              `ResourceBundle.getBundle(String rbname)` methods use the immediate
              caller's class loader to load a class and a resource bundle respectively.
              `Class.getMethod` etc will use the immediate caller's class loader
              to determine the security checks to be performed.

            - Walk the stack, filter the stack frames of specific implementation classes
              and find the first non-filtered frame

              `java.util.logging`, Log4j and Groovy runtime filter the intermediary
              stack frames (typically implementation-specific and reflection frames)
              and find the caller's class to be used by the runtime of such library
              or framework.

            - Walk the stack and finds all protection domains until it reaches
              the first privileged frame

              `AccessControlContext` represents the context for the current execution
              stack and used for permission check.

            - Walk the entire stack and possibly with a depth limit

              `Thread.dumpStack` and the stack trace of a `Throwable`
              traverse the entire stack trace


          This JEP will define a stack walk API that allows laziness, frame filtering,
          supports short reaches to stop at a frame matching some criteria
          as well as long reaches to traverse the entire stack trace. This would
          need the JVM to provide a flexible mechanism to traverse and materialize
          the specific stack frame information to be used and allow efficient
          lazy access to additional stack frames when required.
          Native JVM transitions should be minimized. On the other hand,
          the implementation will need to have a stable view on the thread's stack and
          returning a stream holding a stack pointer for further manipulation in an uncontrolled
          manner will not work because as soon as the stream factory returns, the JVM is free to
          reorganize the control stack (via deoptimization, for example) that will influence how
          the API is defined.

          The API will define how it works when running with a security manager
          that allows access to a `Class` instance of any frame ensuring that the security
          is not compromised.

          ### API

          One API proposal is to define a capability-based `StackWalker` API that the security permission check will be performed on the `StackWalker` object per the requested capabilities at construction time.


              public <T> T walk(Function<Stream<StackFrame>, T> function)

              public Class<?> getCallerClass()

              public Optional<StackFrame> findCaller(Predicate<StackFrame> predicate)

            - The `walk` method taking a callback ti traverse a stream of StackFrame will allow the stack walking to establish its own stack frame and then provide controlled access. Another alternative to have the `walk` method is to return `Stream<StackFrame>` that needs further investigation and prototype to determine the feasibility of safely and lazy traversal of the stack in a controlled manner.

            - The `getCallerClass()` method and `findCaller(Predicate<StackFrameInfo> predicate)` are convenient methods to find the caller frame with or without filtering.

          Testing
          -------

             - Unit tests and JCK tests for the new SE API will need to be developed.

             - Performance/scalability: performance measurement shall be performed
              using micro-benchmarks as well as real world usage of `getCallerClass`
              replaced with the new API.

          mchung Mandy Chung made changes -
          Description Goal
          ----

          Define a standard API for stack walking that will be efficient
          and allows easy filtering and lazy access to stack traces.

          Motivation
          ----------

          There is no standard API to obtain information about the caller's class
          and traverse the execution stack in a performant way. Existing libraries
          and frameworks such as Log4j and Groovy have to resort to using the
          JDK internal API `sun.reflect.Reflection.getCallerClass(int depth)`
          or creating an exception and parsing the stack trace.

          This JEP proposes to define a standard API for stack walking that will
          be efficient and also enable the implementation up
          level the stack walk machinery from the VM to Java and replaces
          the current mechanism of `Throwable.fillInStackTrace`.

          Description
          -----------

          There is no standard API to traverse certain frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are APIs that allow to access the stack trace information:

             - `Throwable.getStackTrace()` and `Thread.getStackTrace()` that returns
               an array of `StackTraceElement` which contains the classname
               and method name of a stack trace.

             - `SecurityManager.getClassContext()` which is a protected method
               such that only `SecurityManager` subclass can access the class
               context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack trace and returns the information representing the entire stack.
          There is no other way to avoid the cost to examine all frames if
          the caller is only interested in the top few frames on the stack.
          Both `Throwable.getStackTrace()` and `Thread.getStackTrace()` methods
          return an array of `StackTraceElement` that contains the classname and
          method name of a stack frame but not the `Class` instance.

          In fact, for applications interested in the entire stack, the specification
          allows VM implementation to omit some frames in the stack for performance.
          In other words, `Thread.getStackTrace()` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend on
          the `getCallerClass(int depth)` method or its performance overhead
          is intolerable. The use cases include:

          The following lists several use cases to do stack walking:

            - Walk the stack until it finds the immediate caller's class

              JDK caller-sensitive APIs look up its immediate caller's class
              which will be used to determine the behavior of the API. For example
              `Class.forName(String classname)` and
              `ResourceBundle.getBundle(String rbname)` methods use the immediate
              caller's class loader to load a class and a resource bundle respectively.
              `Class.getMethod` etc will use the immediate caller's class loader
              to determine the security checks to be performed.

            - Walk the stack, filter the stack frames of specific implementation classes
              and find the first non-filtered frame

              `java.util.logging`, Log4j and Groovy runtime filter the intermediary
              stack frames (typically implementation-specific and reflection frames)
              and find the caller's class to be used by the runtime of such library
              or framework.

            - Walk the stack and finds all protection domains until it reaches
              the first privileged frame

              `AccessControlContext` represents the context for the current execution
              stack and used for permission check.

            - Walk the entire stack and possibly with a depth limit

              `Thread.dumpStack` and the stack trace of a `Throwable`
              traverse the entire stack trace


          This JEP will define a stack walk API that allows laziness, frame filtering,
          supports short reaches to stop at a frame matching some criteria
          as well as long reaches to traverse the entire stack trace. This would
          need the JVM to provide a flexible mechanism to traverse and materialize
          the specific stack frame information to be used and allow efficient
          lazy access to additional stack frames when required.
          Native JVM transitions should be minimized. On the other hand,
          the implementation will need to have a stable view on the thread's stack and
          returning a stream holding a stack pointer for further manipulation in an uncontrolled
          manner will not work because as soon as the stream factory returns, the JVM is free to
          reorganize the control stack (via deoptimization, for example) that will influence how
          the API is defined.

          The API will define how it works when running with a security manager
          that allows access to a `Class` instance of any frame ensuring that the security
          is not compromised.

          ### API

          One API proposal is to define a capability-based `StackWalker` API that the security permission check will be performed on the `StackWalker` object per the requested capabilities at construction time.


              public <T> T walk(Function<Stream<StackFrame>, T> function)

              public Class<?> getCallerClass()

              public Optional<StackFrame> findCaller(Predicate<StackFrame> predicate)

            - The `walk` method taking a callback ti traverse a stream of StackFrame will allow the stack walking to establish its own stack frame and then provide controlled access. Another alternative to have the `walk` method is to return `Stream<StackFrame>` that needs further investigation and prototype to determine the feasibility of safely and lazy traversal of the stack in a controlled manner.

            - The `getCallerClass()` method and `findCaller(Predicate<StackFrameInfo> predicate)` are convenient methods to find the caller frame with or without filtering.

          Testing
          -------

             - Unit tests and JCK tests for the new SE API will need to be developed.

             - Performance/scalability: performance measurement shall be performed
              using micro-benchmarks as well as real world usage of `getCallerClass`
              replaced with the new API.

          Goal
          ----

          Define a standard API for stack walking that will be efficient
          and allows easy filtering and lazy access to stack traces.

          Motivation
          ----------

          There is no standard API to obtain information about the caller's class
          and traverse the execution stack in a performant way. Existing libraries
          and frameworks such as Log4j and Groovy have to resort to using the
          JDK internal API `sun.reflect.Reflection.getCallerClass(int depth)`
          or creating an exception and parsing the stack trace.

          This JEP proposes to define a standard API for stack walking that will
          be efficient and also enable the implementation up
          level the stack walk machinery from the VM to Java and replaces
          the current mechanism of `Throwable.fillInStackTrace`.

          Description
          -----------

          There is no standard API to traverse certain frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are APIs that allow to access the stack trace information:

             - `Throwable.getStackTrace()` and `Thread.getStackTrace()` that returns
               an array of `StackTraceElement` which contains the classname
               and method name of a stack trace.

             - `SecurityManager.getClassContext()` which is a protected method
               such that only `SecurityManager` subclass can access the class
               context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack trace and returns the information representing the entire stack.
          There is no other way to avoid the cost to examine all frames if
          the caller is only interested in the top few frames on the stack.
          Both `Throwable.getStackTrace()` and `Thread.getStackTrace()` methods
          return an array of `StackTraceElement` that contains the classname and
          method name of a stack frame but not the `Class` instance.

          In fact, for applications interested in the entire stack, the specification
          allows VM implementation to omit some frames in the stack for performance.
          In other words, `Thread.getStackTrace()` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend on
          the `getCallerClass(int depth)` method or its performance overhead
          is intolerable. The use cases include:

          The following lists several use cases to do stack walking:

            - Walk the stack until it finds the immediate caller's class

              JDK caller-sensitive APIs look up its immediate caller's class
              which will be used to determine the behavior of the API. For example
              `Class.forName(String classname)` and
              `ResourceBundle.getBundle(String rbname)` methods use the immediate
              caller's class loader to load a class and a resource bundle respectively.
              `Class.getMethod` etc will use the immediate caller's class loader
              to determine the security checks to be performed.

            - Walk the stack, filter the stack frames of specific implementation classes
              and find the first non-filtered frame

              `java.util.logging`, Log4j and Groovy runtime filter the intermediary
              stack frames (typically implementation-specific and reflection frames)
              and find the caller's class to be used by the runtime of such library
              or framework.

            - Walk the stack and finds all protection domains until it reaches
              the first privileged frame

              `AccessControlContext` represents the context for the current execution
              stack and used for permission check.

            - Walk the entire stack and possibly with a depth limit

              `Thread.dumpStack` and the stack trace of a `Throwable`
              traverse the entire stack trace


          This JEP will define a stack walk API that allows laziness, frame filtering,
          supports short reaches to stop at a frame matching some criteria
          as well as long reaches to traverse the entire stack trace. This would
          need the JVM to provide a flexible mechanism to traverse and materialize
          the specific stack frame information to be used and allow efficient
          lazy access to additional stack frames when required.
          Native JVM transitions should be minimized. On the other hand,
          the implementation will need to have a stable view on the thread's stack and
          returning a stream holding a stack pointer for further manipulation in an uncontrolled
          manner will not work because as soon as the stream factory returns, the JVM is free to
          reorganize the control stack (via deoptimization, for example) that will influence how
          the API is defined.

          The API will define how it works when running with a security manager
          that allows access to a `Class` instance of any frame ensuring that the security
          is not compromised.

          ### API

          One API proposal is to define a capability-based `StackWalker` API to traverse the stack. The security permission check will be performed on the `StackWalker` object per the requested capabilities at construction time such as the capability to access `Class` object of a frame.

              public <T> T walk(Function<Stream<StackFrame>, T> function)

              public Class<?> getCallerClass()

              public Optional<StackFrame> findCaller(Predicate<StackFrame> predicate)

            - The `walk` method taking a callback ti traverse a stream of StackFrame will allow the stack walking to establish its own stack frame and then provide controlled access. Another alternative to have the `walk` method is to return `Stream<StackFrame>` that needs further investigation and prototype to determine the feasibility of safely and lazy traversal of the stack in a controlled manner.

            - The `getCallerClass()` method and `findCaller(Predicate<StackFrameInfo> predicate)` are convenient methods to find the caller frame with or without filtering.

          Testing
          -------

             - Unit tests and JCK tests for the new SE API will need to be developed.

             - Performance/scalability: performance measurement shall be performed
              using micro-benchmarks as well as real world usage of `getCallerClass`
              replaced with the new API.

          mchung Mandy Chung made changes -
          Fix Version/s 9 [ 14949 ]
          Fix Version/s 10 [ 16302 ]
          mchung Mandy Chung made changes -
          Assignee Mark Reinhold [ mr ] Mandy Chung [ mchung ]
          mr Mark Reinhold made changes -
          Reviewed By [briangoetz] [briangoetz, mr]
          mr Mark Reinhold made changes -
          Description Goal
          ----

          Define a standard API for stack walking that will be efficient
          and allows easy filtering and lazy access to stack traces.

          Motivation
          ----------

          There is no standard API to obtain information about the caller's class
          and traverse the execution stack in a performant way. Existing libraries
          and frameworks such as Log4j and Groovy have to resort to using the
          JDK internal API `sun.reflect.Reflection.getCallerClass(int depth)`
          or creating an exception and parsing the stack trace.

          This JEP proposes to define a standard API for stack walking that will
          be efficient and also enable the implementation up
          level the stack walk machinery from the VM to Java and replaces
          the current mechanism of `Throwable.fillInStackTrace`.

          Description
          -----------

          There is no standard API to traverse certain frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are APIs that allow to access the stack trace information:

             - `Throwable.getStackTrace()` and `Thread.getStackTrace()` that returns
               an array of `StackTraceElement` which contains the classname
               and method name of a stack trace.

             - `SecurityManager.getClassContext()` which is a protected method
               such that only `SecurityManager` subclass can access the class
               context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack trace and returns the information representing the entire stack.
          There is no other way to avoid the cost to examine all frames if
          the caller is only interested in the top few frames on the stack.
          Both `Throwable.getStackTrace()` and `Thread.getStackTrace()` methods
          return an array of `StackTraceElement` that contains the classname and
          method name of a stack frame but not the `Class` instance.

          In fact, for applications interested in the entire stack, the specification
          allows VM implementation to omit some frames in the stack for performance.
          In other words, `Thread.getStackTrace()` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend on
          the `getCallerClass(int depth)` method or its performance overhead
          is intolerable. The use cases include:

          The following lists several use cases to do stack walking:

            - Walk the stack until it finds the immediate caller's class

              JDK caller-sensitive APIs look up its immediate caller's class
              which will be used to determine the behavior of the API. For example
              `Class.forName(String classname)` and
              `ResourceBundle.getBundle(String rbname)` methods use the immediate
              caller's class loader to load a class and a resource bundle respectively.
              `Class.getMethod` etc will use the immediate caller's class loader
              to determine the security checks to be performed.

            - Walk the stack, filter the stack frames of specific implementation classes
              and find the first non-filtered frame

              `java.util.logging`, Log4j and Groovy runtime filter the intermediary
              stack frames (typically implementation-specific and reflection frames)
              and find the caller's class to be used by the runtime of such library
              or framework.

            - Walk the stack and finds all protection domains until it reaches
              the first privileged frame

              `AccessControlContext` represents the context for the current execution
              stack and used for permission check.

            - Walk the entire stack and possibly with a depth limit

              `Thread.dumpStack` and the stack trace of a `Throwable`
              traverse the entire stack trace


          This JEP will define a stack walk API that allows laziness, frame filtering,
          supports short reaches to stop at a frame matching some criteria
          as well as long reaches to traverse the entire stack trace. This would
          need the JVM to provide a flexible mechanism to traverse and materialize
          the specific stack frame information to be used and allow efficient
          lazy access to additional stack frames when required.
          Native JVM transitions should be minimized. On the other hand,
          the implementation will need to have a stable view on the thread's stack and
          returning a stream holding a stack pointer for further manipulation in an uncontrolled
          manner will not work because as soon as the stream factory returns, the JVM is free to
          reorganize the control stack (via deoptimization, for example) that will influence how
          the API is defined.

          The API will define how it works when running with a security manager
          that allows access to a `Class` instance of any frame ensuring that the security
          is not compromised.

          ### API

          One API proposal is to define a capability-based `StackWalker` API to traverse the stack. The security permission check will be performed on the `StackWalker` object per the requested capabilities at construction time such as the capability to access `Class` object of a frame.

              public <T> T walk(Function<Stream<StackFrame>, T> function)

              public Class<?> getCallerClass()

              public Optional<StackFrame> findCaller(Predicate<StackFrame> predicate)

            - The `walk` method taking a callback ti traverse a stream of StackFrame will allow the stack walking to establish its own stack frame and then provide controlled access. Another alternative to have the `walk` method is to return `Stream<StackFrame>` that needs further investigation and prototype to determine the feasibility of safely and lazy traversal of the stack in a controlled manner.

            - The `getCallerClass()` method and `findCaller(Predicate<StackFrameInfo> predicate)` are convenient methods to find the caller frame with or without filtering.

          Testing
          -------

             - Unit tests and JCK tests for the new SE API will need to be developed.

             - Performance/scalability: performance measurement shall be performed
              using micro-benchmarks as well as real world usage of `getCallerClass`
              replaced with the new API.

          Goal
          ----

          Define an efficient standard API for stack walking that allows easy
          filtering of, and lazy access to, the information in stack traces.


          Motivation
          ----------

          There is no standard API to traverse selected frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are existing APIs that provide access stack-trace information:

             - `Throwable::getStackTrace` and `Thread::getStackTrace` return an
               array of `StackTraceElement` objects, which contain the class name
               and method name of each stack-trace element.

             - `SecurityManager::getClassContext` is a protected method, which
               allows a `SecurityManager` subclass to access the class context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack, and they return information representing the entire stack. There
          is no way to avoid the cost of examining all the frames if the caller is
          only interested in the top few frames on the stack. Both the
          `Throwable::getStackTrace` and `Thread::getStackTrace` methods return an
          array of `StackTraceElement` objects, which contain class names and
          method names but not the actual `Class` instances. For applications
          interested in the entire stack, the specification allows the VM
          implementation to omit some frames in the stack for performance. In
          other words, `Thread::getStackTrace` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend upon the
          JDK-internal `sun.reflect.Reflection::getCallerClass` method, or else
          their performance overhead is intolerable. These use cases include:

            - Walk the stack until the immediate caller's class is found. Every
              JDK caller-sensitive API looks up its immediate caller's class in
              order to determine the behavior of the API. For example, the
              `Class::forName` and `ResourceBundle::getBundle` methods use the
              immediate caller's class loader to load a class and a resource bundle
              respectively. Reflective APIs such as `Class::getMethod` use the
              immediate caller's class loader to determine the security checks to
              be performed.

            - Walk the stack, filtering out the stack frames of specific
              implementation classes to find the first non-filtered frame. The
              `java.util.logging` API, Log4j, and the Groovy runtime filter
              intermediate stack frames (typically implementation-specific and
              reflection frames) to find the caller's class.

            - Walk the stack to find all protection domains, until the first
              privileged frame is reached. This is required in order to do
              permission checks.

            - Walk the entire stack, possibly with a depth limit. This is required
              to generate the stack trace of any `Throwable` object, and to
              implement the `Thread::dumpStack` method.


          Description
          -----------

          This JEP will define a stack-walking API that allows laziness and frame
          filtering, supports short walks that stop at a frame matching given
          criteria, and also supports long walks that traverse the entire stack.

          The JVM will be enhanced to provide a flexible mechanism to traverse and
          materialize the required stack-frame information and allow efficient lazy
          access to additional stack frames when required. Native JVM transitions
          will be minimized. The implementation will need to have a stable view of
          a thread's stack: Returning a stream holding a stack pointer for further
          manipulation in an uncontrolled manner will not work since, as soon as
          the stream factory returns, the JVM will be free to reorganize the
          control stack (via deoptimization, for example). This will influence the
          API's definition.

          The API will specify its behavior when running with a security manager,
          so that access to the `Class` objects in stack frames do not compromise
          security.


          ### API

          One possible approach is to define a capability-based `StackWalker` API
          to traverse the stack. The security permission check will be performed
          on each `StackWalker` object when it is constructed rather than each time
          it is used. It could define the following methods:

              public <T> T walk(Function<Stream<StackFrame>, T> function);
              public Class<?> getCallerClass();
              public Optional<StackFrame> findCaller(Predicate<StackFrame> predicate);

          The `walk` method takes a function that can traverse a stream of stack
          frames. An alternative would be to have the `walk` method return
          `Stream<StackFrame>`, but this needs further investigation and
          prototyping to determine its feasibility and safety.

          The `getCallerClass()` `findCaller(Predicate<StackFrameInfo> predicate)`
          methods are for convenience, to find the caller's frame with or without
          filtering.
          mr Mark Reinhold made changes -
          Description Goal
          ----

          Define an efficient standard API for stack walking that allows easy
          filtering of, and lazy access to, the information in stack traces.


          Motivation
          ----------

          There is no standard API to traverse selected frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are existing APIs that provide access stack-trace information:

             - `Throwable::getStackTrace` and `Thread::getStackTrace` return an
               array of `StackTraceElement` objects, which contain the class name
               and method name of each stack-trace element.

             - `SecurityManager::getClassContext` is a protected method, which
               allows a `SecurityManager` subclass to access the class context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack, and they return information representing the entire stack. There
          is no way to avoid the cost of examining all the frames if the caller is
          only interested in the top few frames on the stack. Both the
          `Throwable::getStackTrace` and `Thread::getStackTrace` methods return an
          array of `StackTraceElement` objects, which contain class names and
          method names but not the actual `Class` instances. For applications
          interested in the entire stack, the specification allows the VM
          implementation to omit some frames in the stack for performance. In
          other words, `Thread::getStackTrace` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend upon the
          JDK-internal `sun.reflect.Reflection::getCallerClass` method, or else
          their performance overhead is intolerable. These use cases include:

            - Walk the stack until the immediate caller's class is found. Every
              JDK caller-sensitive API looks up its immediate caller's class in
              order to determine the behavior of the API. For example, the
              `Class::forName` and `ResourceBundle::getBundle` methods use the
              immediate caller's class loader to load a class and a resource bundle
              respectively. Reflective APIs such as `Class::getMethod` use the
              immediate caller's class loader to determine the security checks to
              be performed.

            - Walk the stack, filtering out the stack frames of specific
              implementation classes to find the first non-filtered frame. The
              `java.util.logging` API, Log4j, and the Groovy runtime filter
              intermediate stack frames (typically implementation-specific and
              reflection frames) to find the caller's class.

            - Walk the stack to find all protection domains, until the first
              privileged frame is reached. This is required in order to do
              permission checks.

            - Walk the entire stack, possibly with a depth limit. This is required
              to generate the stack trace of any `Throwable` object, and to
              implement the `Thread::dumpStack` method.


          Description
          -----------

          This JEP will define a stack-walking API that allows laziness and frame
          filtering, supports short walks that stop at a frame matching given
          criteria, and also supports long walks that traverse the entire stack.

          The JVM will be enhanced to provide a flexible mechanism to traverse and
          materialize the required stack-frame information and allow efficient lazy
          access to additional stack frames when required. Native JVM transitions
          will be minimized. The implementation will need to have a stable view of
          a thread's stack: Returning a stream holding a stack pointer for further
          manipulation in an uncontrolled manner will not work since, as soon as
          the stream factory returns, the JVM will be free to reorganize the
          control stack (via deoptimization, for example). This will influence the
          API's definition.

          The API will specify its behavior when running with a security manager,
          so that access to the `Class` objects in stack frames do not compromise
          security.


          ### API

          One possible approach is to define a capability-based `StackWalker` API
          to traverse the stack. The security permission check will be performed
          on each `StackWalker` object when it is constructed rather than each time
          it is used. It could define the following methods:

              public <T> T walk(Function<Stream<StackFrame>, T> function);
              public Class<?> getCallerClass();
              public Optional<StackFrame> findCaller(Predicate<StackFrame> predicate);

          The `walk` method takes a function that can traverse a stream of stack
          frames. An alternative would be to have the `walk` method return
          `Stream<StackFrame>`, but this needs further investigation and
          prototyping to determine its feasibility and safety.

          The `getCallerClass()` `findCaller(Predicate<StackFrameInfo> predicate)`
          methods are for convenience, to find the caller's frame with or without
          filtering.
          Summary
          -------

          Define an efficient standard API for stack walking that allows easy
          filtering of, and lazy access to, the information in stack traces.


          Motivation
          ----------

          There is no standard API to traverse selected frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are existing APIs that provide access stack-trace information:

             - `Throwable::getStackTrace` and `Thread::getStackTrace` return an
               array of `StackTraceElement` objects, which contain the class name
               and method name of each stack-trace element.

             - `SecurityManager::getClassContext` is a protected method, which
               allows a `SecurityManager` subclass to access the class context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack, and they return information representing the entire stack. There
          is no way to avoid the cost of examining all the frames if the caller is
          only interested in the top few frames on the stack. Both the
          `Throwable::getStackTrace` and `Thread::getStackTrace` methods return an
          array of `StackTraceElement` objects, which contain class names and
          method names but not the actual `Class` instances. For applications
          interested in the entire stack, the specification allows the VM
          implementation to omit some frames in the stack for performance. In
          other words, `Thread::getStackTrace` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend upon the
          JDK-internal `sun.reflect.Reflection::getCallerClass` method, or else
          their performance overhead is intolerable. These use cases include:

            - Walk the stack until the immediate caller's class is found. Every
              JDK caller-sensitive API looks up its immediate caller's class in
              order to determine the behavior of the API. For example, the
              `Class::forName` and `ResourceBundle::getBundle` methods use the
              immediate caller's class loader to load a class and a resource bundle
              respectively. Reflective APIs such as `Class::getMethod` use the
              immediate caller's class loader to determine the security checks to
              be performed.

            - Walk the stack, filtering out the stack frames of specific
              implementation classes to find the first non-filtered frame. The
              `java.util.logging` API, Log4j, and the Groovy runtime filter
              intermediate stack frames (typically implementation-specific and
              reflection frames) to find the caller's class.

            - Walk the stack to find all protection domains, until the first
              privileged frame is reached. This is required in order to do
              permission checks.

            - Walk the entire stack, possibly with a depth limit. This is required
              to generate the stack trace of any `Throwable` object, and to
              implement the `Thread::dumpStack` method.


          Description
          -----------

          This JEP will define a stack-walking API that allows laziness and frame
          filtering, supports short walks that stop at a frame matching given
          criteria, and also supports long walks that traverse the entire stack.

          The JVM will be enhanced to provide a flexible mechanism to traverse and
          materialize the required stack-frame information and allow efficient lazy
          access to additional stack frames when required. Native JVM transitions
          will be minimized. The implementation will need to have a stable view of
          a thread's stack: Returning a stream holding a stack pointer for further
          manipulation in an uncontrolled manner will not work since, as soon as
          the stream factory returns, the JVM will be free to reorganize the
          control stack (via deoptimization, for example). This will influence the
          API's definition.

          The API will specify its behavior when running with a security manager,
          so that access to the `Class` objects in stack frames do not compromise
          security.


          ### API

          One possible approach is to define a capability-based `StackWalker` API
          to traverse the stack. The security permission check will be performed
          on each `StackWalker` object when it is constructed rather than each time
          it is used. It could define the following methods:

              public <T> T walk(Function<Stream<StackFrame>, T> function);
              public Class<?> getCallerClass();
              public Optional<StackFrame> findCaller(Predicate<StackFrame> predicate);

          The `walk` method takes a function that can traverse a stream of stack
          frames. An alternative would be to have the `walk` method return
          `Stream<StackFrame>`, but this needs further investigation and
          prototyping to determine its feasibility and safety.

          The `getCallerClass()` `findCaller(Predicate<StackFrameInfo> predicate)`
          methods are for convenience, to find the caller's frame with or without
          filtering.
          mr Mark Reinhold made changes -
          Status Submitted [ 10002 ] Candidate [ 10003 ]
          JEP Number 259
          mr Mark Reinhold made changes -
          Summary Efficient API for Stack Walking JEP 259: Efficient API for Stack Walking
          mr Mark Reinhold made changes -
          Summary JEP 259: Efficient API for Stack Walking JEP 259: Stack-Walking API
          mchung Mandy Chung made changes -
          Integration Due 2015-11-13
          mchung Mandy Chung made changes -
          Due Date 2015-11-13
          mchung Mandy Chung made changes -
          Due Date 2015-11-13 2015-11-27
          mchung Mandy Chung made changes -
          Description Summary
          -------

          Define an efficient standard API for stack walking that allows easy
          filtering of, and lazy access to, the information in stack traces.


          Motivation
          ----------

          There is no standard API to traverse selected frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are existing APIs that provide access stack-trace information:

             - `Throwable::getStackTrace` and `Thread::getStackTrace` return an
               array of `StackTraceElement` objects, which contain the class name
               and method name of each stack-trace element.

             - `SecurityManager::getClassContext` is a protected method, which
               allows a `SecurityManager` subclass to access the class context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack, and they return information representing the entire stack. There
          is no way to avoid the cost of examining all the frames if the caller is
          only interested in the top few frames on the stack. Both the
          `Throwable::getStackTrace` and `Thread::getStackTrace` methods return an
          array of `StackTraceElement` objects, which contain class names and
          method names but not the actual `Class` instances. For applications
          interested in the entire stack, the specification allows the VM
          implementation to omit some frames in the stack for performance. In
          other words, `Thread::getStackTrace` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend upon the
          JDK-internal `sun.reflect.Reflection::getCallerClass` method, or else
          their performance overhead is intolerable. These use cases include:

            - Walk the stack until the immediate caller's class is found. Every
              JDK caller-sensitive API looks up its immediate caller's class in
              order to determine the behavior of the API. For example, the
              `Class::forName` and `ResourceBundle::getBundle` methods use the
              immediate caller's class loader to load a class and a resource bundle
              respectively. Reflective APIs such as `Class::getMethod` use the
              immediate caller's class loader to determine the security checks to
              be performed.

            - Walk the stack, filtering out the stack frames of specific
              implementation classes to find the first non-filtered frame. The
              `java.util.logging` API, Log4j, and the Groovy runtime filter
              intermediate stack frames (typically implementation-specific and
              reflection frames) to find the caller's class.

            - Walk the stack to find all protection domains, until the first
              privileged frame is reached. This is required in order to do
              permission checks.

            - Walk the entire stack, possibly with a depth limit. This is required
              to generate the stack trace of any `Throwable` object, and to
              implement the `Thread::dumpStack` method.


          Description
          -----------

          This JEP will define a stack-walking API that allows laziness and frame
          filtering, supports short walks that stop at a frame matching given
          criteria, and also supports long walks that traverse the entire stack.

          The JVM will be enhanced to provide a flexible mechanism to traverse and
          materialize the required stack-frame information and allow efficient lazy
          access to additional stack frames when required. Native JVM transitions
          will be minimized. The implementation will need to have a stable view of
          a thread's stack: Returning a stream holding a stack pointer for further
          manipulation in an uncontrolled manner will not work since, as soon as
          the stream factory returns, the JVM will be free to reorganize the
          control stack (via deoptimization, for example). This will influence the
          API's definition.

          The API will specify its behavior when running with a security manager,
          so that access to the `Class` objects in stack frames do not compromise
          security.


          ### API

          One possible approach is to define a capability-based `StackWalker` API
          to traverse the stack. The security permission check will be performed
          on each `StackWalker` object when it is constructed rather than each time
          it is used. It could define the following methods:

              public <T> T walk(Function<Stream<StackFrame>, T> function);
              public Class<?> getCallerClass();
              public Optional<StackFrame> findCaller(Predicate<StackFrame> predicate);

          The `walk` method takes a function that can traverse a stream of stack
          frames. An alternative would be to have the `walk` method return
          `Stream<StackFrame>`, but this needs further investigation and
          prototyping to determine its feasibility and safety.

          The `getCallerClass()` `findCaller(Predicate<StackFrameInfo> predicate)`
          methods are for convenience, to find the caller's frame with or without
          filtering.
          Summary
          -------

          Define an efficient standard API for stack walking that allows easy
          filtering of, and lazy access to, the information in stack traces.


          Motivation
          ----------

          There is no standard API to traverse selected frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are existing APIs that provide access stack-trace information:

             - `Throwable::getStackTrace` and `Thread::getStackTrace` return an
               array of `StackTraceElement` objects, which contain the class name
               and method name of each stack-trace element.

             - `SecurityManager::getClassContext` is a protected method, which
               allows a `SecurityManager` subclass to access the class context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack, and they return information representing the entire stack. There
          is no way to avoid the cost of examining all the frames if the caller is
          only interested in the top few frames on the stack. Both the
          `Throwable::getStackTrace` and `Thread::getStackTrace` methods return an
          array of `StackTraceElement` objects, which contain class names and
          method names but not the actual `Class` instances. For applications
          interested in the entire stack, the specification allows the VM
          implementation to omit some frames in the stack for performance. In
          other words, `Thread::getStackTrace` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend upon the
          JDK-internal `sun.reflect.Reflection::getCallerClass` method, or else
          their performance overhead is intolerable. These use cases include:

            - Walk the stack until the immediate caller's class is found. Every
              JDK caller-sensitive API looks up its immediate caller's class in
              order to determine the behavior of the API. For example, the
              `Class::forName` and `ResourceBundle::getBundle` methods use the
              immediate caller's class loader to load a class and a resource bundle
              respectively. Reflective APIs such as `Class::getMethod` use the
              immediate caller's class loader to determine the security checks to
              be performed.

            - Walk the stack, filtering out the stack frames of specific
              implementation classes to find the first non-filtered frame. The
              `java.util.logging` API, Log4j, and the Groovy runtime filter
              intermediate stack frames (typically implementation-specific and
              reflection frames) to find the caller's class.

            - Walk the stack to find all protection domains, until the first
              privileged frame is reached. This is required in order to do
              permission checks.

            - Walk the entire stack, possibly with a depth limit. This is required
              to generate the stack trace of any `Throwable` object, and to
              implement the `Thread::dumpStack` method.


          Description
          -----------

          This JEP will define a stack-walking API that allows laziness and frame
          filtering, supports short walks that stop at a frame matching given
          criteria, and also supports long walks that traverse the entire stack.

          The JVM will be enhanced to provide a flexible mechanism to traverse and
          materialize the required stack-frame information and allow efficient lazy
          access to additional stack frames when required. Native JVM transitions
          will be minimized. The implementation will need to have a stable view of
          a thread's stack: Returning a stream holding a stack pointer for further
          manipulation in an uncontrolled manner will not work since, as soon as
          the stream factory returns, the JVM will be free to reorganize the
          control stack (via deoptimization, for example). This will influence the
          API's definition.

          The API will specify its behavior when running with a security manager,
          so that access to the `Class` objects in stack frames do not compromise
          security.


          ### API

          One possible approach is to define a capability-based `StackWalker` API
          to traverse the stack. The security permission check will be performed
          on each `StackWalker` object when it is constructed rather than each time
          it is used. It could define the following methods:

              public <T> T walk(Function<Stream<StackFrame>, T> function);
              public Class<?> getCallerClass();
              public Optional<StackFrame> findCaller(Predicate<StackFrame> predicate);

          The `walk` method takes a function that can traverse a stream of stack
          frames. An alternative would be to have the `walk` method return
          `Stream<StackFrame>`, but this needs further investigation and
          prototyping to determine its feasibility and safety.

          The `getCallerClass()` and `findCaller(Predicate<StackFrameInfo> predicate)`
          methods are for convenience, to find the caller's frame with or without
          filtering.
          mchung Mandy Chung made changes -
          Description Summary
          -------

          Define an efficient standard API for stack walking that allows easy
          filtering of, and lazy access to, the information in stack traces.


          Motivation
          ----------

          There is no standard API to traverse selected frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are existing APIs that provide access stack-trace information:

             - `Throwable::getStackTrace` and `Thread::getStackTrace` return an
               array of `StackTraceElement` objects, which contain the class name
               and method name of each stack-trace element.

             - `SecurityManager::getClassContext` is a protected method, which
               allows a `SecurityManager` subclass to access the class context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack, and they return information representing the entire stack. There
          is no way to avoid the cost of examining all the frames if the caller is
          only interested in the top few frames on the stack. Both the
          `Throwable::getStackTrace` and `Thread::getStackTrace` methods return an
          array of `StackTraceElement` objects, which contain class names and
          method names but not the actual `Class` instances. For applications
          interested in the entire stack, the specification allows the VM
          implementation to omit some frames in the stack for performance. In
          other words, `Thread::getStackTrace` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend upon the
          JDK-internal `sun.reflect.Reflection::getCallerClass` method, or else
          their performance overhead is intolerable. These use cases include:

            - Walk the stack until the immediate caller's class is found. Every
              JDK caller-sensitive API looks up its immediate caller's class in
              order to determine the behavior of the API. For example, the
              `Class::forName` and `ResourceBundle::getBundle` methods use the
              immediate caller's class loader to load a class and a resource bundle
              respectively. Reflective APIs such as `Class::getMethod` use the
              immediate caller's class loader to determine the security checks to
              be performed.

            - Walk the stack, filtering out the stack frames of specific
              implementation classes to find the first non-filtered frame. The
              `java.util.logging` API, Log4j, and the Groovy runtime filter
              intermediate stack frames (typically implementation-specific and
              reflection frames) to find the caller's class.

            - Walk the stack to find all protection domains, until the first
              privileged frame is reached. This is required in order to do
              permission checks.

            - Walk the entire stack, possibly with a depth limit. This is required
              to generate the stack trace of any `Throwable` object, and to
              implement the `Thread::dumpStack` method.


          Description
          -----------

          This JEP will define a stack-walking API that allows laziness and frame
          filtering, supports short walks that stop at a frame matching given
          criteria, and also supports long walks that traverse the entire stack.

          The JVM will be enhanced to provide a flexible mechanism to traverse and
          materialize the required stack-frame information and allow efficient lazy
          access to additional stack frames when required. Native JVM transitions
          will be minimized. The implementation will need to have a stable view of
          a thread's stack: Returning a stream holding a stack pointer for further
          manipulation in an uncontrolled manner will not work since, as soon as
          the stream factory returns, the JVM will be free to reorganize the
          control stack (via deoptimization, for example). This will influence the
          API's definition.

          The API will specify its behavior when running with a security manager,
          so that access to the `Class` objects in stack frames do not compromise
          security.


          ### API

          One possible approach is to define a capability-based `StackWalker` API
          to traverse the stack. The security permission check will be performed
          on each `StackWalker` object when it is constructed rather than each time
          it is used. It could define the following methods:

              public <T> T walk(Function<Stream<StackFrame>, T> function);
              public Class<?> getCallerClass();
              public Optional<StackFrame> findCaller(Predicate<StackFrame> predicate);

          The `walk` method takes a function that can traverse a stream of stack
          frames. An alternative would be to have the `walk` method return
          `Stream<StackFrame>`, but this needs further investigation and
          prototyping to determine its feasibility and safety.

          The `getCallerClass()` and `findCaller(Predicate<StackFrameInfo> predicate)`
          methods are for convenience, to find the caller's frame with or without
          filtering.
          Summary
          -------

          Define an efficient standard API for stack walking that allows easy
          filtering of, and lazy access to, the information in stack traces.

          Non-Goal
          ---------

             - It is not a goal to convert all existing stack walking code in the JDK via this new API.

          Motivation
          ----------

          There is no standard API to traverse selected frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are existing APIs that provide access stack-trace information:

             - `Throwable::getStackTrace` and `Thread::getStackTrace` return an
               array of `StackTraceElement` objects, which contain the class name
               and method name of each stack-trace element.

             - `SecurityManager::getClassContext` is a protected method, which
               allows a `SecurityManager` subclass to access the class context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack, and they return information representing the entire stack. There
          is no way to avoid the cost of examining all the frames if the caller is
          only interested in the top few frames on the stack. Both the
          `Throwable::getStackTrace` and `Thread::getStackTrace` methods return an
          array of `StackTraceElement` objects, which contain class names and
          method names but not the actual `Class` instances. For applications
          interested in the entire stack, the specification allows the VM
          implementation to omit some frames in the stack for performance. In
          other words, `Thread::getStackTrace` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend upon the
          JDK-internal `sun.reflect.Reflection::getCallerClass` method, or else
          their performance overhead is intolerable. These use cases include:

            - Walk the stack until the immediate caller's class is found. Every
              JDK caller-sensitive API looks up its immediate caller's class in
              order to determine the behavior of the API. For example, the
              `Class::forName` and `ResourceBundle::getBundle` methods use the
              immediate caller's class loader to load a class and a resource bundle
              respectively. Reflective APIs such as `Class::getMethod` use the
              immediate caller's class loader to determine the security checks to
              be performed.

            - Walk the stack, filtering out the stack frames of specific
              implementation classes to find the first non-filtered frame. The
              `java.util.logging` API, Log4j, and the Groovy runtime filter
              intermediate stack frames (typically implementation-specific and
              reflection frames) to find the caller's class.

            - Walk the stack to find all protection domains, until the first
              privileged frame is reached. This is required in order to do
              permission checks.

            - Walk the entire stack, possibly with a depth limit. This is required
              to generate the stack trace of any `Throwable` object, and to
              implement the `Thread::dumpStack` method.


          Description
          -----------

          This JEP will define a stack-walking API that allows laziness and frame
          filtering, supports short walks that stop at a frame matching given
          criteria, and also supports long walks that traverse the entire stack.

          The JVM will be enhanced to provide a flexible mechanism to traverse and
          materialize the required stack-frame information and allow efficient lazy
          access to additional stack frames when required. Native JVM transitions
          will be minimized. The implementation will need to have a stable view of
          a thread's stack: Returning a stream holding a stack pointer for further
          manipulation in an uncontrolled manner will not work since, as soon as
          the stream factory returns, the JVM will be free to reorganize the
          control stack (via deoptimization, for example). This will influence the
          API's definition.

          The API will specify its behavior when running with a security manager,
          so that access to the `Class` objects in stack frames do not compromise
          security. The proposal is to define a capability-based `StackWalker` API
          to traverse the stack. The security permission check will be performed
          on each `StackWalker` object when it is constructed rather than each time
          it is used. It could define the following methods:

              public <T> T walk(Function<Stream<StackFrame>, T> function);
              public Class<?> getCallerClass();

          The `walk` method takes a function that can traverse a stream of stack
          frames. The `getCallerClass()` method is for convenience, to find the
          caller's frame without filtering and is the replacement for
          `sun.reflect.Reflection.getCallerClass`.

          Alternatives
          ------------

          An alternative API choice would be to have the `walk` method to return `Stream<StackFrame>`.
          When a stream of stack frames is created, as soon as the stream factory returns,
          the JVM is free to reorganize the control stack via deoptimization, for example.
          Returning `Stream<StackFrame>` will not work and the stream object may be used
          in an uncontrolled manner for further manipulation and there is no robust way to
          detect if the stack has been mutated. Instead, similar to `AccessController::doPrivileged`,
          at least one native method must be created which will establish its own stack frame and
          then provide controlled access to the JVM's stack walking logic, for older frames.
          When this native method returns, that capability must be deactivated, or else made inaccessible
          in some other way. In this way, we can do efficient lazy access to stack frames, on a stable view
          of the thread's own control stack.
          mchung Mandy Chung made changes -
          Description Summary
          -------

          Define an efficient standard API for stack walking that allows easy
          filtering of, and lazy access to, the information in stack traces.

          Non-Goal
          ---------

             - It is not a goal to convert all existing stack walking code in the JDK via this new API.

          Motivation
          ----------

          There is no standard API to traverse selected frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are existing APIs that provide access stack-trace information:

             - `Throwable::getStackTrace` and `Thread::getStackTrace` return an
               array of `StackTraceElement` objects, which contain the class name
               and method name of each stack-trace element.

             - `SecurityManager::getClassContext` is a protected method, which
               allows a `SecurityManager` subclass to access the class context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack, and they return information representing the entire stack. There
          is no way to avoid the cost of examining all the frames if the caller is
          only interested in the top few frames on the stack. Both the
          `Throwable::getStackTrace` and `Thread::getStackTrace` methods return an
          array of `StackTraceElement` objects, which contain class names and
          method names but not the actual `Class` instances. For applications
          interested in the entire stack, the specification allows the VM
          implementation to omit some frames in the stack for performance. In
          other words, `Thread::getStackTrace` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend upon the
          JDK-internal `sun.reflect.Reflection::getCallerClass` method, or else
          their performance overhead is intolerable. These use cases include:

            - Walk the stack until the immediate caller's class is found. Every
              JDK caller-sensitive API looks up its immediate caller's class in
              order to determine the behavior of the API. For example, the
              `Class::forName` and `ResourceBundle::getBundle` methods use the
              immediate caller's class loader to load a class and a resource bundle
              respectively. Reflective APIs such as `Class::getMethod` use the
              immediate caller's class loader to determine the security checks to
              be performed.

            - Walk the stack, filtering out the stack frames of specific
              implementation classes to find the first non-filtered frame. The
              `java.util.logging` API, Log4j, and the Groovy runtime filter
              intermediate stack frames (typically implementation-specific and
              reflection frames) to find the caller's class.

            - Walk the stack to find all protection domains, until the first
              privileged frame is reached. This is required in order to do
              permission checks.

            - Walk the entire stack, possibly with a depth limit. This is required
              to generate the stack trace of any `Throwable` object, and to
              implement the `Thread::dumpStack` method.


          Description
          -----------

          This JEP will define a stack-walking API that allows laziness and frame
          filtering, supports short walks that stop at a frame matching given
          criteria, and also supports long walks that traverse the entire stack.

          The JVM will be enhanced to provide a flexible mechanism to traverse and
          materialize the required stack-frame information and allow efficient lazy
          access to additional stack frames when required. Native JVM transitions
          will be minimized. The implementation will need to have a stable view of
          a thread's stack: Returning a stream holding a stack pointer for further
          manipulation in an uncontrolled manner will not work since, as soon as
          the stream factory returns, the JVM will be free to reorganize the
          control stack (via deoptimization, for example). This will influence the
          API's definition.

          The API will specify its behavior when running with a security manager,
          so that access to the `Class` objects in stack frames do not compromise
          security. The proposal is to define a capability-based `StackWalker` API
          to traverse the stack. The security permission check will be performed
          on each `StackWalker` object when it is constructed rather than each time
          it is used. It could define the following methods:

              public <T> T walk(Function<Stream<StackFrame>, T> function);
              public Class<?> getCallerClass();

          The `walk` method takes a function that can traverse a stream of stack
          frames. The `getCallerClass()` method is for convenience, to find the
          caller's frame without filtering and is the replacement for
          `sun.reflect.Reflection.getCallerClass`.

          Alternatives
          ------------

          An alternative API choice would be to have the `walk` method to return `Stream<StackFrame>`.
          When a stream of stack frames is created, as soon as the stream factory returns,
          the JVM is free to reorganize the control stack via deoptimization, for example.
          Returning `Stream<StackFrame>` will not work and the stream object may be used
          in an uncontrolled manner for further manipulation and there is no robust way to
          detect if the stack has been mutated. Instead, similar to `AccessController::doPrivileged`,
          at least one native method must be created which will establish its own stack frame and
          then provide controlled access to the JVM's stack walking logic, for older frames.
          When this native method returns, that capability must be deactivated, or else made inaccessible
          in some other way. In this way, we can do efficient lazy access to stack frames, on a stable view
          of the thread's own control stack.
          Summary
          -------

          Define an efficient standard API for stack walking that allows easy
          filtering of, and lazy access to, the information in stack traces.

          Non-Goal
          ---------

             - It is not a goal to convert all existing stack walking code in the JDK to use this new API.

          Motivation
          ----------

          There is no standard API to traverse selected frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are existing APIs that provide access stack-trace information:

             - `Throwable::getStackTrace` and `Thread::getStackTrace` return an
               array of `StackTraceElement` objects, which contain the class name
               and method name of each stack-trace element.

             - `SecurityManager::getClassContext` is a protected method, which
               allows a `SecurityManager` subclass to access the class context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack, and they return information representing the entire stack. There
          is no way to avoid the cost of examining all the frames if the caller is
          only interested in the top few frames on the stack. Both the
          `Throwable::getStackTrace` and `Thread::getStackTrace` methods return an
          array of `StackTraceElement` objects, which contain class names and
          method names but not the actual `Class` instances. For applications
          interested in the entire stack, the specification allows the VM
          implementation to omit some frames in the stack for performance. In
          other words, `Thread::getStackTrace` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend upon the
          JDK-internal `sun.reflect.Reflection::getCallerClass` method, or else
          their performance overhead is intolerable. These use cases include:

            - Walk the stack until the immediate caller's class is found. Every
              JDK caller-sensitive API looks up its immediate caller's class in
              order to determine the behavior of the API. For example, the
              `Class::forName` and `ResourceBundle::getBundle` methods use the
              immediate caller's class loader to load a class and a resource bundle
              respectively. Reflective APIs such as `Class::getMethod` use the
              immediate caller's class loader to determine the security checks to
              be performed.

            - Walk the stack, filtering out the stack frames of specific
              implementation classes to find the first non-filtered frame. The
              `java.util.logging` API, Log4j, and the Groovy runtime filter
              intermediate stack frames (typically implementation-specific and
              reflection frames) to find the caller's class.

            - Walk the stack to find all protection domains, until the first
              privileged frame is reached. This is required in order to do
              permission checks.

            - Walk the entire stack, possibly with a depth limit. This is required
              to generate the stack trace of any `Throwable` object, and to
              implement the `Thread::dumpStack` method.


          Description
          -----------

          This JEP will define a stack-walking API that allows laziness and frame
          filtering, supports short walks that stop at a frame matching given
          criteria, and also supports long walks that traverse the entire stack.

          The JVM will be enhanced to provide a flexible mechanism to traverse and
          materialize the required stack-frame information and allow efficient lazy
          access to additional stack frames when required. Native JVM transitions
          will be minimized. The implementation will need to have a stable view of
          a thread's stack: Returning a stream holding a stack pointer for further
          manipulation in an uncontrolled manner will not work since, as soon as
          the stream factory returns, the JVM will be free to reorganize the
          control stack (via deoptimization, for example). This will influence the
          API's definition.

          The API will specify its behavior when running with a security manager,
          so that access to the `Class` objects in stack frames do not compromise
          security. The proposal is to define a capability-based `StackWalker` API
          to traverse the stack. The security permission check will be performed
          on each `StackWalker` object when it is constructed rather than each time
          it is used. It could define the following methods:

              public <T> T walk(Function<Stream<StackFrame>, T> function);
              public Class<?> getCallerClass();

          The `walk` method takes a function that can traverse a stream of stack
          frames. The `getCallerClass()` method is for convenience, to find the
          caller's frame without filtering and is the replacement for
          `sun.reflect.Reflection.getCallerClass`.

          Alternatives
          ------------

          An alternative API choice would be to have the `walk` method to return `Stream<StackFrame>`.
          When a stream of stack frames is created, as soon as the stream factory returns,
          the JVM is free to reorganize the control stack via deoptimization, for example.
          Returning `Stream<StackFrame>` will not work and the stream object may be used
          in an uncontrolled manner for further manipulation and there is no robust way to
          detect if the stack has been mutated. Instead, similar to `AccessController::doPrivileged`,
          at least one native method must be created which will establish its own stack frame and
          then provide controlled access to the JVM's stack walking logic, for older frames.
          When this native method returns, that capability must be deactivated, or else made inaccessible
          in some other way. In this way, we can do efficient lazy access to stack frames, on a stable view
          of the thread's own control stack.
          mchung Mandy Chung made changes -
          Description Summary
          -------

          Define an efficient standard API for stack walking that allows easy
          filtering of, and lazy access to, the information in stack traces.

          Non-Goal
          ---------

             - It is not a goal to convert all existing stack walking code in the JDK to use this new API.

          Motivation
          ----------

          There is no standard API to traverse selected frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are existing APIs that provide access stack-trace information:

             - `Throwable::getStackTrace` and `Thread::getStackTrace` return an
               array of `StackTraceElement` objects, which contain the class name
               and method name of each stack-trace element.

             - `SecurityManager::getClassContext` is a protected method, which
               allows a `SecurityManager` subclass to access the class context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack, and they return information representing the entire stack. There
          is no way to avoid the cost of examining all the frames if the caller is
          only interested in the top few frames on the stack. Both the
          `Throwable::getStackTrace` and `Thread::getStackTrace` methods return an
          array of `StackTraceElement` objects, which contain class names and
          method names but not the actual `Class` instances. For applications
          interested in the entire stack, the specification allows the VM
          implementation to omit some frames in the stack for performance. In
          other words, `Thread::getStackTrace` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend upon the
          JDK-internal `sun.reflect.Reflection::getCallerClass` method, or else
          their performance overhead is intolerable. These use cases include:

            - Walk the stack until the immediate caller's class is found. Every
              JDK caller-sensitive API looks up its immediate caller's class in
              order to determine the behavior of the API. For example, the
              `Class::forName` and `ResourceBundle::getBundle` methods use the
              immediate caller's class loader to load a class and a resource bundle
              respectively. Reflective APIs such as `Class::getMethod` use the
              immediate caller's class loader to determine the security checks to
              be performed.

            - Walk the stack, filtering out the stack frames of specific
              implementation classes to find the first non-filtered frame. The
              `java.util.logging` API, Log4j, and the Groovy runtime filter
              intermediate stack frames (typically implementation-specific and
              reflection frames) to find the caller's class.

            - Walk the stack to find all protection domains, until the first
              privileged frame is reached. This is required in order to do
              permission checks.

            - Walk the entire stack, possibly with a depth limit. This is required
              to generate the stack trace of any `Throwable` object, and to
              implement the `Thread::dumpStack` method.


          Description
          -----------

          This JEP will define a stack-walking API that allows laziness and frame
          filtering, supports short walks that stop at a frame matching given
          criteria, and also supports long walks that traverse the entire stack.

          The JVM will be enhanced to provide a flexible mechanism to traverse and
          materialize the required stack-frame information and allow efficient lazy
          access to additional stack frames when required. Native JVM transitions
          will be minimized. The implementation will need to have a stable view of
          a thread's stack: Returning a stream holding a stack pointer for further
          manipulation in an uncontrolled manner will not work since, as soon as
          the stream factory returns, the JVM will be free to reorganize the
          control stack (via deoptimization, for example). This will influence the
          API's definition.

          The API will specify its behavior when running with a security manager,
          so that access to the `Class` objects in stack frames do not compromise
          security. The proposal is to define a capability-based `StackWalker` API
          to traverse the stack. The security permission check will be performed
          on each `StackWalker` object when it is constructed rather than each time
          it is used. It could define the following methods:

              public <T> T walk(Function<Stream<StackFrame>, T> function);
              public Class<?> getCallerClass();

          The `walk` method takes a function that can traverse a stream of stack
          frames. The `getCallerClass()` method is for convenience, to find the
          caller's frame without filtering and is the replacement for
          `sun.reflect.Reflection.getCallerClass`.

          Alternatives
          ------------

          An alternative API choice would be to have the `walk` method to return `Stream<StackFrame>`.
          When a stream of stack frames is created, as soon as the stream factory returns,
          the JVM is free to reorganize the control stack via deoptimization, for example.
          Returning `Stream<StackFrame>` will not work and the stream object may be used
          in an uncontrolled manner for further manipulation and there is no robust way to
          detect if the stack has been mutated. Instead, similar to `AccessController::doPrivileged`,
          at least one native method must be created which will establish its own stack frame and
          then provide controlled access to the JVM's stack walking logic, for older frames.
          When this native method returns, that capability must be deactivated, or else made inaccessible
          in some other way. In this way, we can do efficient lazy access to stack frames, on a stable view
          of the thread's own control stack.
          Summary
          -------

          Define an efficient standard API for stack walking that allows easy
          filtering of, and lazy access to, the information in stack traces.

          Non-Goal
          ---------

             - It is not a goal to convert all existing stack walking code in the JDK to use this new API.

          Motivation
          ----------

          There is no standard API to traverse selected frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are existing APIs that provide access stack-trace information:

             - `Throwable::getStackTrace` and `Thread::getStackTrace` return an
               array of `StackTraceElement` objects, which contain the class name
               and method name of each stack-trace element.

             - `SecurityManager::getClassContext` is a protected method, which
               allows a `SecurityManager` subclass to access the class context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack, and they return information representing the entire stack. There
          is no way to avoid the cost of examining all the frames if the caller is
          only interested in the top few frames on the stack. Both the
          `Throwable::getStackTrace` and `Thread::getStackTrace` methods return an
          array of `StackTraceElement` objects, which contain class names and
          method names but not the actual `Class` instances. For applications
          interested in the entire stack, the specification allows the VM
          implementation to omit some frames in the stack for performance. In
          other words, `Thread::getStackTrace` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend upon the
          JDK-internal `sun.reflect.Reflection::getCallerClass` method, or else
          their performance overhead is intolerable. These use cases include:

            - Walk the stack until the immediate caller's class is found. Every
              JDK caller-sensitive API looks up its immediate caller's class in
              order to determine the behavior of the API. For example, the
              `Class::forName` and `ResourceBundle::getBundle` methods use the
              immediate caller's class loader to load a class and a resource bundle
              respectively. Reflective APIs such as `Class::getMethod` use the
              immediate caller's class loader to determine the security checks to
              be performed.

            - Walk the stack, filtering out the stack frames of specific
              implementation classes to find the first non-filtered frame. The
              `java.util.logging` API, Log4j, and the Groovy runtime filter
              intermediate stack frames (typically implementation-specific and
              reflection frames) to find the caller's class.

            - Walk the stack to find all protection domains, until the first
              privileged frame is reached. This is required in order to do
              permission checks.

            - Walk the entire stack, possibly with a depth limit. This is required
              to generate the stack trace of any `Throwable` object, and to
              implement the `Thread::dumpStack` method.


          Description
          -----------

          This JEP will define a stack-walking API that allows laziness and frame
          filtering, supports short walks that stop at a frame matching given
          criteria, and also supports long walks that traverse the entire stack.

          The JVM will be enhanced to provide a flexible mechanism to traverse and
          materialize the required stack-frame information and allow efficient lazy
          access to additional stack frames when required. Native JVM transitions
          will be minimized. The implementation will need to have a stable view of
          a thread's stack: Returning a stream holding a stack pointer for further
          manipulation in an uncontrolled manner will not work since, as soon as
          the stream factory returns, the JVM will be free to reorganize the
          control stack (via deoptimization, for example). This will influence the
          API's definition.

          The API will specify its behavior when running with a security manager,
          so that access to the `Class` objects in stack frames do not compromise
          security.

          The proposal is to define a capability-based `StackWalker` API
          to traverse the stack. The security permission check will be performed
          on each `StackWalker` object when it is constructed rather than each time
          it is used. It will define the following methods:

              public <T> T walk(Function<Stream<StackFrame>, T> function);
              public Class<?> getCallerClass();

          The `walk` method opens a sequential `StackFrame` stream of the current thread
          and then applies the function with the `StackFrame` stream.
          The spliterator of the stream performs the stack frame traversal in an ordered manner.
          The `Stream<StackFrame>` object can only be traversed once and will be closed
          when the `walk` method returns. The stream becomes invalid to use once it is closed.

          The `getCallerClass()` method is for convenience, to find the
          caller's frame without filtering and is the replacement for
          `sun.reflect.Reflection.getCallerClass`.

          Alternatives
          ------------

          An alternative API choice would be to have the `walk` method to return `Stream<StackFrame>`.
          When a stream of stack frames is created, as soon as the stream factory returns,
          the JVM is free to reorganize the control stack via deoptimization, for example.
          Returning `Stream<StackFrame>` will not work and the stream object may be used
          in an uncontrolled manner for further manipulation and there is no robust way to
          detect if the stack has been mutated. Instead, similar to `AccessController::doPrivileged`,
          at least one native method must be created which will establish its own stack frame and
          then provide controlled access to the JVM's stack walking logic, for older frames.
          When this native method returns, that capability must be deactivated, or else made inaccessible
          in some other way. In this way, we can do efficient lazy access to stack frames, on a stable view
          of the thread's own control stack.
          mchung Mandy Chung made changes -
          Description Summary
          -------

          Define an efficient standard API for stack walking that allows easy
          filtering of, and lazy access to, the information in stack traces.

          Non-Goal
          ---------

             - It is not a goal to convert all existing stack walking code in the JDK to use this new API.

          Motivation
          ----------

          There is no standard API to traverse selected frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are existing APIs that provide access stack-trace information:

             - `Throwable::getStackTrace` and `Thread::getStackTrace` return an
               array of `StackTraceElement` objects, which contain the class name
               and method name of each stack-trace element.

             - `SecurityManager::getClassContext` is a protected method, which
               allows a `SecurityManager` subclass to access the class context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack, and they return information representing the entire stack. There
          is no way to avoid the cost of examining all the frames if the caller is
          only interested in the top few frames on the stack. Both the
          `Throwable::getStackTrace` and `Thread::getStackTrace` methods return an
          array of `StackTraceElement` objects, which contain class names and
          method names but not the actual `Class` instances. For applications
          interested in the entire stack, the specification allows the VM
          implementation to omit some frames in the stack for performance. In
          other words, `Thread::getStackTrace` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend upon the
          JDK-internal `sun.reflect.Reflection::getCallerClass` method, or else
          their performance overhead is intolerable. These use cases include:

            - Walk the stack until the immediate caller's class is found. Every
              JDK caller-sensitive API looks up its immediate caller's class in
              order to determine the behavior of the API. For example, the
              `Class::forName` and `ResourceBundle::getBundle` methods use the
              immediate caller's class loader to load a class and a resource bundle
              respectively. Reflective APIs such as `Class::getMethod` use the
              immediate caller's class loader to determine the security checks to
              be performed.

            - Walk the stack, filtering out the stack frames of specific
              implementation classes to find the first non-filtered frame. The
              `java.util.logging` API, Log4j, and the Groovy runtime filter
              intermediate stack frames (typically implementation-specific and
              reflection frames) to find the caller's class.

            - Walk the stack to find all protection domains, until the first
              privileged frame is reached. This is required in order to do
              permission checks.

            - Walk the entire stack, possibly with a depth limit. This is required
              to generate the stack trace of any `Throwable` object, and to
              implement the `Thread::dumpStack` method.


          Description
          -----------

          This JEP will define a stack-walking API that allows laziness and frame
          filtering, supports short walks that stop at a frame matching given
          criteria, and also supports long walks that traverse the entire stack.

          The JVM will be enhanced to provide a flexible mechanism to traverse and
          materialize the required stack-frame information and allow efficient lazy
          access to additional stack frames when required. Native JVM transitions
          will be minimized. The implementation will need to have a stable view of
          a thread's stack: Returning a stream holding a stack pointer for further
          manipulation in an uncontrolled manner will not work since, as soon as
          the stream factory returns, the JVM will be free to reorganize the
          control stack (via deoptimization, for example). This will influence the
          API's definition.

          The API will specify its behavior when running with a security manager,
          so that access to the `Class` objects in stack frames do not compromise
          security.

          The proposal is to define a capability-based `StackWalker` API
          to traverse the stack. The security permission check will be performed
          on each `StackWalker` object when it is constructed rather than each time
          it is used. It will define the following methods:

              public <T> T walk(Function<Stream<StackFrame>, T> function);
              public Class<?> getCallerClass();

          The `walk` method opens a sequential `StackFrame` stream of the current thread
          and then applies the function with the `StackFrame` stream.
          The spliterator of the stream performs the stack frame traversal in an ordered manner.
          The `Stream<StackFrame>` object can only be traversed once and will be closed
          when the `walk` method returns. The stream becomes invalid to use once it is closed.

          The `getCallerClass()` method is for convenience, to find the
          caller's frame without filtering and is the replacement for
          `sun.reflect.Reflection.getCallerClass`.

          Alternatives
          ------------

          An alternative API choice would be to have the `walk` method to return `Stream<StackFrame>`.
          When a stream of stack frames is created, as soon as the stream factory returns,
          the JVM is free to reorganize the control stack via deoptimization, for example.
          Returning `Stream<StackFrame>` will not work and the stream object may be used
          in an uncontrolled manner for further manipulation and there is no robust way to
          detect if the stack has been mutated. Instead, similar to `AccessController::doPrivileged`,
          at least one native method must be created which will establish its own stack frame and
          then provide controlled access to the JVM's stack walking logic, for older frames.
          When this native method returns, that capability must be deactivated, or else made inaccessible
          in some other way. In this way, we can do efficient lazy access to stack frames, on a stable view
          of the thread's own control stack.
          Summary
          -------

          Define an efficient standard API for stack walking that allows easy
          filtering of, and lazy access to, the information in stack traces.

          Non-Goal
          ---------

             - It is not a goal to convert all existing stack walking code in the JDK to use this new API.

          Motivation
          ----------

          There is no standard API to traverse selected frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are existing APIs that provide access stack-trace information:

             - `Throwable::getStackTrace` and `Thread::getStackTrace` return an
               array of `StackTraceElement` objects, which contain the class name
               and method name of each stack-trace element.

             - `SecurityManager::getClassContext` is a protected method, which
               allows a `SecurityManager` subclass to access the class context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack, and they return information representing the entire stack. There
          is no way to avoid the cost of examining all the frames if the caller is
          only interested in the top few frames on the stack. Both the
          `Throwable::getStackTrace` and `Thread::getStackTrace` methods return an
          array of `StackTraceElement` objects, which contain class names and
          method names but not the actual `Class` instances. For applications
          interested in the entire stack, the specification allows the VM
          implementation to omit some frames in the stack for performance. In
          other words, `Thread::getStackTrace` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend upon the
          JDK-internal `sun.reflect.Reflection::getCallerClass` method, or else
          their performance overhead is intolerable. These use cases include:

            - Walk the stack until the immediate caller's class is found. Every
              JDK caller-sensitive API looks up its immediate caller's class in
              order to determine the behavior of the API. For example, the
              `Class::forName` and `ResourceBundle::getBundle` methods use the
              immediate caller's class loader to load a class and a resource bundle
              respectively. Reflective APIs such as `Class::getMethod` use the
              immediate caller's class loader to determine the security checks to
              be performed.

            - Walk the stack, filtering out the stack frames of specific
              implementation classes to find the first non-filtered frame. The
              `java.util.logging` API, Log4j, and the Groovy runtime filter
              intermediate stack frames (typically implementation-specific and
              reflection frames) to find the caller's class.

            - Walk the stack to find all protection domains, until the first
              privileged frame is reached. This is required in order to do
              permission checks.

            - Walk the entire stack, possibly with a depth limit. This is required
              to generate the stack trace of any `Throwable` object, and to
              implement the `Thread::dumpStack` method.


          Description
          -----------

          This JEP will define a stack-walking API that allows laziness and frame
          filtering, supports short walks that stop at a frame matching given
          criteria, and also supports long walks that traverse the entire stack.

          The JVM will be enhanced to provide a flexible mechanism to traverse and
          materialize the required stack-frame information and allow efficient lazy
          access to additional stack frames when required. Native JVM transitions
          will be minimized. The implementation will need to have a stable view of
          a thread's stack: Returning a stream holding a stack pointer for further
          manipulation in an uncontrolled manner will not work since, as soon as
          the stream factory returns, the JVM will be free to reorganize the
          control stack (via deoptimization, for example). This will influence the
          API's definition.

          The API will specify its behavior when running with a security manager,
          so that access to the `Class` objects in stack frames do not compromise
          security.

          The proposal is to define a capability-based `StackWalker` API
          to traverse the stack. The security permission check will be performed
          on each `StackWalker` object when it is constructed rather than each time
          it is used. It will define the following methods:

              public <T> T walk(Function<Stream<StackFrame>, T> function);
              public Class<?> getCallerClass();

          The `walk` method opens a sequential `StackFrame` stream of the current thread
          and then applies the function with the `StackFrame` stream.
          The spliterator of the stream performs the stack frame traversal in an ordered manner.
          The `Stream<StackFrame>` object can only be traversed once and will be closed
          when the `walk` method returns. The stream becomes invalid to use once it is closed.

          The `getCallerClass()` method is for convenience, to find the
          caller's frame without filtering and is the replacement for
          `sun.reflect.Reflection.getCallerClass`.

          Alternatives
          ------------

          An alternative API choice would be to have the `walk` method to return `Stream<StackFrame>`.
          When a stream of stack frames is created, as soon as the stream factory returns,
          the JVM is free to reorganize the control stack via deoptimization, for example.
          Returning `Stream<StackFrame>` will not work and the stream object may be used
          in an uncontrolled manner for further manipulation and there is no robust way to
          detect if the stack has been mutated.

          Instead, similar to `AccessController::doPrivileged`, at least one native method must be
          created which will establish its own stack frame and
          then provide controlled access to the JVM's stack walking logic, for older frames.
          When this native method returns, that capability must be deactivated, or else made inaccessible
          in some other way. In this way, we can do efficient lazy access to stack frames, on a stable view
          of the thread's own control stack.
          mchung Mandy Chung made changes -
          Description Summary
          -------

          Define an efficient standard API for stack walking that allows easy
          filtering of, and lazy access to, the information in stack traces.

          Non-Goal
          ---------

             - It is not a goal to convert all existing stack walking code in the JDK to use this new API.

          Motivation
          ----------

          There is no standard API to traverse selected frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are existing APIs that provide access stack-trace information:

             - `Throwable::getStackTrace` and `Thread::getStackTrace` return an
               array of `StackTraceElement` objects, which contain the class name
               and method name of each stack-trace element.

             - `SecurityManager::getClassContext` is a protected method, which
               allows a `SecurityManager` subclass to access the class context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack, and they return information representing the entire stack. There
          is no way to avoid the cost of examining all the frames if the caller is
          only interested in the top few frames on the stack. Both the
          `Throwable::getStackTrace` and `Thread::getStackTrace` methods return an
          array of `StackTraceElement` objects, which contain class names and
          method names but not the actual `Class` instances. For applications
          interested in the entire stack, the specification allows the VM
          implementation to omit some frames in the stack for performance. In
          other words, `Thread::getStackTrace` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend upon the
          JDK-internal `sun.reflect.Reflection::getCallerClass` method, or else
          their performance overhead is intolerable. These use cases include:

            - Walk the stack until the immediate caller's class is found. Every
              JDK caller-sensitive API looks up its immediate caller's class in
              order to determine the behavior of the API. For example, the
              `Class::forName` and `ResourceBundle::getBundle` methods use the
              immediate caller's class loader to load a class and a resource bundle
              respectively. Reflective APIs such as `Class::getMethod` use the
              immediate caller's class loader to determine the security checks to
              be performed.

            - Walk the stack, filtering out the stack frames of specific
              implementation classes to find the first non-filtered frame. The
              `java.util.logging` API, Log4j, and the Groovy runtime filter
              intermediate stack frames (typically implementation-specific and
              reflection frames) to find the caller's class.

            - Walk the stack to find all protection domains, until the first
              privileged frame is reached. This is required in order to do
              permission checks.

            - Walk the entire stack, possibly with a depth limit. This is required
              to generate the stack trace of any `Throwable` object, and to
              implement the `Thread::dumpStack` method.


          Description
          -----------

          This JEP will define a stack-walking API that allows laziness and frame
          filtering, supports short walks that stop at a frame matching given
          criteria, and also supports long walks that traverse the entire stack.

          The JVM will be enhanced to provide a flexible mechanism to traverse and
          materialize the required stack-frame information and allow efficient lazy
          access to additional stack frames when required. Native JVM transitions
          will be minimized. The implementation will need to have a stable view of
          a thread's stack: Returning a stream holding a stack pointer for further
          manipulation in an uncontrolled manner will not work since, as soon as
          the stream factory returns, the JVM will be free to reorganize the
          control stack (via deoptimization, for example). This will influence the
          API's definition.

          The API will specify its behavior when running with a security manager,
          so that access to the `Class` objects in stack frames do not compromise
          security.

          The proposal is to define a capability-based `StackWalker` API
          to traverse the stack. The security permission check will be performed
          on each `StackWalker` object when it is constructed rather than each time
          it is used. It will define the following methods:

              public <T> T walk(Function<Stream<StackFrame>, T> function);
              public Class<?> getCallerClass();

          The `walk` method opens a sequential `StackFrame` stream of the current thread
          and then applies the function with the `StackFrame` stream.
          The spliterator of the stream performs the stack frame traversal in an ordered manner.
          The `Stream<StackFrame>` object can only be traversed once and will be closed
          when the `walk` method returns. The stream becomes invalid to use once it is closed.

          The `getCallerClass()` method is for convenience, to find the
          caller's frame without filtering and is the replacement for
          `sun.reflect.Reflection.getCallerClass`.

          Alternatives
          ------------

          An alternative API choice would be to have the `walk` method to return `Stream<StackFrame>`.
          When a stream of stack frames is created, as soon as the stream factory returns,
          the JVM is free to reorganize the control stack via deoptimization, for example.
          Returning `Stream<StackFrame>` will not work and the stream object may be used
          in an uncontrolled manner for further manipulation and there is no robust way to
          detect if the stack has been mutated.

          Instead, similar to `AccessController::doPrivileged`, at least one native method must be
          created which will establish its own stack frame and
          then provide controlled access to the JVM's stack walking logic, for older frames.
          When this native method returns, that capability must be deactivated, or else made inaccessible
          in some other way. In this way, we can do efficient lazy access to stack frames, on a stable view
          of the thread's own control stack.
          Summary
          -------

          Define an efficient standard API for stack walking that allows easy
          filtering of, and lazy access to, the information in stack traces.

          Non-Goal
          ---------

             - It is not a goal to convert all existing stack walking code in the JDK to use this new API.

          Motivation
          ----------

          There is no standard API to traverse selected frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are existing APIs that provide access to a thread's stack:

             - `Throwable::getStackTrace` and `Thread::getStackTrace` return an
               array of `StackTraceElement` objects, which contain the class name
               and method name of each stack-trace element.

             - `SecurityManager::getClassContext` is a protected method, which
               allows a `SecurityManager` subclass to access the class context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack, and they return information representing the entire stack. There
          is no way to avoid the cost of examining all the frames if the caller is
          only interested in the top few frames on the stack. Both the
          `Throwable::getStackTrace` and `Thread::getStackTrace` methods return an
          array of `StackTraceElement` objects, which contain class names and
          method names but not the actual `Class` instances. For applications
          interested in the entire stack, the specification allows the VM
          implementation to omit some frames in the stack for performance. In
          other words, `Thread::getStackTrace` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend upon the
          JDK-internal `sun.reflect.Reflection::getCallerClass` method, or else
          their performance overhead is intolerable. These use cases include:

            - Walk the stack until the immediate caller's class is found. Every
              JDK caller-sensitive API looks up its immediate caller's class in
              order to determine the behavior of the API. For example, the
              `Class::forName` and `ResourceBundle::getBundle` methods use the
              immediate caller's class loader to load a class and a resource bundle
              respectively. Reflective APIs such as `Class::getMethod` use the
              immediate caller's class loader to determine the security checks to
              be performed.

            - Walk the stack, filtering out the stack frames of specific
              implementation classes to find the first non-filtered frame. The
              `java.util.logging` API, Log4j, and the Groovy runtime filter
              intermediate stack frames (typically implementation-specific and
              reflection frames) to find the caller's class.

            - Walk the stack to find all protection domains, until the first
              privileged frame is reached. This is required in order to do
              permission checks.

            - Walk the entire stack, possibly with a depth limit. This is required
              to generate the stack trace of any `Throwable` object, and to
              implement the `Thread::dumpStack` method.


          Description
          -----------

          This JEP will define a stack-walking API that allows laziness and frame
          filtering, supports short walks that stop at a frame matching given
          criteria, and also supports long walks that traverse the entire stack.

          The JVM will be enhanced to provide a flexible mechanism to traverse and
          materialize the required stack-frame information and allow efficient lazy
          access to additional stack frames when required. Native JVM transitions
          will be minimized. The implementation will need to have a stable view of
          a thread's stack: Returning a stream holding a stack pointer for further
          manipulation in an uncontrolled manner will not work since, as soon as
          the stream factory returns, the JVM will be free to reorganize the
          control stack (via deoptimization, for example). This will influence the
          API's definition.

          The API will specify its behavior when running with a security manager,
          so that access to the `Class` objects in stack frames do not compromise
          security.

          The proposal is to define a capability-based `StackWalker` API
          to traverse the stack. The security permission check will be performed
          on each `StackWalker` object when it is constructed rather than each time
          it is used. It will define the following methods:

              public <T> T walk(Function<Stream<StackFrame>, T> function);
              public Class<?> getCallerClass();

          The `walk` method opens a sequential stream of `StackFrame` for the current thread
          and then applies the function with the `StackFrame` stream.
          The spliterator of the stream performs the stack frame traversal in an ordered manner.
          The `Stream<StackFrame>` object can only be traversed once and will be closed
          when the `walk` method returns. The stream becomes invalid to use once it is closed.

          The `getCallerClass()` method is for convenience to find the caller's frame and is
          the replacement for `sun.reflect.Reflection.getCallerClass`.

          Alternatives
          ------------

          An alternative API choice would be the `walk` method to return `Stream<StackFrame>`.
          When a stream of stack frames is created, as soon as the stream factory returns,
          the JVM is free to reorganize the control stack (via deoptimization, for example).
          Returning `Stream<StackFrame>` will not work and the stream object may be used
          in an uncontrolled manner for further manipulation and there is no robust way to
          detect if the stack has been mutated.

          Instead, similar to `AccessController::doPrivileged`, at least one native method must be
          created which will establish its own stack frame and then provide controlled access
          to the JVM's stack walking logic, for older frames.
          When this native method returns, that capability must be deactivated, or else made inaccessible
          in some other way. In this way, we can do efficient lazy access to stack frames, on a stable view
          of the thread's own control stack.
          mchung Mandy Chung made changes -
          Description Summary
          -------

          Define an efficient standard API for stack walking that allows easy
          filtering of, and lazy access to, the information in stack traces.

          Non-Goal
          ---------

             - It is not a goal to convert all existing stack walking code in the JDK to use this new API.

          Motivation
          ----------

          There is no standard API to traverse selected frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are existing APIs that provide access to a thread's stack:

             - `Throwable::getStackTrace` and `Thread::getStackTrace` return an
               array of `StackTraceElement` objects, which contain the class name
               and method name of each stack-trace element.

             - `SecurityManager::getClassContext` is a protected method, which
               allows a `SecurityManager` subclass to access the class context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack, and they return information representing the entire stack. There
          is no way to avoid the cost of examining all the frames if the caller is
          only interested in the top few frames on the stack. Both the
          `Throwable::getStackTrace` and `Thread::getStackTrace` methods return an
          array of `StackTraceElement` objects, which contain class names and
          method names but not the actual `Class` instances. For applications
          interested in the entire stack, the specification allows the VM
          implementation to omit some frames in the stack for performance. In
          other words, `Thread::getStackTrace` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend upon the
          JDK-internal `sun.reflect.Reflection::getCallerClass` method, or else
          their performance overhead is intolerable. These use cases include:

            - Walk the stack until the immediate caller's class is found. Every
              JDK caller-sensitive API looks up its immediate caller's class in
              order to determine the behavior of the API. For example, the
              `Class::forName` and `ResourceBundle::getBundle` methods use the
              immediate caller's class loader to load a class and a resource bundle
              respectively. Reflective APIs such as `Class::getMethod` use the
              immediate caller's class loader to determine the security checks to
              be performed.

            - Walk the stack, filtering out the stack frames of specific
              implementation classes to find the first non-filtered frame. The
              `java.util.logging` API, Log4j, and the Groovy runtime filter
              intermediate stack frames (typically implementation-specific and
              reflection frames) to find the caller's class.

            - Walk the stack to find all protection domains, until the first
              privileged frame is reached. This is required in order to do
              permission checks.

            - Walk the entire stack, possibly with a depth limit. This is required
              to generate the stack trace of any `Throwable` object, and to
              implement the `Thread::dumpStack` method.


          Description
          -----------

          This JEP will define a stack-walking API that allows laziness and frame
          filtering, supports short walks that stop at a frame matching given
          criteria, and also supports long walks that traverse the entire stack.

          The JVM will be enhanced to provide a flexible mechanism to traverse and
          materialize the required stack-frame information and allow efficient lazy
          access to additional stack frames when required. Native JVM transitions
          will be minimized. The implementation will need to have a stable view of
          a thread's stack: Returning a stream holding a stack pointer for further
          manipulation in an uncontrolled manner will not work since, as soon as
          the stream factory returns, the JVM will be free to reorganize the
          control stack (via deoptimization, for example). This will influence the
          API's definition.

          The API will specify its behavior when running with a security manager,
          so that access to the `Class` objects in stack frames do not compromise
          security.

          The proposal is to define a capability-based `StackWalker` API
          to traverse the stack. The security permission check will be performed
          on each `StackWalker` object when it is constructed rather than each time
          it is used. It will define the following methods:

              public <T> T walk(Function<Stream<StackFrame>, T> function);
              public Class<?> getCallerClass();

          The `walk` method opens a sequential stream of `StackFrame` for the current thread
          and then applies the function with the `StackFrame` stream.
          The spliterator of the stream performs the stack frame traversal in an ordered manner.
          The `Stream<StackFrame>` object can only be traversed once and will be closed
          when the `walk` method returns. The stream becomes invalid to use once it is closed.

          The `getCallerClass()` method is for convenience to find the caller's frame and is
          the replacement for `sun.reflect.Reflection.getCallerClass`.

          Alternatives
          ------------

          An alternative API choice would be the `walk` method to return `Stream<StackFrame>`.
          When a stream of stack frames is created, as soon as the stream factory returns,
          the JVM is free to reorganize the control stack (via deoptimization, for example).
          Returning `Stream<StackFrame>` will not work and the stream object may be used
          in an uncontrolled manner for further manipulation and there is no robust way to
          detect if the stack has been mutated.

          Instead, similar to `AccessController::doPrivileged`, at least one native method must be
          created which will establish its own stack frame and then provide controlled access
          to the JVM's stack walking logic, for older frames.
          When this native method returns, that capability must be deactivated, or else made inaccessible
          in some other way. In this way, we can do efficient lazy access to stack frames, on a stable view
          of the thread's own control stack.
          Summary
          -------

          Define an efficient standard API for stack walking that allows easy
          filtering of, and lazy access to, the information in stack traces.

          Non-Goal
          ---------

             - It is not a goal to convert all existing stack walking code in the JDK to use this new API.

          Motivation
          ----------

          There is no standard API to traverse selected frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are existing APIs that provide access to a thread's stack:

             - `Throwable::getStackTrace` and `Thread::getStackTrace` return an
               array of `StackTraceElement` objects, which contain the class name
               and method name of each stack-trace element.

             - `SecurityManager::getClassContext` is a protected method, which
               allows a `SecurityManager` subclass to access the class context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack, and they return information representing the entire stack. There
          is no way to avoid the cost of examining all the frames if the caller is
          only interested in the top few frames on the stack. Both the
          `Throwable::getStackTrace` and `Thread::getStackTrace` methods return an
          array of `StackTraceElement` objects, which contain class names and
          method names but not the actual `Class` instances. For applications
          interested in the entire stack, the specification allows the VM
          implementation to omit some frames in the stack for performance. In
          other words, `Thread::getStackTrace` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend upon the
          JDK-internal `sun.reflect.Reflection::getCallerClass` method, or else
          their performance overhead is intolerable. These use cases include:

            - Walk the stack until the immediate caller's class is found. Every
              JDK caller-sensitive API looks up its immediate caller's class in
              order to determine the behavior of the API. For example, the
              `Class::forName` and `ResourceBundle::getBundle` methods use the
              immediate caller's class loader to load a class and a resource bundle
              respectively. Reflective APIs such as `Class::getMethod` use the
              immediate caller's class loader to determine the security checks to
              be performed.

            - Walk the stack, filtering out the stack frames of specific
              implementation classes to find the first non-filtered frame. The
              `java.util.logging` API, Log4j, and the Groovy runtime filter
              intermediate stack frames (typically implementation-specific and
              reflection frames) to find the caller's class.

            - Walk the stack to find all protection domains, until the first
              privileged frame is reached. This is required in order to do
              permission checks.

            - Walk the entire stack, possibly with a depth limit. This is required
              to generate the stack trace of any `Throwable` object, and to
              implement the `Thread::dumpStack` method.


          Description
          -----------

          This JEP will define a stack-walking API that allows laziness and frame
          filtering, supports short walks that stop at a frame matching given
          criteria, and also supports long walks that traverse the entire stack.

          The JVM will be enhanced to provide a flexible mechanism to traverse and
          materialize the required stack-frame information and allow efficient lazy
          access to additional stack frames when required. Native JVM transitions
          will be minimized. The implementation will need to have a stable view of
          a thread's stack: Returning a stream holding a stack pointer for further
          manipulation in an uncontrolled manner will not work since, as soon as
          the stream factory returns, the JVM will be free to reorganize the
          control stack (via deoptimization, for example). This will influence the
          API's definition.

          The API will specify its behavior when running with a security manager,
          so that access to the `Class` objects in stack frames do not compromise
          security.

          The proposal is to define a capability-based `StackWalker` API
          to traverse the stack. The security permission check will be performed
          on each `StackWalker` object when it is constructed rather than each time
          it is used. It will define the following methods:

              public <T> T walk(Function<Stream<StackFrame>, T> function);
              public Class<?> getCallerClass();

          The `walk` method opens a sequential stream of `StackFrame` for the current thread
          and then applies the function with the `StackFrame` stream.
          The spliterator of the stream performs the stack frame traversal in an ordered manner.
          The `Stream<StackFrame>` object can only be traversed once and will be closed
          when the `walk` method returns. The stream becomes invalid to use once it is closed.

          The `getCallerClass()` method is for convenience to find the caller's frame and is
          the replacement for `sun.reflect.Reflection.getCallerClass`.

          Alternatives
          ------------

          An alternative API choice would be for the `walk` method to return `Stream<StackFrame>`
          but that will not work as the returned stream object may be used in an uncontrolled manner
          for further manipulation. When a stream of stack frames is created, as soon as
          the stream factory returns, the JVM is free to reorganize the control stack (via deoptimization, for example)
          and there is no robust way to detect if the stack has been mutated.

          Instead, similar to `AccessController::doPrivileged`, at least one native method must be
          created which will establish its own stack frame and then provide controlled access
          to the JVM's stack walking logic, for older frames.
          When this native method returns, that capability must be deactivated, or else made inaccessible
          in some other way. In this way, we can do efficient lazy access to stack frames, on a stable view
          of the thread's own control stack.
          mchung Mandy Chung made changes -
          Description Summary
          -------

          Define an efficient standard API for stack walking that allows easy
          filtering of, and lazy access to, the information in stack traces.

          Non-Goal
          ---------

             - It is not a goal to convert all existing stack walking code in the JDK to use this new API.

          Motivation
          ----------

          There is no standard API to traverse selected frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are existing APIs that provide access to a thread's stack:

             - `Throwable::getStackTrace` and `Thread::getStackTrace` return an
               array of `StackTraceElement` objects, which contain the class name
               and method name of each stack-trace element.

             - `SecurityManager::getClassContext` is a protected method, which
               allows a `SecurityManager` subclass to access the class context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack, and they return information representing the entire stack. There
          is no way to avoid the cost of examining all the frames if the caller is
          only interested in the top few frames on the stack. Both the
          `Throwable::getStackTrace` and `Thread::getStackTrace` methods return an
          array of `StackTraceElement` objects, which contain class names and
          method names but not the actual `Class` instances. For applications
          interested in the entire stack, the specification allows the VM
          implementation to omit some frames in the stack for performance. In
          other words, `Thread::getStackTrace` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend upon the
          JDK-internal `sun.reflect.Reflection::getCallerClass` method, or else
          their performance overhead is intolerable. These use cases include:

            - Walk the stack until the immediate caller's class is found. Every
              JDK caller-sensitive API looks up its immediate caller's class in
              order to determine the behavior of the API. For example, the
              `Class::forName` and `ResourceBundle::getBundle` methods use the
              immediate caller's class loader to load a class and a resource bundle
              respectively. Reflective APIs such as `Class::getMethod` use the
              immediate caller's class loader to determine the security checks to
              be performed.

            - Walk the stack, filtering out the stack frames of specific
              implementation classes to find the first non-filtered frame. The
              `java.util.logging` API, Log4j, and the Groovy runtime filter
              intermediate stack frames (typically implementation-specific and
              reflection frames) to find the caller's class.

            - Walk the stack to find all protection domains, until the first
              privileged frame is reached. This is required in order to do
              permission checks.

            - Walk the entire stack, possibly with a depth limit. This is required
              to generate the stack trace of any `Throwable` object, and to
              implement the `Thread::dumpStack` method.


          Description
          -----------

          This JEP will define a stack-walking API that allows laziness and frame
          filtering, supports short walks that stop at a frame matching given
          criteria, and also supports long walks that traverse the entire stack.

          The JVM will be enhanced to provide a flexible mechanism to traverse and
          materialize the required stack-frame information and allow efficient lazy
          access to additional stack frames when required. Native JVM transitions
          will be minimized. The implementation will need to have a stable view of
          a thread's stack: Returning a stream holding a stack pointer for further
          manipulation in an uncontrolled manner will not work since, as soon as
          the stream factory returns, the JVM will be free to reorganize the
          control stack (via deoptimization, for example). This will influence the
          API's definition.

          The API will specify its behavior when running with a security manager,
          so that access to the `Class` objects in stack frames do not compromise
          security.

          The proposal is to define a capability-based `StackWalker` API
          to traverse the stack. The security permission check will be performed
          on each `StackWalker` object when it is constructed rather than each time
          it is used. It will define the following methods:

              public <T> T walk(Function<Stream<StackFrame>, T> function);
              public Class<?> getCallerClass();

          The `walk` method opens a sequential stream of `StackFrame` for the current thread
          and then applies the function with the `StackFrame` stream.
          The spliterator of the stream performs the stack frame traversal in an ordered manner.
          The `Stream<StackFrame>` object can only be traversed once and will be closed
          when the `walk` method returns. The stream becomes invalid to use once it is closed.

          The `getCallerClass()` method is for convenience to find the caller's frame and is
          the replacement for `sun.reflect.Reflection.getCallerClass`.

          Alternatives
          ------------

          An alternative API choice would be for the `walk` method to return `Stream<StackFrame>`
          but that will not work as the returned stream object may be used in an uncontrolled manner
          for further manipulation. When a stream of stack frames is created, as soon as
          the stream factory returns, the JVM is free to reorganize the control stack (via deoptimization, for example)
          and there is no robust way to detect if the stack has been mutated.

          Instead, similar to `AccessController::doPrivileged`, at least one native method must be
          created which will establish its own stack frame and then provide controlled access
          to the JVM's stack walking logic, for older frames.
          When this native method returns, that capability must be deactivated, or else made inaccessible
          in some other way. In this way, we can do efficient lazy access to stack frames, on a stable view
          of the thread's own control stack.
          Summary
          -------

          Define an efficient standard API for stack walking that allows easy
          filtering of, and lazy access to, the information in stack traces.

          Non-Goal
          ---------

             - It is not a goal to convert all existing stack walking code in the JDK to use this new API.

          Motivation
          ----------

          There is no standard API to traverse selected frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are existing APIs that provide access to a thread's stack:

             - `Throwable::getStackTrace` and `Thread::getStackTrace` return an
               array of `StackTraceElement` objects, which contain the class name
               and method name of each stack-trace element.

             - `SecurityManager::getClassContext` is a protected method, which
               allows a `SecurityManager` subclass to access the class context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack, and they return information representing the entire stack. There
          is no way to avoid the cost of examining all the frames if the caller is
          only interested in the top few frames on the stack. Both the
          `Throwable::getStackTrace` and `Thread::getStackTrace` methods return an
          array of `StackTraceElement` objects, which contain class names and
          method names but not the actual `Class` instances. For applications
          interested in the entire stack, the specification allows the VM
          implementation to omit some frames in the stack for performance. In
          other words, `Thread::getStackTrace` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend upon the
          JDK-internal `sun.reflect.Reflection::getCallerClass` method, or else
          their performance overhead is intolerable. These use cases include:

            - Walk the stack until the immediate caller's class is found. Every
              JDK caller-sensitive API looks up its immediate caller's class in
              order to determine the behavior of the API. For example, the
              `Class::forName` and `ResourceBundle::getBundle` methods use the
              immediate caller's class loader to load a class and a resource bundle
              respectively. Reflective APIs such as `Class::getMethod` use the
              immediate caller's class loader to determine the security checks to
              be performed.

            - Walk the stack, filtering out the stack frames of specific
              implementation classes to find the first non-filtered frame. The
              `java.util.logging` API, Log4j, and the Groovy runtime filter
              intermediate stack frames (typically implementation-specific and
              reflection frames) to find the caller's class.

            - Walk the stack to find all protection domains, until the first
              privileged frame is reached. This is required in order to do
              permission checks.

            - Walk the entire stack, possibly with a depth limit. This is required
              to generate the stack trace of any `Throwable` object, and to
              implement the `Thread::dumpStack` method.


          Description
          -----------

          This JEP will define a stack-walking API that allows laziness and frame
          filtering, supports short walks that stop at a frame matching given
          criteria, and also supports long walks that traverse the entire stack.

          The JVM will be enhanced to provide a flexible mechanism to traverse and
          materialize the required stack-frame information and allow efficient lazy
          access to additional stack frames when required. Native JVM transitions
          will be minimized. The implementation will need to have a stable view of
          a thread's stack: Returning a stream holding a stack pointer for further
          manipulation in an uncontrolled manner will not work since, as soon as
          the stream factory returns, the JVM will be free to reorganize the
          control stack (via deoptimization, for example). This will influence the
          API's definition.

          The API will specify its behavior when running with a security manager,
          so that access to the `Class` objects in stack frames do not compromise
          security.

          The proposal is to define a capability-based `StackWalker` API
          to traverse the stack. The security permission check will be performed
          on each `StackWalker` object when it is constructed rather than each time
          it is used. It will define the following methods:

              public <T> T walk(Function<Stream<StackFrame>, T> function);
              public Class<?> getCallerClass();

          The `walk` method opens a sequential stream of `StackFrame` for the current thread
          and then applies the function with the `StackFrame` stream.
          The spliterator of the stream performs the stack frame traversal in an ordered manner.
          The `Stream<StackFrame>` object can only be traversed once and will be closed
          when the `walk` method returns. The stream becomes invalid to use once it is closed.

          The `getCallerClass()` method is for convenience to find the caller's frame and is
          the replacement for `sun.reflect.Reflection.getCallerClass`.

          Alternatives
          ------------

          An alternative API choice would be for the `walk` method to return `Stream<StackFrame>`.
          Such alternative will not work as the returned stream object may be used in an uncontrolled manner
          for further manipulation. When a stream of stack frames is created, as soon as
          the stream factory returns, the JVM is free to reorganize the control stack (via deoptimization, for example)
          and there is no robust way to detect if the stack has been mutated.

          Instead, similar to `AccessController::doPrivileged`, at least one native method must be
          created which will establish its own stack frame and then provide controlled access
          to the JVM's stack walking logic, for older frames.
          When this native method returns, that capability must be deactivated, or else made inaccessible
          in some other way. In this way, we can do efficient lazy access to stack frames, on a stable view
          of the thread's own control stack.
          mchung Mandy Chung made changes -
          Description Summary
          -------

          Define an efficient standard API for stack walking that allows easy
          filtering of, and lazy access to, the information in stack traces.

          Non-Goal
          ---------

             - It is not a goal to convert all existing stack walking code in the JDK to use this new API.

          Motivation
          ----------

          There is no standard API to traverse selected frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are existing APIs that provide access to a thread's stack:

             - `Throwable::getStackTrace` and `Thread::getStackTrace` return an
               array of `StackTraceElement` objects, which contain the class name
               and method name of each stack-trace element.

             - `SecurityManager::getClassContext` is a protected method, which
               allows a `SecurityManager` subclass to access the class context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack, and they return information representing the entire stack. There
          is no way to avoid the cost of examining all the frames if the caller is
          only interested in the top few frames on the stack. Both the
          `Throwable::getStackTrace` and `Thread::getStackTrace` methods return an
          array of `StackTraceElement` objects, which contain class names and
          method names but not the actual `Class` instances. For applications
          interested in the entire stack, the specification allows the VM
          implementation to omit some frames in the stack for performance. In
          other words, `Thread::getStackTrace` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend upon the
          JDK-internal `sun.reflect.Reflection::getCallerClass` method, or else
          their performance overhead is intolerable. These use cases include:

            - Walk the stack until the immediate caller's class is found. Every
              JDK caller-sensitive API looks up its immediate caller's class in
              order to determine the behavior of the API. For example, the
              `Class::forName` and `ResourceBundle::getBundle` methods use the
              immediate caller's class loader to load a class and a resource bundle
              respectively. Reflective APIs such as `Class::getMethod` use the
              immediate caller's class loader to determine the security checks to
              be performed.

            - Walk the stack, filtering out the stack frames of specific
              implementation classes to find the first non-filtered frame. The
              `java.util.logging` API, Log4j, and the Groovy runtime filter
              intermediate stack frames (typically implementation-specific and
              reflection frames) to find the caller's class.

            - Walk the stack to find all protection domains, until the first
              privileged frame is reached. This is required in order to do
              permission checks.

            - Walk the entire stack, possibly with a depth limit. This is required
              to generate the stack trace of any `Throwable` object, and to
              implement the `Thread::dumpStack` method.


          Description
          -----------

          This JEP will define a stack-walking API that allows laziness and frame
          filtering, supports short walks that stop at a frame matching given
          criteria, and also supports long walks that traverse the entire stack.

          The JVM will be enhanced to provide a flexible mechanism to traverse and
          materialize the required stack-frame information and allow efficient lazy
          access to additional stack frames when required. Native JVM transitions
          will be minimized. The implementation will need to have a stable view of
          a thread's stack: Returning a stream holding a stack pointer for further
          manipulation in an uncontrolled manner will not work since, as soon as
          the stream factory returns, the JVM will be free to reorganize the
          control stack (via deoptimization, for example). This will influence the
          API's definition.

          The API will specify its behavior when running with a security manager,
          so that access to the `Class` objects in stack frames do not compromise
          security.

          The proposal is to define a capability-based `StackWalker` API
          to traverse the stack. The security permission check will be performed
          on each `StackWalker` object when it is constructed rather than each time
          it is used. It will define the following methods:

              public <T> T walk(Function<Stream<StackFrame>, T> function);
              public Class<?> getCallerClass();

          The `walk` method opens a sequential stream of `StackFrame` for the current thread
          and then applies the function with the `StackFrame` stream.
          The spliterator of the stream performs the stack frame traversal in an ordered manner.
          The `Stream<StackFrame>` object can only be traversed once and will be closed
          when the `walk` method returns. The stream becomes invalid to use once it is closed.

          The `getCallerClass()` method is for convenience to find the caller's frame and is
          the replacement for `sun.reflect.Reflection.getCallerClass`.

          Alternatives
          ------------

          An alternative API choice would be for the `walk` method to return `Stream<StackFrame>`.
          Such alternative will not work as the returned stream object may be used in an uncontrolled manner
          for further manipulation. When a stream of stack frames is created, as soon as
          the stream factory returns, the JVM is free to reorganize the control stack (via deoptimization, for example)
          and there is no robust way to detect if the stack has been mutated.

          Instead, similar to `AccessController::doPrivileged`, at least one native method must be
          created which will establish its own stack frame and then provide controlled access
          to the JVM's stack walking logic, for older frames.
          When this native method returns, that capability must be deactivated, or else made inaccessible
          in some other way. In this way, we can do efficient lazy access to stack frames, on a stable view
          of the thread's own control stack.
          Summary
          -------

          Define an efficient standard API for stack walking that allows easy
          filtering of, and lazy access to, the information in stack traces.

          Non-Goal
          ---------

             - It is not a goal to convert all existing stack walking code in the JDK to use this new API.

          Motivation
          ----------

          There is no standard API to traverse selected frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are existing APIs that provide access to a thread's stack:

             - `Throwable::getStackTrace` and `Thread::getStackTrace` return an
               array of `StackTraceElement` objects, which contain the class name
               and method name of each stack-trace element.

             - `SecurityManager::getClassContext` is a protected method, which
               allows a `SecurityManager` subclass to access the class context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack, and they return information representing the entire stack. There
          is no way to avoid the cost of examining all the frames if the caller is
          only interested in the top few frames on the stack. Both the
          `Throwable::getStackTrace` and `Thread::getStackTrace` methods return an
          array of `StackTraceElement` objects, which contain class names and
          method names but not the actual `Class` instances. For applications
          interested in the entire stack, the specification allows the VM
          implementation to omit some frames in the stack for performance. In
          other words, `Thread::getStackTrace` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend upon the
          JDK-internal `sun.reflect.Reflection::getCallerClass` method, or else
          their performance overhead is intolerable. These use cases include:

            - Walk the stack until the immediate caller's class is found. Every
              JDK caller-sensitive API looks up its immediate caller's class in
              order to determine the behavior of the API. For example, the
              `Class::forName` and `ResourceBundle::getBundle` methods use the
              immediate caller's class loader to load a class and a resource bundle
              respectively. Reflective APIs such as `Class::getMethod` use the
              immediate caller's class loader to determine the security checks to
              be performed.

            - Walk the stack, filtering out the stack frames of specific
              implementation classes to find the first non-filtered frame. The
              `java.util.logging` API, Log4j, and the Groovy runtime filter
              intermediate stack frames (typically implementation-specific and
              reflection frames) to find the caller's class.

            - Walk the stack to find all protection domains, until the first
              privileged frame is reached. This is required in order to do
              permission checks.

            - Walk the entire stack, possibly with a depth limit. This is required
              to generate the stack trace of any `Throwable` object, and to
              implement the `Thread::dumpStack` method.


          Description
          -----------

          This JEP will define a stack-walking API that allows laziness and frame
          filtering, supports short walks that stop at a frame matching given
          criteria, and also supports long walks that traverse the entire stack.

          The JVM will be enhanced to provide a flexible mechanism to traverse and
          materialize the required stack-frame information and allow efficient lazy
          access to additional stack frames when required. Native JVM transitions
          will be minimized. The implementation will need to have a stable view of
          a thread's stack: Returning a stream holding a stack pointer for further
          manipulation in an uncontrolled manner will not work since, as soon as
          the stream factory returns, the JVM will be free to reorganize the
          control stack (via deoptimization, for example). This will influence the
          API's definition.

          The API will specify its behavior when running with a security manager,
          so that access to the `Class` objects in stack frames do not compromise
          security.

          The proposal is to define a capability-based `StackWalker` API
          to traverse the stack. The security permission check will be performed
          on each `StackWalker` object when it is constructed rather than each time
          it is used. It will define the following methods:

              public <T> T walk(Function<Stream<StackFrame>, T> function);
              public Class<?> getCallerClass();

          The `walk` method opens a sequential stream of `StackFrame` for the current thread
          and then applies the function with the `StackFrame` stream.
          The spliterator of the stream performs the stack frame traversal in an ordered manner.
          The `Stream<StackFrame>` object can only be traversed once and will be closed
          when the `walk` method returns. The stream becomes invalid to use once it is closed.

          The `getCallerClass()` method is for convenience to find the caller's frame and is
          the replacement for `sun.reflect.Reflection.getCallerClass`.

          Alternatives
          ------------

          An alternative API choice would be for the `walk` method to return `Stream<StackFrame>`.
          Such an alternative will not work as the returned stream object may be used in an uncontrolled manner
          for further manipulation. When a stream of stack frames is created, as soon as
          the stream factory returns, the JVM is free to reorganize the control stack (via deoptimization, for example)
          and there is no robust way to detect if the stack has been mutated.

          Instead, similar to `AccessController::doPrivileged`, at least one native method must be
          created which will establish its own stack frame and then provide controlled access
          to the JVM's stack walking logic, for older frames.
          When this native method returns, that capability must be deactivated, or else made inaccessible
          in some other way. In this way, we can do efficient lazy access to stack frames, on a stable view
          of the thread's own control stack.
          mchung Mandy Chung made changes -
          Description Summary
          -------

          Define an efficient standard API for stack walking that allows easy
          filtering of, and lazy access to, the information in stack traces.

          Non-Goal
          ---------

             - It is not a goal to convert all existing stack walking code in the JDK to use this new API.

          Motivation
          ----------

          There is no standard API to traverse selected frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are existing APIs that provide access to a thread's stack:

             - `Throwable::getStackTrace` and `Thread::getStackTrace` return an
               array of `StackTraceElement` objects, which contain the class name
               and method name of each stack-trace element.

             - `SecurityManager::getClassContext` is a protected method, which
               allows a `SecurityManager` subclass to access the class context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack, and they return information representing the entire stack. There
          is no way to avoid the cost of examining all the frames if the caller is
          only interested in the top few frames on the stack. Both the
          `Throwable::getStackTrace` and `Thread::getStackTrace` methods return an
          array of `StackTraceElement` objects, which contain class names and
          method names but not the actual `Class` instances. For applications
          interested in the entire stack, the specification allows the VM
          implementation to omit some frames in the stack for performance. In
          other words, `Thread::getStackTrace` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend upon the
          JDK-internal `sun.reflect.Reflection::getCallerClass` method, or else
          their performance overhead is intolerable. These use cases include:

            - Walk the stack until the immediate caller's class is found. Every
              JDK caller-sensitive API looks up its immediate caller's class in
              order to determine the behavior of the API. For example, the
              `Class::forName` and `ResourceBundle::getBundle` methods use the
              immediate caller's class loader to load a class and a resource bundle
              respectively. Reflective APIs such as `Class::getMethod` use the
              immediate caller's class loader to determine the security checks to
              be performed.

            - Walk the stack, filtering out the stack frames of specific
              implementation classes to find the first non-filtered frame. The
              `java.util.logging` API, Log4j, and the Groovy runtime filter
              intermediate stack frames (typically implementation-specific and
              reflection frames) to find the caller's class.

            - Walk the stack to find all protection domains, until the first
              privileged frame is reached. This is required in order to do
              permission checks.

            - Walk the entire stack, possibly with a depth limit. This is required
              to generate the stack trace of any `Throwable` object, and to
              implement the `Thread::dumpStack` method.


          Description
          -----------

          This JEP will define a stack-walking API that allows laziness and frame
          filtering, supports short walks that stop at a frame matching given
          criteria, and also supports long walks that traverse the entire stack.

          The JVM will be enhanced to provide a flexible mechanism to traverse and
          materialize the required stack-frame information and allow efficient lazy
          access to additional stack frames when required. Native JVM transitions
          will be minimized. The implementation will need to have a stable view of
          a thread's stack: Returning a stream holding a stack pointer for further
          manipulation in an uncontrolled manner will not work since, as soon as
          the stream factory returns, the JVM will be free to reorganize the
          control stack (via deoptimization, for example). This will influence the
          API's definition.

          The API will specify its behavior when running with a security manager,
          so that access to the `Class` objects in stack frames do not compromise
          security.

          The proposal is to define a capability-based `StackWalker` API
          to traverse the stack. The security permission check will be performed
          on each `StackWalker` object when it is constructed rather than each time
          it is used. It will define the following methods:

              public <T> T walk(Function<Stream<StackFrame>, T> function);
              public Class<?> getCallerClass();

          The `walk` method opens a sequential stream of `StackFrame` for the current thread
          and then applies the function with the `StackFrame` stream.
          The spliterator of the stream performs the stack frame traversal in an ordered manner.
          The `Stream<StackFrame>` object can only be traversed once and will be closed
          when the `walk` method returns. The stream becomes invalid to use once it is closed.

          The `getCallerClass()` method is for convenience to find the caller's frame and is
          the replacement for `sun.reflect.Reflection.getCallerClass`.

          Alternatives
          ------------

          An alternative API choice would be for the `walk` method to return `Stream<StackFrame>`.
          Such an alternative will not work as the returned stream object may be used in an uncontrolled manner
          for further manipulation. When a stream of stack frames is created, as soon as
          the stream factory returns, the JVM is free to reorganize the control stack (via deoptimization, for example)
          and there is no robust way to detect if the stack has been mutated.

          Instead, similar to `AccessController::doPrivileged`, at least one native method must be
          created which will establish its own stack frame and then provide controlled access
          to the JVM's stack walking logic, for older frames.
          When this native method returns, that capability must be deactivated, or else made inaccessible
          in some other way. In this way, we can do efficient lazy access to stack frames, on a stable view
          of the thread's own control stack.
          Summary
          -------

          Define an efficient standard API for stack walking that allows easy
          filtering of, and lazy access to, the information in stack traces.

          Non-Goal
          ---------

             - It is not a goal to convert all existing stack walking code in the JDK to use this new API.

          Motivation
          ----------

          There is no standard API to traverse selected frames on the execution
          stack efficiently and access the `Class` instance of each frame.

          There are existing APIs that provide access to a thread's stack:

             - `Throwable::getStackTrace` and `Thread::getStackTrace` return an
               array of `StackTraceElement` objects, which contain the class name
               and method name of each stack-trace element.

             - `SecurityManager::getClassContext` is a protected method, which
               allows a `SecurityManager` subclass to access the class context.

          These APIs require the VM to eagerly capture a snapshot of the entire
          stack, and they return information representing the entire stack. There
          is no way to avoid the cost of examining all the frames if the caller is
          only interested in the top few frames on the stack. Both the
          `Throwable::getStackTrace` and `Thread::getStackTrace` methods return an
          array of `StackTraceElement` objects, which contain class names and
          method names but not the actual `Class` instances. For applications
          interested in the entire stack, the specification allows the VM
          implementation to omit some frames in the stack for performance. In
          other words, `Thread::getStackTrace` may return a partial stack trace.

          These APIs do not satisfy the use cases that currently depend upon the
          JDK-internal `sun.reflect.Reflection::getCallerClass` method, or else
          their performance overhead is intolerable. These use cases include:

            - Walk the stack until the immediate caller's class is found. Every
              JDK caller-sensitive API looks up its immediate caller's class in
              order to determine the behavior of the API. For example, the
              `Class::forName` and `ResourceBundle::getBundle` methods use the
              immediate caller's class loader to load a class and a resource bundle
              respectively. Reflective APIs such as `Class::getMethod` use the
              immediate caller's class loader to determine the security checks to
              be performed.

            - Walk the stack, filtering out the stack frames of specific
              implementation classes to find the first non-filtered frame. The
              `java.util.logging` API, Log4j, and the Groovy runtime filter
              intermediate stack frames (typically implementation-specific and
              reflection frames) to find the caller's class.

            - Walk the stack to find all protection domains, until the first
              privileged frame is reached. This is required in order to do
              permission checks.

            - Walk the entire stack, possibly with a depth limit. This is required
              to generate the stack trace of any `Throwable` object, and to
              implement the `Thread::dumpStack` method.


          Description
          -----------

          This JEP will define a stack-walking API that allows laziness and frame
          filtering, supports short walks that stop at a frame matching given
          criteria, and also supports long walks that traverse the entire stack.

          The JVM will be enhanced to provide a flexible mechanism to traverse and
          materialize the required stack-frame information and allow efficient lazy
          access to additional stack frames when required. Native JVM transitions
          will be minimized. The implementation will need to have a stable view of
          a thread's stack: Returning a stream holding a stack pointer for further
          manipulation in an uncontrolled manner will not work since, as soon as
          the stream factory returns, the JVM will be free to reorganize the
          control stack (via deoptimization, for example). This will influence the
          API's definition.

          The API will specify its behavior when running with a security manager,
          so that access to the `Class` objects in stack frames do not compromise
          security.

          The proposal is to define a capability-based `StackWalker` API
          to traverse the stack. The security permission check will be performed
          on each `StackWalker` object when it is constructed rather than each time
          it is used. It will define the following methods:

              public <T> T walk(Function<Stream<StackFrame>, T> function);
              public Class<?> getCallerClass();

          The `walk` method opens a sequential stream of `StackFrame` for the current thread
          and then applies the function with the `StackFrame` stream.
          The spliterator of the stream performs the stack frame traversal in an ordered manner.
          The `Stream<StackFrame>` object can only be traversed once and will be closed
          when the `walk` method returns. The stream becomes invalid to use once it is closed.
          For example, to find the first caller filtering a known list of implementation class:

              Optional<Class<?>> frame = new StackWalker().walk((s) ->
              {
                  s.filter(f -> interestingClasses.contains(f.getDeclaringClass()))
                   .map(StackFrame::getDeclaringClass)
                   .findFirst();
              });

          To snapshot the stack trace of the current thread,

              List<StackFrame> stack =
                   new StackWalker().walk((s) -> s.collect(Collectors.toList()));

          The `getCallerClass()` method is for convenience to find the caller's frame and is
          the replacement for `sun.reflect.Reflection.getCallerClass`. An equivalent way to get the caller class using the `walk` method is:

              walk((s) -> s.map(StackFrame::declaringClass).skip(2).findFirst());

          Alternatives
          ------------

          An alternative API choice would be for the `walk` method to return `Stream<StackFrame>`.
          Such an alternative will not work as the returned stream object may be used in an uncontrolled manner
          for further manipulation. When a stream of stack frames is created, as soon as
          the stream factory returns, the JVM is free to reorganize the control stack (via deoptimization, for example)
          and there is no robust way to detect if the stack has been mutated.

          Instead, similar to `AccessController::doPrivileged`, at least one native method must be
          created which will establish its own stack frame and then provide controlled access
          to the JVM's stack walking logic, for older frames.
          When this native method returns, that capability must be deactivated, or else made inaccessible
          in some other way. In this way, we can do efficient lazy access to stack frames, on a stable view
          of the thread's own control stack.
          briangoetz Brian Goetz made changes -
          Endorsed By Brian Goetz [ briangoetz ]
          mchung Mandy Chung made changes -
          Status Candidate [ 10003 ] Proposed to Target [ 10004 ]
          mchung Mandy Chung made changes -
          Link This issue relates to JDK-8141239 [ JDK-8141239 ]
          mchung Mandy Chung made changes -
          Due Date 2015-11-27 2015-12-10
          mchung Mandy Chung made changes -
          Integration Due 2015-11-13 2015-12-04
          mr Mark Reinhold made changes -
          Labels a360_1190575 team-corelibs a360_1190575 jdk9-ptt-2015-11-05 team-corelibs
          mtrudeau Michel Trudeau made changes -
          Alert Status Green [ 1 ]
          mchung Mandy Chung made changes -
          Link This issue relates to JDK-8143259 [ JDK-8143259 ]
          mr Mark Reinhold made changes -
          Status Proposed to Target [ 10004 ] Targeted [ 10005 ]
          mchung Mandy Chung made changes -
          Integration Due 2015-12-04 2015-12-10
          Due Date 2015-12-10 2015-12-17
          mchung Mandy Chung made changes -
          Status Targeted [ 10005 ] Integrated [ 10007 ]
          dfuchs Daniel Fuchs made changes -
          Link This issue duplicates JDK-8145686 [ JDK-8145686 ]
          vlivanov Vladimir Ivanov made changes -
          Link This issue relates to JDK-6655643 [ JDK-6655643 ]
          rpallath Rajendrakumar Pallath made changes -
          Labels a360_1190575 jdk9-ptt-2015-11-05 team-corelibs a360_1190575 jdk9-ptt-2015-11-05 team-corelibs toi=yes
          mchung Mandy Chung made changes -
          Link This issue relates to JDK-8147039 [ JDK-8147039 ]
          bchristi Brent Christian made changes -
          Link This issue relates to JDK-8153123 [ JDK-8153123 ]
          jgodinez Jennifer Godinez (Inactive) made changes -
          Workflow JEP Workflow [ 4729847 ] JEP Workflow INFRA-2743 [ 4887562 ]
          jgodinez Jennifer Godinez (Inactive) made changes -
          Workflow JEP Workflow INFRA-2743 [ 4887562 ] JEP Workflow [ 4888311 ]
          mchung Mandy Chung made changes -
          Status Integrated [ 10007 ] Completed [ 10008 ]
          dbessono Dmitry Bessonov made changes -
          Link This issue relates to JCK-7306588 [ JCK-7306588 ]
          mchung Mandy Chung made changes -
          Resolution Delivered [ 17 ]
          Status Completed [ 10008 ] Closed [ 6 ]
          snikandrova Svetlana Nikandrova (Inactive) made changes -
          Labels a360_1190575 jdk9-ptt-2015-11-05 team-corelibs toi=yes a360_1190575 jdk9-ptt-2015-11-05 qa-toi=done team-corelibs toi=yes
          iris Iris Clark made changes -
          Scope JDK [ 19107 ] SE [ 19106 ]
          zmajo Zoltan Majo (Inactive) made changes -
          Link This issue duplicates JDK-6655643 [ JDK-6655643 ]
          ostuart Owen Stuart made changes -
          Link This issue relates to JDK-8176432 [ JDK-8176432 ]
          mchung Mandy Chung made changes -
          Labels a360_1190575 jdk9-ptt-2015-11-05 qa-toi=done team-corelibs toi=yes a360_1190575 jdk9-ptt-2015-11-05 jdkinternals qa-toi=done team-corelibs toi=yes
          ostuart Owen Stuart made changes -
          Link This issue relates to JDK-8176432 [ JDK-8176432 ]

            People

            • Assignee:
              mchung Mandy Chung
              Reporter:
              mchung Mandy Chung
              Owner:
              Mandy Chung
              Reviewed By:
              Brian Goetz, Mark Reinhold
              Endorsed By:
              Brian Goetz
            • Votes:
              0 Vote for this issue
              Watchers:
              17 Start watching this issue

              Dates

              • Due:
                Created:
                Updated:
                Resolved:
                Integration Due: