backtracie 0.1.0

data/README.adoc

@@ -0,0 +1,66 @@
+= `backtracie`
+:toc:
+:toc-placement: macro
+:toclevels: 4
+:toc-title:
+
+image:https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg["Contributor Covenant", link="CODE_OF_CONDUCT.adoc"]
+image:https://badge.fury.io/rb/backtracie.svg["Gem Version", link="https://badge.fury.io/rb/backtracie"]
+
+[discrete]
+== Contents
+
+toc::[]
+
+== Installation
+
+Add this line to your application's `gems.rb` or `Gemfile`:
+
+[source,ruby]
+----
+gem 'backtracie'
+----
+
+And then execute:
+
+[source,bash]
+----
+$ bundle install
+----
+
+Or install it yourself as:
+
+[source,bash]
+----
+$ gem install backtracie
+----
+
+This gem is versioned according to http://semver.org/spec/v2.0.0.html[Semantic Versioning].
+
+== Usage
+
+TODO
+
+== Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `rake spec` to run the tests.
+
+To open a console with the gem loaded, run `bundle console`.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to https://rubygems.org[rubygems.org].
+
+== Feedback and success stories
+
+Your feedback is welcome!
+
+== Contributing
+
+Bug reports and pull requests are welcome on GitLab at https://github.com/ivoanjo/backtracie.
+
+This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the http://contributor-covenant.org[Contributor Covenant] code of conduct.
+
+Maintained with ❤️ by https://ivoanjo.me/[Ivo Anjo].
+
+== Code of Conduct
+
+Everyone interacting in the backtracie project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the link:CODE_OF_CONDUCT.adoc[code of conduct].

data/Rakefile

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# backtracie: Ruby gem for beautiful backtraces
+# Copyright (C) 2021 Ivo Anjo <ivo@ivoanjo.me>
+#
+# This file is part of backtracie.
+#
+# backtracie is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# backtracie is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with backtracie.  If not, see <http://www.gnu.org/licenses/>.
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "standard/rake"
+require "rake/extensiontask"
+
+RSpec::Core::RakeTask.new(:spec)
+Rake::ExtensionTask.new("backtracie_native_extension")
+
+task default: [:compile, :spec, :'standard:fix']

data/backtracie.gemspec

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# backtracie: Ruby gem for beautiful backtraces
+# Copyright (C) 2021 Ivo Anjo <ivo@ivoanjo.me>
+#
+# This file is part of backtracie.
+#
+# backtracie is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# backtracie is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with backtracie.  If not, see <http://www.gnu.org/licenses/>.
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "backtracie/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "backtracie"
+  spec.version = Backtracie::VERSION
+  spec.authors = ["Ivo Anjo"]
+  spec.email = ["ivo@ivoanjo.me"]
+
+  spec.summary = "Ruby gem for beautiful backtraces"
+  spec.description = "Ruby gem for beautiful backtraces"
+  spec.homepage = "https://github.com/ivoanjo/backtracie"
+  spec.license = "LGPL-3.0+"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.require_paths = ["lib", "ext"]
+end

data/bin/console

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "backtracie"
+
+require "pry"
+Pry.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/ext/backtracie_native_extension/backtracie.c

@@ -0,0 +1,185 @@
+// backtracie: Ruby gem for beautiful backtraces
+// Copyright (C) 2021 Ivo Anjo <ivo@ivoanjo.me>
+//
+// This file is part of backtracie.
+//
+// backtracie is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// backtracie is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with backtracie.  If not, see <http://www.gnu.org/licenses/>.
+
+#include "ruby/ruby.h"
+#include "ruby/debug.h"
+
+#include "extconf.h"
+
+#include "ruby_3.0.0.h"
+
+// Constants
+
+#define MAX_STACK_DEPTH 2000 // FIXME: Need to handle when this is not enough
+
+// Globals
+
+static VALUE backtracie_module = Qnil;
+static VALUE backtracie_location_class = Qnil;
+
+// Function headers
+
+static VALUE primitive_caller_locations(VALUE self);
+static VALUE primitive_backtrace_locations(VALUE self, VALUE thread);
+static VALUE caller_locations(VALUE self, VALUE thread, int ignored_stack_top_frames);
+inline static VALUE new_location(VALUE absolute_path, VALUE base_label, VALUE label, VALUE lineno, VALUE path, VALUE debug);
+static bool is_ruby_frame(VALUE ruby_frame);
+static VALUE ruby_frame_to_location(VALUE frame, VALUE last_ruby_line, VALUE correct_label);
+static VALUE cfunc_frame_to_location(VALUE frame, VALUE last_ruby_frame, VALUE last_ruby_line);
+static VALUE debug_frame(VALUE frame, VALUE type);
+
+// Macros
+
+#define VALUE_COUNT(array) (sizeof(array) / sizeof(VALUE))
+
+void Init_backtracie_native_extension(void) {
+  backtracie_module = rb_const_get(rb_cObject, rb_intern("Backtracie"));
+  rb_global_variable(&backtracie_module);
+
+  rb_define_module_function(backtracie_module, "backtrace_locations", primitive_backtrace_locations, 1);
+
+  // We need to keep a reference to Backtracie::Locations around, to create new instances
+  backtracie_location_class = rb_const_get(backtracie_module, rb_intern("Location"));
+  rb_global_variable(&backtracie_location_class);
+
+  VALUE backtracie_primitive_module = rb_define_module_under(backtracie_module, "Primitive");
+
+  rb_define_module_function(backtracie_primitive_module, "caller_locations", primitive_caller_locations, 0);
+}
+
+// Get array of Backtracie::Locations for a given thread; if thread is nil, returns for the current thread
+static VALUE caller_locations(VALUE self, VALUE thread, int ignored_stack_top_frames) {
+  int stack_depth = 0;
+  VALUE frames[MAX_STACK_DEPTH];
+  VALUE correct_labels[MAX_STACK_DEPTH];
+  int lines[MAX_STACK_DEPTH];
+
+  if (thread == Qnil) {
+    // Get for own thread
+    stack_depth = modified_rb_profile_frames(0, MAX_STACK_DEPTH, frames, correct_labels, lines);
+  } else {
+    stack_depth = modified_rb_profile_frames_for_thread(thread, 0, MAX_STACK_DEPTH, frames, correct_labels, lines);
+  }
+
+  // Ignore the last frame -- seems to be an uninteresting VM frame. MRI itself seems to ignore the last frame in
+  // the implementation of backtrace_collect()
+  int ignored_stack_bottom_frames = 1;
+
+  stack_depth -= ignored_stack_bottom_frames;
+
+  VALUE locations = rb_ary_new_capa(stack_depth - ignored_stack_top_frames);
+
+  // MRI does not give us the path or line number for frames implemented using C code. The convention in
+  // Kernel#caller_locations is to instead use the path and line number of the last Ruby frame seen.
+  // Thus, we keep that frame here to able to replicate that behavior.
+  // (This is why we also iterate the frames array backwards below -- so that it's easier to keep the last_ruby_frame)
+  VALUE last_ruby_frame = Qnil;
+  VALUE last_ruby_line = Qnil;
+
+  for (int i = stack_depth - 1; i >= ignored_stack_top_frames; i--) {
+    VALUE frame = frames[i];
+    int line = lines[i];
+
+    VALUE location = Qnil;
+
+    if (is_ruby_frame(frame)) {
+      last_ruby_frame = frame;
+      last_ruby_line = INT2FIX(line);
+
+      location = ruby_frame_to_location(frame, last_ruby_line, correct_labels[i]);
+    } else {
+      location = cfunc_frame_to_location(frame, last_ruby_frame, last_ruby_line);
+    }
+
+    rb_ary_store(locations, i - ignored_stack_top_frames, location);
+  }
+
+  return locations;
+}
+
+static VALUE primitive_caller_locations(VALUE self) {
+  // Ignore:
+  // * the current stack frame (native)
+  // * the Backtracie.caller_locations that called us
+  // * the frame from the caller itself (since we're replicating the semantics of Kernel#caller_locations)
+  int ignored_stack_top_frames = 3;
+
+  return caller_locations(self, Qnil, ignored_stack_top_frames);
+}
+
+static VALUE primitive_backtrace_locations(VALUE self, VALUE thread) {
+  rb_funcall(backtracie_module, rb_intern("ensure_object_is_thread"), 1, thread);
+
+  int ignored_stack_top_frames = 0;
+
+  return caller_locations(self, thread, ignored_stack_top_frames);
+}
+
+inline static VALUE new_location(VALUE absolute_path, VALUE base_label, VALUE label, VALUE lineno, VALUE path, VALUE debug) {
+  VALUE arguments[] = { absolute_path, base_label, label, lineno, path, debug };
+  return rb_class_new_instance(VALUE_COUNT(arguments), arguments, backtracie_location_class);
+}
+
+static bool is_ruby_frame(VALUE frame) {
+  VALUE absolute_path = rb_profile_frame_absolute_path(frame);
+
+  return (rb_profile_frame_path(frame) != Qnil || absolute_path != Qnil) &&
+    (rb_funcall(absolute_path, rb_intern("=="), 1, rb_str_new2("<cfunc>")) == Qfalse);
+}
+
+static VALUE ruby_frame_to_location(VALUE frame, VALUE last_ruby_line, VALUE correct_label) {
+  return new_location(
+    rb_profile_frame_absolute_path(frame),
+    rb_profile_frame_base_label(frame),
+    rb_profile_frame_label(correct_label),
+    last_ruby_line,
+    rb_profile_frame_path(frame),
+    debug_frame(frame, rb_str_new2("ruby_frame"))
+  );
+}
+
+static VALUE cfunc_frame_to_location(VALUE frame, VALUE last_ruby_frame, VALUE last_ruby_line) {
+  VALUE method_name = rb_profile_frame_method_name(frame); // Replaces label and base_label in cfuncs
+
+  return new_location(
+    last_ruby_frame != Qnil ? rb_profile_frame_absolute_path(last_ruby_frame) : Qnil,
+    method_name,
+    method_name,
+    last_ruby_line,
+    last_ruby_frame != Qnil ? rb_profile_frame_path(last_ruby_frame) : Qnil,
+    debug_frame(frame, rb_str_new2("cfunc_frame"))
+  );
+}
+
+// Used to dump all the things we get from the rb_profile_frames API, for debugging
+static VALUE debug_frame(VALUE frame, VALUE type) {
+  VALUE arguments[] = {
+    rb_profile_frame_path(frame),
+    rb_profile_frame_absolute_path(frame),
+    rb_profile_frame_label(frame),
+    rb_profile_frame_base_label(frame),
+    rb_profile_frame_full_label(frame),
+    rb_profile_frame_first_lineno(frame),
+    rb_profile_frame_classpath(frame),
+    rb_profile_frame_singleton_method_p(frame),
+    rb_profile_frame_method_name(frame),
+    rb_profile_frame_qualified_method_name(frame),
+    type
+  };
+  return rb_ary_new_from_values(VALUE_COUNT(arguments), arguments);
+}

data/ext/backtracie_native_extension/extconf.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# backtracie: Ruby gem for beautiful backtraces
+# Copyright (C) 2021 Ivo Anjo <ivo@ivoanjo.me>
+#
+# This file is part of backtracie.
+#
+# backtracie is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# backtracie is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with backtracie.  If not, see <http://www.gnu.org/licenses/>.
+
+require "mkmf"
+
+# This warning gets really annoying when we include the Ruby mjit header file,
+# let's omit it
+$CFLAGS << " " << "-Wno-unused-function"
+
+create_header
+create_makefile "backtracie_native_extension"

data/ext/backtracie_native_extension/ruby_3.0.0.c

@@ -0,0 +1,196 @@
+// backtracie: Ruby gem for beautiful backtraces
+// Copyright (C) 2021 Ivo Anjo <ivo@ivoanjo.me>
+//
+// This file is part of backtracie.
+//
+// backtracie is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// backtracie is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License
+// along with backtracie.  If not, see <http://www.gnu.org/licenses/>.
+
+// -----------------------------------------------------------------------------
+// The file below has modified versions of code extracted from the Ruby project.
+// The Ruby project copyright and license follow:
+// -----------------------------------------------------------------------------
+
+// Ruby is copyrighted free software by Yukihiro Matsumoto <matz@netlab.jp>.
+// You can redistribute it and/or modify it under either the terms of the
+// 2-clause BSDL (see the file BSDL), or the conditions below:
+
+// 1. You may make and give away verbatim copies of the source form of the
+//    software without restriction, provided that you duplicate all of the
+//    original copyright notices and associated disclaimers.
+
+// 2. You may modify your copy of the software in any way, provided that
+//    you do at least ONE of the following:
+
+//    a. place your modifications in the Public Domain or otherwise
+//       make them Freely Available, such as by posting said
+//       modifications to Usenet or an equivalent medium, or by allowing
+//       the author to include your modifications in the software.
+
+//    b. use the modified software only within your corporation or
+//       organization.
+
+//    c. give non-standard binaries non-standard names, with
+//       instructions on where to get the original software distribution.
+
+//    d. make other distribution arrangements with the author.
+
+// 3. You may distribute the software in object code or binary form,
+//    provided that you do at least ONE of the following:
+
+//    a. distribute the binaries and library files of the software,
+//       together with instructions (in the manual page or equivalent)
+//       on where to get the original distribution.
+
+//    b. accompany the distribution with the machine-readable source of
+//       the software.
+
+//    c. give non-standard binaries non-standard names, with
+//       instructions on where to get the original software distribution.
+
+//    d. make other distribution arrangements with the author.
+
+// 4. You may modify and include the part of the software into any other
+//    software (possibly commercial).  But some files in the distribution
+//    are not written by the author, so that they are not under these terms.
+
+//    For the list of those files and their copying conditions, see the
+//    file LEGAL.
+
+// 5. The scripts and library files supplied as input to or produced as
+//    output from the software do not automatically fall under the
+//    copyright of the software, but belong to whomever generated them,
+//    and may be sold commercially, and may be aggregated with this
+//    software.
+
+// 6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+//    IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+//    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+//    PURPOSE.
+
+#include "rb_mjit_min_header-3.0.0.h"
+
+#include "ruby_3.0.0.h"
+
+/**********************************************************************
+
+  vm_backtrace.c -
+
+  $Author: ko1 $
+  created at: Sun Jun 03 00:14:20 2012
+
+  Copyright (C) 1993-2012 Yukihiro Matsumoto
+
+**********************************************************************/
+
+inline static int
+calc_lineno(const rb_iseq_t *iseq, const VALUE *pc)
+{
+    VM_ASSERT(iseq);
+    VM_ASSERT(iseq->body);
+    VM_ASSERT(iseq->body->iseq_encoded);
+    VM_ASSERT(iseq->body->iseq_size);
+    if (! pc) {
+        /* This can happen during VM bootup. */
+        VM_ASSERT(iseq->body->type == ISEQ_TYPE_TOP);
+        VM_ASSERT(! iseq->body->local_table);
+        VM_ASSERT(! iseq->body->local_table_size);
+        return 0;
+    }
+    else {
+        ptrdiff_t n = pc - iseq->body->iseq_encoded;
+        VM_ASSERT(n <= iseq->body->iseq_size);
+        VM_ASSERT(n >= 0);
+        ASSUME(n >= 0);
+        size_t pos = n; /* no overflow */
+        if (LIKELY(pos)) {
+            /* use pos-1 because PC points next instruction at the beginning of instruction */
+            pos--;
+        }
+#if VMDEBUG && defined(HAVE_BUILTIN___BUILTIN_TRAP)
+        else {
+            /* SDR() is not possible; that causes infinite loop. */
+            rb_print_backtrace();
+            __builtin_trap();
+        }
+#endif
+        return rb_iseq_line_no(iseq, pos);
+    }
+}
+
+int modified_rb_profile_frames_for_execution_context(
+  rb_execution_context_t *ec,
+  int start,
+  int limit,
+  VALUE *buff,
+  VALUE *correct_labels,
+  int *lines
+) {
+    int i;
+    const rb_control_frame_t *cfp = ec->cfp, *end_cfp = RUBY_VM_END_CONTROL_FRAME(ec);
+    const rb_callable_method_entry_t *cme;
+
+    for (i=0; i<limit && cfp != end_cfp;) {
+        if (VM_FRAME_RUBYFRAME_P(cfp)) {
+            if (start > 0) {
+                start--;
+                continue;
+            }
+
+            // Stash the iseq so we can use it for the label. Otherwise ./spec/unit/backtracie_spec.rb:53 used to fail with
+            //   expected: "block (3 levels) in fetch_or_store"
+            //   got: "fetch_or_store"
+            // ...but works with this hack.
+            correct_labels[i] = (VALUE) cfp->iseq;
+
+            /* record frame info */
+            cme = rb_vm_frame_method_entry(cfp);
+            if (cme && cme->def->type == VM_METHOD_TYPE_ISEQ) {
+                buff[i] = (VALUE)cme;
+            }
+            else {
+                buff[i] = (VALUE)cfp->iseq;
+            }
+
+            if (lines) lines[i] = calc_lineno(cfp->iseq, cfp->pc);
+
+            i++;
+        }
+        else {
+            cme = rb_vm_frame_method_entry(cfp);
+            if (cme && cme->def->type == VM_METHOD_TYPE_CFUNC) {
+                buff[i] = (VALUE)cme;
+                if (lines) lines[i] = 0;
+                i++;
+            }
+        }
+
+        cfp = RUBY_VM_PREVIOUS_CONTROL_FRAME(cfp);
+    }
+
+    return i;
+}
+
+int modified_rb_profile_frames(int start, int limit, VALUE *buff, VALUE *correct_labels, int *lines) {
+  return modified_rb_profile_frames_for_execution_context(GET_EC(), start, limit, buff, correct_labels, lines);
+}
+
+int modified_rb_profile_frames_for_thread(VALUE thread, int start, int limit, VALUE *buff, VALUE *correct_labels, int *lines) {
+  // In here we're assuming that what we got is really a Thread or its subclass. This assumption NEEDS to be verified by
+  // the caller, otherwise I see a segfault in your future.
+  rb_thread_t *thread_pointer = (rb_thread_t*) DATA_PTR(thread);
+
+  if (thread_pointer->to_kill || thread_pointer->status == THREAD_KILLED) return Qnil;
+
+  return modified_rb_profile_frames_for_execution_context(thread_pointer->ec, start, limit, buff, correct_labels, lines);
+}