backtracie 0.3.0 → 1.0.0

data/ext/backtracie_native_extension/backtracie_private.h

@@ -0,0 +1,20 @@
+#ifndef BACKTRACIE_PRIVATE_H
+#define BACKTRACIE_PRIVATE_H
+
+#include <ruby.h>
+#include <stdbool.h>
+
+// Need to define an assert macro - we might have just used RUBY_ASSERT, but
+// that's not exported in Ruby < 2.7.
+#define BACKTRACIE_ASSERT(expr) BACKTRACIE_ASSERT_MSG((expr), (#expr))
+#define BACKTRACIE_ASSERT_MSG(expr, msg)                                       \
+  do {                                                                         \
+    if ((expr) == 0) {                                                         \
+      rb_bug("backtracie gem: %s:%d: %s", __FILE__, __LINE__, msg);            \
+    }                                                                          \
+  } while (0)
+#define BACKTRACIE_ASSERT_FAIL(msg) BACKTRACIE_ASSERT_MSG(0, msg)
+
+bool backtracie_is_thread_alive(VALUE thread);
+void backtracie_init_c_test_helpers(VALUE backtracie_module);
+#endif

data/ext/backtracie_native_extension/c_test_helpers.c

@@ -0,0 +1,62 @@
+#include "backtracie_private.h"
+#include "public/backtracie.h"
+
+#include <ruby.h>
+#include <ruby/thread.h>
+
+static VALUE backtracie_backtrace_from_thread(VALUE self);
+static VALUE backtracie_backtrace_from_thread_cthread(void *ctx);
+static VALUE stdlib_backtrace_from_thread(VALUE self);
+static VALUE stdlib_backtrace_from_thread_cthread(void *ctx);
+static VALUE backtracie_backtrace_from_empty_thread(VALUE self);
+static VALUE backtracie_backtrace_from_empty_thread_cthread(void *ctx);
+
+void backtracie_init_c_test_helpers(VALUE backtracie_module) {
+  VALUE test_helpers_mod =
+      rb_define_module_under(backtracie_module, "TestHelpers");
+  rb_define_singleton_method(test_helpers_mod,
+                             "backtracie_backtrace_from_thread",
+                             backtracie_backtrace_from_thread, 0);
+  rb_define_singleton_method(test_helpers_mod, "stdlib_backtrace_from_thread",
+                             stdlib_backtrace_from_thread, 0);
+  rb_define_singleton_method(test_helpers_mod,
+                             "backtracie_backtrace_from_empty_thread",
+                             backtracie_backtrace_from_empty_thread, 0);
+}
+
+static VALUE backtracie_backtrace_from_thread(VALUE self) {
+  VALUE th = rb_thread_create(backtracie_backtrace_from_thread_cthread, NULL);
+  return rb_funcall(th, rb_intern("value"), 0);
+}
+
+static VALUE backtracie_backtrace_from_thread_cthread(void *ctx) {
+  VALUE backtracie_mod = rb_const_get(rb_cObject, rb_intern("Backtracie"));
+  return rb_funcall(backtracie_mod, rb_intern("backtrace_locations"), 1,
+                    rb_thread_current());
+}
+
+static VALUE stdlib_backtrace_from_thread(VALUE self) {
+  VALUE th = rb_thread_create(stdlib_backtrace_from_thread_cthread, NULL);
+  return rb_funcall(th, rb_intern("value"), 0);
+}
+
+static VALUE stdlib_backtrace_from_thread_cthread(void *ctx) {
+  return rb_funcall(rb_thread_current(), rb_intern("backtrace_locations"), 0);
+}
+
+static VALUE backtracie_backtrace_from_empty_thread(VALUE self) {
+  VALUE backtracie_mod = rb_const_get(rb_cObject, rb_intern("Backtracie"));
+  VALUE th =
+      rb_thread_create(backtracie_backtrace_from_empty_thread_cthread, NULL);
+  VALUE bt =
+      rb_funcall(backtracie_mod, rb_intern("backtrace_locations"), 1, th);
+  rb_thread_kill(th);
+  rb_funcall(th, rb_intern("join"), 0);
+  return bt;
+}
+
+static VALUE backtracie_backtrace_from_empty_thread_cthread(void *ctx) {
+  // yield the GVL without creating a frame of any kind
+  rb_thread_sleep(-1);
+  return Qnil;
+}

data/ext/backtracie_native_extension/extconf.rb

@@ -18,68 +18,62 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with backtracie.  If not, see <http://www.gnu.org/licenses/>.
 
-if ["jruby", "truffleruby"].include?(RUBY_ENGINE)
+if %w[jruby truffleruby].include?(RUBY_ENGINE)
   raise \
-    "\n#{"-" * 80}\nSorry! This gem is unsupported on #{RUBY_ENGINE}. Since it relies on a lot of guts of MRI Ruby, " \
+    "\n#{'-' * 80}\nSorry! This gem is unsupported on #{RUBY_ENGINE}. Since it relies on a lot of guts of MRI Ruby, " \
     "it's impossible to make a direct port.\n" \
-    "Perhaps a #{RUBY_ENGINE} equivalent could be created -- help is welcome! :)\n#{"-" * 80}"
+    "Perhaps a #{RUBY_ENGINE} equivalent could be created -- help is welcome! :)\n#{'-' * 80}"
 end
 
-require "mkmf"
+require 'mkmf'
 
 # This warning gets really annoying when we include the Ruby mjit header file,
 # let's omit it
-$CFLAGS << " " << "-Wno-unused-function"
+$CFLAGS << ' ' << '-Wno-unused-function'
 
 # Really dislike the "define everything at the beginning of the function" thing, sorry!
-$CFLAGS << " " << "-Wno-declaration-after-statement"
+$CFLAGS << ' ' << '-Wno-declaration-after-statement'
 
 # If we forget to include a Ruby header, the function call may still appear to work, but then
 # cause a segfault later. Let's ensure that never happens.
-$CFLAGS << " " << "-Werror-implicit-function-declaration"
+$CFLAGS << ' ' << '-Werror-implicit-function-declaration'
 
-# Enable us to use """modern""" C
-if RUBY_VERSION < "2.4"
-  $CFLAGS << " " << "-std=c99"
-end
+# Enable us to use """modern""" C. Note that Ruby requires GNU extensions; specifically,
+# NSIG is expected to be defined in signal.h.
+$CFLAGS << ' ' << '-std=gnu99' if RUBY_VERSION < '2.4'
 
-# On older Rubies, we need to enable a few backports. See cfunc_frames_backport.h for details.
-if RUBY_VERSION < "3"
-  $defs << "-DCFUNC_FRAMES_BACKPORT_NEEDED"
-end
+$CFLAGS << ' ' << '-DPRE_RB_ISEQ_TYPE' if RUBY_VERSION < '3.2'
 
-# Backport https://github.com/ruby/ruby/pull/3084 (present in 2.7 and 3.0) to Ruby <= 2.6
-if RUBY_VERSION.start_with?("2.6")
-  $defs << "-DCLASSPATH_BACKPORT_NEEDED"
-end
+$CFLAGS << ' ' << '-DPRE_GC_MARK_MOVABLE' if RUBY_VERSION < '2.7'
 
 # Older Rubies don't have the MJIT header, see below for details
-if RUBY_VERSION < "2.6"
-  $defs << "-DPRE_MJIT_RUBY"
-end
+$defs << '-DPRE_MJIT_RUBY' if RUBY_VERSION < '2.6'
 
-if RUBY_VERSION < "2.5"
-  $CFLAGS << " " << "-DPRE_EXECUTION_CONTEXT" # Flag that there's no execution context, we need to use threads instead
-  $CFLAGS << " " << "-Wno-attributes" # Silence a few warnings that we can't do anything about
+if RUBY_VERSION < '2.5'
+  $CFLAGS << ' ' << '-DPRE_EXECUTION_CONTEXT' # Flag that there's no execution context, we need to use threads instead
+  $CFLAGS << ' ' << '-DPRE_LOCATION_PATHOBJ'
+  $CFLAGS << ' ' << '-Wno-attributes' # Silence a few warnings that we can't do anything about
 end
 
-if RUBY_VERSION < "2.4"
-  $CFLAGS << " " << "-DPRE_VM_ENV_RENAMES" # Flag that it's a really old Ruby, and a few constants were since renamed
+if RUBY_VERSION < '2.4'
+  $CFLAGS << ' ' << '-DPRE_VM_ENV_RENAMES' # Flag that it's a really old Ruby, and a few constants were since renamed
 end
 
+$CFLAGS << ' ' << '-DBACKTRACIE_EXPORTS'
+append_cflags ['-fvisibility=hidden']
 create_header
 
-if RUBY_VERSION < "2.6"
+if RUBY_VERSION < '2.6'
   # Use the debase-ruby_core_source gem to get access to Ruby internal structures (no MJIT header -- the preferred
   # option -- is available for these older Rubies)
 
-  require "debase/ruby_core_source"
-  dir_config("ruby") # allow user to pass in non-standard core include directory
-  if !Debase::RubyCoreSource.create_makefile_with_core(
-    proc { ["vm_core.h", "method.h", "iseq.h", "regenc.h"].map { |it| have_header(it) }.uniq == [true] },
-    "backtracie_native_extension"
+  require 'debase/ruby_core_source'
+  dir_config('ruby') # allow user to pass in non-standard core include directory
+  unless Debase::RubyCoreSource.create_makefile_with_core(
+    proc { ['vm_core.h', 'method.h', 'iseq.h', 'regenc.h'].map { |it| have_header(it) }.uniq == [true] },
+    'backtracie_native_extension'
   )
-    raise "Error during native gem setup -- `Debase::RubyCoreSource.create_makefile_with_core` failed"
+    raise 'Error during native gem setup -- `Debase::RubyCoreSource.create_makefile_with_core` failed'
   end
 
 else
@@ -90,14 +84,14 @@ else
   # containing the exact file, so that it can be used in a #include in the C code.
   header_contents =
     File.read($extconf_h)
-      .sub("#endif",
-        <<~EXTCONF_H.strip
-          #define RUBY_MJIT_HEADER "rb_mjit_min_header-#{RUBY_VERSION}.h"
+        .sub('#endif',
+             <<~EXTCONF_H.strip
+               #define RUBY_MJIT_HEADER "rb_mjit_min_header-#{RUBY_VERSION}.h"
 
-          #endif
-        EXTCONF_H
-      )
-  File.open($extconf_h, "w") { |file| file.puts(header_contents) }
+               #endif
+             EXTCONF_H
+            )
+  File.open($extconf_h, 'w') { |file| file.puts(header_contents) }
 
-  create_makefile "backtracie_native_extension"
+  create_makefile 'backtracie_native_extension'
 end

data/ext/backtracie_native_extension/public/backtracie.h

@@ -0,0 +1,268 @@
+// 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/>.
+
+#ifndef BACKTRACIE_PUBLIC_H
+#define BACKTRACIE_PUBLIC_H
+
+#include <ruby.h>
+#include <stdbool.h>
+#include <stdint.h>
+
+// clang-format off
+#if defined(_WIN32) || defined(_WIN64)
+# ifdef BACKTRACIE_EXPORTS
+#   define BACKTRACIE_API __declspec(dllexport)
+# else
+#   define BACKTRACIE_API __declspec(dllimport)
+# endif
+#else
+# define BACKTRACIE_API __attribute__((visibility("default")))
+#endif
+// clang-format on
+
+typedef struct {
+  // The first element of this struct is a bitfield, comprised of uint32_t's.
+  // Ruby requires that VALUE be at least 32-bit but not necessarily 64-bit;
+  // using uint32_t for the bitfield ensures we have a minimum of pointless
+  // padding in this struct no matter the system.
+
+  // 1 -> ruby frame / 0 -> cfunc frame
+  uint32_t is_ruby_frame : 1;
+  // 1 means self really is the self object, 0 means it's the class of the self.
+  uint32_t self_is_real_self : 1;
+  // The iseq & cme; one, both, or neither might actually be available; if
+  // they're not, they will be Qnil. These need to be GC marked if you wish to
+  // keep the location alive.
+  VALUE iseq;
+  VALUE callable_method_entry;
+  // This is either self, or rb_class_of(self), depending on a few thing.
+  // It will be the actual self object for the frame if
+  //   - self is the toplevel binding,
+  //   - self is rb_mRubyVMFrozenCore,
+  //   - self is a class or module
+  // Otherwise, it will be rb_class_of(self).
+  // This is done so that, should the caller decide to retain the raw_location
+  // instance for a while, GC mark its VALUEs, and stringify the backtrace
+  // later, we both:
+  //   - retain enough information to actually produce a good name for the
+  //     method,
+  //   - but also don't hold onto random objects that would otherwise be GC'd
+  //     just because they happened to be in a backtrace.
+  // This needs to be marked if you wish to keep the location alive
+  VALUE self_or_self_class;
+  // Raw PC pointer; not much use to callers, but saved so we can calculate the
+  // lineno later on.
+  const void *pc;
+} raw_location;
+
+// Returns the number of Ruby frames currently live on the thread; this
+// can be used to judge how many times backtracie_capture_frame_for_thread()
+// should be called to capture the actual frames.
+BACKTRACIE_API int backtracie_frame_count_for_thread(VALUE thread);
+// Fills in the raw_location struct with the details of the Ruby call stack
+// frame on the given thread at the given index. The given index may or may not
+// refer to a "valid" frame on the ruby stack; there are some entries on the
+// Ruby stack which are not actually meaningful from a call-stack perspective.
+//
+// The maximum allowable value for i is
+// (backtracie_frame_count_for_thread(thread) - 1). Any value higher than this
+// will crash.
+
+// If the given index DOES refer to a valid frame on the Ruby stack:
+//   - *loc will be filled in with details of the frame,
+//   - the return value will be true
+// If the given index DOES NOT refer to a valid frame, then:
+//   - *loc will be totally untouched,
+//   - the return value will be false
+//
+// The intended usage of this API looks something like this:
+//
+//   VALUE thread = rb_thread_current();
+//   int max_frame_count = backtracie_frame_count_for_thread(thread);
+//   raw_location *locs = xcalloc(frame_count ,sizeof(raw_location));
+//   int frame_counter = 0;
+//   for (int i = 0; i < max_frame_count; i++) {
+//     bool is_valid = backtracie_capture_frame_for_thread(thread, i,
+//                                                         &locs[frame_counter]);
+//     if (is_valid) frame_counter++;
+//   }
+BACKTRACIE_API
+bool backtracie_capture_frame_for_thread(VALUE thread, int frame_index,
+                                         raw_location *loc);
+// Get the "qualified method name" for the frame. This is a string that best
+// describes what method is being called, intended for human interpretation.
+// Writes a NULL-term'd string of at most buflen chars (including NULL
+// terminator) to *buf. It returns the number of characters (NOT including NULL
+// terminator) that would be required to store the full string (which might be >
+// buflen, if it has been truncated). Essentially, has the same semantics as
+// snprintf or strlcat.
+BACKTRACIE_API
+size_t backtracie_frame_name_cstr(const raw_location *loc, char *buf,
+                                  size_t buflen);
+// Like backtracie_frame_name_cstr, but will allocate memory to ensure that
+// there is no truncation of the method name; returns a Ruby string.
+BACKTRACIE_API
+VALUE backtracie_frame_name_rbstr(const raw_location *loc);
+// Returns the filename of the source file for this backtrace location. Has the
+// same string handling semantics as backtracie_frame_name_cstr.
+//
+// Pass true/false for absolute to get the full, realpath vs just the path.
+//
+// If loc is a cfunc, and therefore has no filename, 0 is returned (and no
+// string is written to *buf)
+BACKTRACIE_API
+size_t backtracie_frame_filename_cstr(const raw_location *loc, bool absolute,
+                                      char *buf, size_t buflen);
+// Like backtracie_frame_filename_cstr, but returns a Ruby string. Will allocate
+// memory to ensure there is no truncation. Returns Qnil if there is no
+// filename.
+BACKTRACIE_API
+VALUE backtracie_frame_filename_rbstr(const raw_location *loc, bool absolute);
+
+// Returns the source line number of the given location, if it's a Ruby frame
+// (otherwise, returns 0).
+BACKTRACIE_API
+int backtracie_frame_line_number(const raw_location *loc);
+// Returns a string which would be like the "label" returned by
+// rb_profile_frames or Thread#backtrace or similar.
+BACKTRACIE_API
+size_t backtracie_frame_label_cstr(const raw_location *loc, bool base,
+                                   char *buf, size_t buflen);
+// Like backtracie_frame_label_cstr, but returns a ruby string.
+BACKTRACIE_API
+VALUE backtracie_frame_label_rbstr(const raw_location *loc, bool base);
+// Returns a VALUE that can be passed into the rb_profile_frames family of
+// methods
+BACKTRACIE_API
+VALUE backtracie_frame_for_rb_profile(const raw_location *loc);
+// Marks the contained ruby objects; for use when you want to persist the
+// raw_location object beyond the current call stack.
+BACKTRACIE_API
+void backtracie_frame_mark(const raw_location *loc);
+// Like backtracie_frame_mark, but calls rb_gc_mark_movable if available.
+BACKTRACIE_API
+void backtracie_frame_mark_movable(const raw_location *loc);
+// Updates *loc's VALUEs to point to possibly-moved locations
+BACKTRACIE_API
+void backtracie_frame_compact(raw_location *loc);
+
+// This is an optional facility to create a VALUE containing an array of
+// backtracie frames, which itself owns the process of marking them. When using
+// this, you need only mark the wrapper, and the wrapper will take care of
+// marking the individual frames. NOTE - if you keep a reference to this value
+// on the stack, you _probably_ need to use RB_GC_GUARD() on it, because the
+// Ruby GC cannot trace usage of the underlying pointer.
+BACKTRACIE_API
+VALUE backtracie_frame_wrapper_new(size_t capa);
+// Returns the underying array of frames for use
+BACKTRACIE_API
+raw_location *backtracie_frame_wrapper_frames(VALUE wrapper);
+// This returns a pointer to the len, so you can update the size of the
+// contained list of frames (up to capa)
+BACKTRACIE_API
+int *backtracie_frame_wrapper_len(VALUE wrapper);
+
+// ========= "Minimal" API ========
+// This part of the API defines a "minimal" version of raw_location, called
+// minimal_location_t. The problem this solves is that marking the iseq &
+// callable method entry stored on the raw_location struct can actually mark a
+// whole lot of memory, but only a small amount of those things are actually
+// needed to compute the method name.
+
+// These values define union descriminator values for minimal_location_t.
+// It's tempting to make this an enum, but apparently an enum in a bitfield is
+// implementation-defined behaviour.
+// It would also be tempting to define these as "const uint16_t", but the
+// ancient version of mingw used to build for Ruby 2.3 on Windows doesn't like
+// using such a constant in a switch statement somehow (??).
+// So... #define's it is.
+#define BACKTRACIE_METHOD_QUALIFIER_CONTENTS_SELF 0u
+#define BACKTRACIE_METHOD_QUALIFIER_CONTENTS_SELF_CLASS 1u
+#define BACKTRACIE_METHOD_QUALIFIER_CONTENTS_CME_CLASS 2u
+#define BACKTRACIE_METHOD_NAME_CONTENTS_CME_ID 0u
+#define BACKTRACIE_METHOD_NAME_CONTENTS_BASE_LABEL 1u
+
+typedef struct {
+  // 1 -> ruby frame / 0 -> cfunc frame
+  uint16_t is_ruby_frame : 1;
+  // What is in the method_qualifier field?
+  // 0 -> self
+  // 1 -> self_class
+  // 2 -> cme_defined_class
+  uint16_t method_qualifier_contents : 2;
+  // 0 -> cme_method_id
+  // 1 -> base_label
+  uint16_t method_name_contents : 1;
+  // 1 means iseq_type is populated
+  uint16_t has_iseq_type : 1;
+
+  // Comes from iseq->body->type; is an iseq_type enum.
+  // 5 bits is _way_ more than enough to store this enum.
+  uint16_t iseq_type : 5;
+
+  // We have six bits left over if someone can come up with a good use for them.
+  uint16_t reserved_bits : 6;
+
+  // Line number - we calculate this at capture time because it's fast, and it
+  // saves us from storing the iseq.
+  uint32_t line_number;
+
+  // Contains either the callable method entry ID or the iseq base label. The
+  // former if has_cme_method_id is set, the latter if not.
+  // If has_cme_method_id is set, this need not be marked, but if it is NOT set,
+  // then method_name.base_label needs to be marked.
+  union {
+    // Comes from callable_method_entry->called_id
+    ID cme_method_id;
+    // Comes from iseq->body->location.base_label
+    VALUE base_label;
+  } method_name;
+
+  // VALUE for the filename (abs), or Qnil
+  // Needs to be marked
+  VALUE filename;
+
+  // See method_qualifier_contents flag for possible values that can be in here.
+  // Needs to be marked
+  union {
+    VALUE self;              // the VALUE the method was called on
+    VALUE self_class;        // rb_class_of(the VALUE the method was called on)
+    VALUE cme_defined_class; // the class that the callable_method_entry is
+                             // defined on
+  } method_qualifier;
+} minimal_location_t;
+
+// This is like backtracie_capture_frame_for_thread, but captures a
+// minimal_location_t instead of a raw_location.
+BACKTRACIE_API
+bool backtracie_capture_minimal_frame_for_thread(VALUE thread, int frame_index,
+                                                 minimal_location_t *loc);
+
+// This is like backtracie_frame_name_cstr, but works on a minimal_location_t
+// instead of a raw_location
+BACKTRACIE_API
+size_t backtracie_minimal_frame_name_cstr(const minimal_location_t *loc,
+                                          char *buf, size_t buflen);
+
+// This is like backtracie_frame_filename_cstr, but works on a
+// minimal_location_t instead of a raw_location. Note that this always returns
+// the absolute filename.
+BACKTRACIE_API
+size_t backtracie_minimal_frame_filename_cstr(const minimal_location_t *loc,
+                                              char *buf, size_t buflen);
+#endif

data/ext/backtracie_native_extension/strbuilder.c

@@ -0,0 +1,123 @@
+#include <ruby.h>
+#include <stdarg.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+#include "backtracie_private.h"
+#include "strbuilder.h"
+
+void strbuilder_init(strbuilder_t *str, char *buf, size_t bufsize) {
+  str->original_buf = buf;
+  str->original_bufsize = bufsize;
+  str->curr_ptr = str->original_buf;
+  str->attempted_size = 0;
+  if (str->original_bufsize > 0) {
+    str->original_buf[0] = '\0';
+  }
+  str->growable = false;
+}
+
+void strbuilder_init_growable(strbuilder_t *str, size_t initial_bufsize) {
+  str->original_bufsize = initial_bufsize;
+  str->original_buf = malloc(str->original_bufsize);
+  str->curr_ptr = str->original_buf;
+  str->attempted_size = 0;
+  if (str->original_bufsize > 0) {
+    str->original_buf[0] = '\0';
+  }
+  str->growable = true;
+}
+
+void strbuilder_free_growable(strbuilder_t *str) {
+  BACKTRACIE_ASSERT(str->growable);
+  free(str->original_buf);
+}
+
+static void strbuilder_grow(strbuilder_t *str) {
+  ptrdiff_t offset = str->curr_ptr - str->original_buf;
+  str->original_bufsize = str->original_bufsize * 2;
+  str->original_buf = realloc(str->original_buf, str->original_bufsize);
+  str->curr_ptr = str->original_buf + offset;
+}
+
+void strbuilder_appendf(strbuilder_t *str, const char *fmt, ...) {
+  va_list fmtargs;
+  va_start(fmtargs, fmt);
+
+retry:;
+  // The size left in the buffer
+  size_t max_writesize =
+      str->original_bufsize - (str->curr_ptr - str->original_buf);
+  // vsnprintf returns the number of bytes it _would_ have written, not
+  // including the null terminator.
+  size_t attempted_writesize_wo_nullterm =
+      vsnprintf(str->curr_ptr, max_writesize, fmt, fmtargs);
+  if (attempted_writesize_wo_nullterm >= max_writesize) {
+    // Can we grow & retry?
+    if (str->growable) {
+      strbuilder_grow(str);
+      goto retry;
+    }
+    // If the string (including nullterm) would have exceeded the bufsize,
+    // point str->curr_ptr to one-past-the-end of the buffer.
+    // This will make subsequent calls to vsnprintf() receive zero for
+    // max_writesize, no further things can be appended to this buffer.
+    str->curr_ptr = str->original_buf + str->original_bufsize;
+  } else {
+    // If there's still room in the buffer, advance the curr_ptr.
+    str->curr_ptr = str->curr_ptr + attempted_writesize_wo_nullterm;
+  }
+  str->attempted_size += attempted_writesize_wo_nullterm;
+  va_end(fmtargs);
+}
+
+void strbuilder_append(strbuilder_t *str, const char *cat) {
+retry:;
+  size_t max_writesize =
+      str->original_bufsize - (str->curr_ptr - str->original_buf);
+  size_t attempted_writesize_wo_nullterm =
+      strlcat(str->curr_ptr, cat, max_writesize);
+  if (attempted_writesize_wo_nullterm >= max_writesize) {
+    if (str->growable) {
+      strbuilder_grow(str);
+      goto retry;
+    }
+    str->curr_ptr = str->original_buf + str->original_bufsize;
+  } else {
+    str->curr_ptr = str->curr_ptr + attempted_writesize_wo_nullterm;
+  }
+  str->attempted_size += attempted_writesize_wo_nullterm;
+}
+
+void strbuilder_append_value(strbuilder_t *str, VALUE val) {
+  BACKTRACIE_ASSERT(RB_TYPE_P(val, T_STRING));
+
+  const char *val_ptr = RSTRING_PTR(val);
+  size_t val_len = RSTRING_LEN(val);
+
+retry:;
+  size_t max_writesize =
+      str->original_bufsize - (str->curr_ptr - str->original_buf);
+  size_t chars_to_copy = val_len;
+  if (chars_to_copy + 1 > max_writesize) {
+    if (str->growable) {
+      strbuilder_grow(str);
+      goto retry;
+    }
+    chars_to_copy = max_writesize - 1; // leave room for NULL terminator.
+  }
+  memcpy(str->curr_ptr, val_ptr, chars_to_copy);
+  str->curr_ptr[chars_to_copy] = '\0';
+  str->attempted_size += val_len;
+  if (val_len + 1 > max_writesize) {
+    str->curr_ptr = str->original_buf + str->original_bufsize;
+  } else {
+    str->curr_ptr += val_len;
+  }
+
+  RB_GC_GUARD(val);
+}
+
+VALUE strbuilder_to_value(strbuilder_t *str) {
+  return rb_str_new2(str->original_buf);
+}

data/ext/backtracie_native_extension/strbuilder.h

@@ -0,0 +1,23 @@
+#ifndef STRBUILDER_H
+#define STRBUILDER_H
+
+#include <ruby.h>
+#include <stdbool.h>
+#include <stddef.h>
+
+typedef struct {
+  char *original_buf;
+  char *curr_ptr;
+  size_t original_bufsize;
+  size_t attempted_size;
+  bool growable;
+} strbuilder_t;
+
+void strbuilder_append(strbuilder_t *str, const char *cat);
+void strbuilder_appendf(strbuilder_t *str, const char *fmt, ...);
+void strbuilder_append_value(strbuilder_t *str, VALUE val);
+VALUE strbuilder_to_value(strbuilder_t *str);
+void strbuilder_init(strbuilder_t *str, char *buf, size_t bufsize);
+void strbuilder_init_growable(strbuilder_t *str, size_t initial_bufsize);
+void strbuilder_free_growable(strbuilder_t *str);
+#endif

data/lib/backtracie/location.rb

@@ -27,16 +27,21 @@ module Backtracie
     attr_accessor :lineno
     attr_accessor :path
     attr_accessor :qualified_method_name
+    attr_accessor :path_is_synthetic
 
     # Note: The order of arguments is hardcoded in the native extension in the `new_location` function --
     # keep them in sync
-    def initialize(absolute_path, base_label, label, lineno, path, qualified_method_name, debug)
+    def initialize(
+      absolute_path, base_label, label, lineno, path, qualified_method_name,
+      path_is_synthetic, debug
+    )
       @absolute_path = absolute_path
       @base_label = base_label
       @label = label
       @lineno = lineno
       @path = path
       @qualified_method_name = qualified_method_name
+      @path_is_synthetic = path_is_synthetic
       @debug = debug
 
       freeze

data/lib/backtracie/version.rb

@@ -19,5 +19,5 @@
 # along with backtracie.  If not, see <http://www.gnu.org/licenses/>.
 
 module Backtracie
-  VERSION = "0.3.0"
+  VERSION = "1.0.0"
 end