Add Thread.each_caller_location.

Author: itarato

CHANGELOG.md

@@ -24,6 +24,7 @@ Compatibility:
 * Add implementations of `rb_proc_call_with_block`, `rb_proc_call_kw`, `rb_proc_call_with_block_kw` and `rb_funcall_with_block_kw` (#3068, @andrykonchin).
 * Add optional `timeout` argument to `Thread::Queue#pop` (#3039, @itarato).
 * Add optional `timeout` argument to `Thread::SizedsQueue#pop` (#3039, @itarato).
+* Add `Thread.each_caller_location` (#3039, @itarato).
 
 Performance:
 

doc/user/compatibility.md

@@ -167,6 +167,15 @@ It is not recommended to use exceptions for control flow on any implementation o
 
 To help alleviate this problem, backtraces are automatically disabled in cases where we can detect that they will not be used.
 
+### Caller locations
+
+Using `Kernel#caller_locations` or `Thread.each_caller_location` might contain engine specific location objects and/or
+paths. This is expected and should be filtered in application code where necessary.
+
+The enumerator returned by `Thread.to_enum(:each_caller_location)` is not supporting iteration with `.next`. In CRuby
+this raises a `StopIteration`, while in TruffleRuby it iterates on an undetermined (related to where and how `.next` is
+called) call stack. It is not recommended to use this in any circumstance (neither CRuby nor TruffleRuby).
+
 ## C Extension Compatibility
 
 ### Identifiers may be macros or functions

spec/ruby/core/thread/each_caller_location_spec.rb

@@ -0,0 +1,49 @@
+require_relative '../../spec_helper'
+
+describe "Thread.each_caller_location" do
+  ruby_version_is "3.2" do
+    it "iterates through the current execution stack and matches caller_locations content and type" do
+      ScratchPad.record []
+      Thread.each_caller_location { |l| ScratchPad << l; }
+
+      ScratchPad.recorded.map(&:to_s).should == caller_locations.map(&:to_s)
+      ScratchPad.recorded[0].should be_kind_of(Thread::Backtrace::Location)
+    end
+
+    it "returns subset of 'Thread.to_enum(:each_caller_location)' locations" do
+      ar = []
+      ecl = Thread.each_caller_location { |x| ar << x }
+
+      (ar.map(&:to_s) - Thread.to_enum(:each_caller_location).to_a.map(&:to_s)).should.empty?
+    end
+
+    it "stops the backtrace iteration if 'break' occurs" do
+      i = 0
+      ar = []
+      ecl = Thread.each_caller_location do |x|
+        ar << x
+        i += 1
+        break x if i == 2
+      end
+
+      ar.map(&:to_s).should == caller_locations(1, 2).map(&:to_s)
+      ecl.should be_kind_of(Thread::Backtrace::Location)
+    end
+
+    it "returns nil" do
+      Thread.each_caller_location {}.should == nil
+    end
+
+    it "raises LocalJumpError when called without a block" do
+      -> {
+        Thread.each_caller_location
+      }.should raise_error(LocalJumpError, "no block given")
+    end
+
+    it "doesn't accept positional and keyword arguments" do
+      -> {
+        Thread.each_caller_location(12, foo: 10) {}
+      }.should raise_error(ArgumentError, "wrong number of arguments (given 2, expected 0)")
+    end
+  end
+end

spec/truffleruby.next-specs

@@ -29,3 +29,5 @@ spec/ruby/core/queue/shift_spec.rb
 spec/ruby/core/sizedqueue/deq_spec.rb
 spec/ruby/core/sizedqueue/pop_spec.rb
 spec/ruby/core/sizedqueue/shift_spec.rb
+
+spec/ruby/core/thread/each_caller_location_spec.rb

src/main/java/org/truffleruby/core/thread/ThreadBacktraceLocationNodes.java

@@ -38,9 +38,7 @@ private static SourceSection getAvailableSourceSection(RubyContext context,
         final Backtrace backtrace = threadBacktraceLocation.backtrace;
         final int activationIndex = threadBacktraceLocation.activationIndex;
 
-        return context
-                .getUserBacktraceFormatter()
-                .nextAvailableSourceSection(backtrace.getStackTrace(), activationIndex);
+        return BacktraceFormatter.nextAvailableSourceSection(backtrace.getStackTrace(), activationIndex);
     }
 
     @CoreMethod(names = "absolute_path")

src/main/java/org/truffleruby/core/thread/ThreadNodes.java

@@ -44,9 +44,12 @@
 import java.util.List;
 import java.util.concurrent.TimeUnit;
 
+import com.oracle.truffle.api.RootCallTarget;
 import com.oracle.truffle.api.TruffleContext;
 import com.oracle.truffle.api.TruffleSafepoint;
 import com.oracle.truffle.api.TruffleSafepoint.Interrupter;
+import com.oracle.truffle.api.TruffleStackTraceElement;
+import com.oracle.truffle.api.frame.FrameInstance;
 import com.oracle.truffle.api.frame.VirtualFrame;
 import com.oracle.truffle.api.profiles.InlinedBranchProfile;
 import com.oracle.truffle.api.profiles.InlinedConditionProfile;
@@ -93,6 +96,7 @@
 import org.truffleruby.language.arguments.ArgumentsDescriptor;
 import org.truffleruby.language.arguments.RubyArguments;
 import org.truffleruby.language.backtrace.Backtrace;
+import org.truffleruby.language.backtrace.BacktraceFormatter;
 import org.truffleruby.language.control.KillException;
 import org.truffleruby.language.control.RaiseException;
 import org.truffleruby.language.objects.AllocationTracing;
@@ -1035,4 +1039,59 @@ protected Object runBlockingSystemCall(Object executable, RubyArray argsArray,
             return foreignToRubyNode.executeConvert(result);
         }
     }
+
+    @CoreMethod(names = "each_caller_location", needsBlock = true, onSingleton = true)
+    public abstract static class EachCallerLocationNode extends CoreMethodArrayArgumentsNode {
+
+        private static final Object STOP_ITERATE = new Object();
+
+        // Skip the block of `Thread#each_caller_location` + its internal iteration.
+        private static final int SKIP = 2;
+
+        @Child private CallBlockNode yieldNode = CallBlockNode.create();
+
+        @Specialization
+        protected Object eachCallerLocation(VirtualFrame frame, RubyProc block) {
+            final List<TruffleStackTraceElement> stackTraceElements = new ArrayList<>();
+
+            getContext().getCallStack().iterateFrameBindings(SKIP, frameInstance -> {
+                final Node location = frameInstance.getCallNode();
+
+                final RootCallTarget rootCallTarget = (RootCallTarget) frameInstance.getCallTarget();
+                final TruffleStackTraceElement stackTraceElement = TruffleStackTraceElement.create(
+                        location,
+                        rootCallTarget,
+                        frameInstance.getFrame(FrameInstance.FrameAccess.READ_ONLY));
+                stackTraceElements.add(stackTraceElement);
+
+                final TruffleStackTraceElement[] finalStackTraceElements = stackTraceElements
+                        .toArray(TruffleStackTraceElement[]::new);
+                final boolean readyToYield = BacktraceFormatter.nextAvailableSourceSection(finalStackTraceElements,
+                        0) != null;
+
+                if (readyToYield) {
+                    for (int i = 0; i < finalStackTraceElements.length; i++) {
+                        final Backtrace backtrace = new Backtrace(location, 0, finalStackTraceElements);
+                        RubyBacktraceLocation rubyBacktraceLocation = new RubyBacktraceLocation(
+                                getContext().getCoreLibrary().threadBacktraceLocationClass,
+                                getLanguage().threadBacktraceLocationShape,
+                                backtrace,
+                                i);
+
+                        yieldNode.yield(block, rubyBacktraceLocation);
+                    }
+                    stackTraceElements.clear();
+                }
+
+                return null;
+            });
+
+            return nil;
+        }
+
+        @Specialization
+        protected Object eachCallerLocation(VirtualFrame frame, Nil block) {
+            throw new RaiseException(getContext(), coreExceptions().localJumpError("no block given", this));
+        }
+    }
 }

src/main/java/org/truffleruby/language/backtrace/Backtrace.java

@@ -87,6 +87,14 @@ public Backtrace(Node location, int omitted, Throwable javaThrowable) {
         this.javaThrowable = javaThrowable;
     }
 
+    /** For manually crafted backtraces. */
+    public Backtrace(Node location, int omitted, TruffleStackTraceElement[] stackTraceElements) {
+        this.location = location;
+        this.omitted = omitted;
+        this.javaThrowable = null;
+        this.stackTrace = stackTraceElements;
+    }
+
     /** Creates a backtrace for the given foreign exception, setting the {@link #getLocation() location} accordingly,
      * and computing the activations eagerly (since the exception itself is not retained). */
     public Backtrace(AbstractTruffleException exception) {

src/main/java/org/truffleruby/language/backtrace/BacktraceFormatter.java

@@ -337,7 +337,7 @@ private String formatException(RubyException exception) {
 
     /** This logic should be kept in sync with
      * {@link org.truffleruby.debug.TruffleDebugNodes.IterateFrameBindingsNode} */
-    public SourceSection nextAvailableSourceSection(TruffleStackTraceElement[] stackTrace, int n) {
+    public static SourceSection nextAvailableSourceSection(TruffleStackTraceElement[] stackTrace, int n) {
         while (n < stackTrace.length) {
             final Node callNode = stackTrace[n].getLocation();