From 67766cd55c3a05f9888c8e2b9e34051a44b3e3fc Mon Sep 17 00:00:00 2001
From: Koichi Sasada <ko1@atdot.net>
Date: Fri, 25 Nov 2022 11:51:35 +0900
Subject: add debug context APIs for debuggers (frame depth)

The following new debug context APIs are for implementing debugger's
`next` (step over) and similar functionality.

* `rb_debug_inspector_frame_depth(dc, index)` returns `index`-th
  frame's depth.
* `rb_debug_inspector_current_depth()` returns current frame depth.

The frame depth is not related to the frame index because debug
context API skips some special frames but proposed `_depth()` APIs
returns the count of all frames (raw depth).
---
 include/ruby/debug.h | 35 +++++++++++++++++++++++++++++------
 1 file changed, 29 insertions(+), 6 deletions(-)

(limited to 'include')

diff --git a/include/ruby/debug.h b/include/ruby/debug.h
index c88da9c43d..f95acdb17e 100644
--- a/include/ruby/debug.h
+++ b/include/ruby/debug.h
@@ -206,6 +206,17 @@ typedef VALUE (*rb_debug_inspector_func_t)(const rb_debug_inspector_t *dc, void
  */
 VALUE rb_debug_inspector_open(rb_debug_inspector_func_t func, void *data);
 
+/**
+ * Queries  the backtrace  object  of the  context.   This is  as  if you  call
+ * `caller_locations` at the point of debugger.
+ *
+ * @param[in]  dc  A debug context.
+ * @return     An array  of `Thread::Backtrace::Location` which  represents the
+ *             current point of execution at `dc`.
+
+ */
+VALUE rb_debug_inspector_backtrace_locations(const rb_debug_inspector_t *dc);
+
 /**
  * Queries the current receiver of the passed context's upper frame.
  *
@@ -250,15 +261,27 @@ VALUE rb_debug_inspector_frame_binding_get(const rb_debug_inspector_t *dc, long
 VALUE rb_debug_inspector_frame_iseq_get(const rb_debug_inspector_t *dc, long index);
 
 /**
- * Queries  the backtrace  object  of the  context.   This is  as  if you  call
- * `caller_locations` at the point of debugger.
+ * Queries the depth of the passed context's upper frame.
  *
- * @param[in]  dc  A debug context.
- * @return     An array  of `Thread::Backtrace::Location` which  represents the
- *             current point of execution at `dc`.
+ * Note that the depth is not same as the frame index because debug_inspector
+ * skips some special frames but the depth counts all frames.
+ *
+ * @param[in]  dc           A debug context.
+ * @param[in]  index        Index of the frame from top to bottom.
+ * @exception  rb_eArgError `index` out of range.
+ * @retval     The depth at `index`-th frame in Integer.
+ */
+VALUE rb_debug_inspector_frame_depth(const rb_debug_inspector_t *dc, long index);
+
+// A macro to recognize `rb_debug_inspector_frame_depth()` is available or not
+#define RB_DEBUG_INSPECTOR_FRAME_DEPTH(dc, index) rb_debug_inspector_frame_depth(dc, index)
 
+/**
+ * Return current frmae depth.
+ *
+ * @retval     The depth of the current frame in Integer.
  */
-VALUE rb_debug_inspector_backtrace_locations(const rb_debug_inspector_t *dc);
+VALUE rb_debug_inspector_current_depth(void);
 
 /** @} */
 
-- 
cgit v1.2.1