ruby_memprofiler_pprof 0.0.3 → 0.0.4

data/ext/ruby_memprofiler_pprof_ext/vendor/backtracie/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