Implement jerry_get_backtrace_from API function (#4454)

JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com
2021-01-12 19:52:05 +01:00
parent c46f4c3e40
commit 3193e6d0dc
7 changed files with 313 additions and 6 deletions
@@ -8876,6 +8876,7 @@ backtrace_handler (const jerry_value_t function_obj,
  if (!jerry_is_feature_enabled (JERRY_FEATURE_LINE_INFO))
  {
    printf ("Line info disabled, no backtrace will be printed\n");
+    return jerry_create_undefined ();
  }

  /* If the line info feature is disabled an empty array will be returned. */
@@ -8948,9 +8949,146 @@ main (void)

 **See also**

+- [jerry_get_backtrace_from](#jerry_get_backtrace_from)
 - [jerry_create_external_function](#jerry_create_external_function)


+## jerry_get_backtrace_from
+
+**Summary**
+
+Get backtrace. The backtrace is an array of strings where
+each string contains the position of the corresponding frame.
+The array length is zero if the backtrace is not available.
+
+Collecting the trace starts after the function specified in
+the `ignored_function` parameter. This parameter can be used to
+skip the helper function(s) which collects the backtrace from
+the backtrace data.
+
+*Notes*:
+- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+is no longer needed.
+- This feature depends on build option (`JERRY_LINE_INFO`) and can be checked
+  in runtime with the `JERRY_FEATURE_LINE_INFO` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_get_backtrace_from (uint32_t max_depth, jerry_value_t ignored_function);
+```
+
+- `max_depth` - backtrace collection stops after reaching this value, 0 = unlimited
+- `ignored_function` - if this function is present in the backtrace, the backtrace
+                       only contains the stack frames after the topmost instance of
+                       this function. Otherwise this parameter is ignored
+- return value
+  - a newly constructed JS array
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # (name="02.API-REFERENCE-jsbacktracefrom.c")
+
+```c
+#include <stdio.h>
+#include <string.h>
+#include "jerryscript.h"
+
+static jerry_value_t
+backtrace_handler (const jerry_value_t function_obj,
+                   const jerry_value_t this_val,
+                   const jerry_value_t args_p[],
+                   const jerry_length_t args_count)
+{
+  if (!jerry_is_feature_enabled (JERRY_FEATURE_LINE_INFO))
+  {
+    printf ("Line info disabled, no backtrace will be printed\n");
+    return jerry_create_undefined ();
+  }
+
+  if (args_count < 1)
+  {
+    printf ("Ignored function is not specified\n");
+    return jerry_create_undefined ();
+  }
+
+  /* If the line info feature is disabled an empty array will be returned. */
+  jerry_value_t backtrace_array = jerry_get_backtrace_from (0, args_p[0]);
+  uint32_t array_length = jerry_get_array_length (backtrace_array);
+
+  for (uint32_t idx = 0; idx < array_length; idx++)
+  {
+    jerry_value_t property = jerry_get_property_by_index (backtrace_array, idx);
+
+    jerry_char_t string_buffer[64];
+    jerry_size_t copied_bytes = jerry_substring_to_char_buffer (property,
+                                                                0,
+                                                                63,
+                                                                string_buffer,
+                                                                63);
+    string_buffer[copied_bytes] = '\0';
+    printf(" %d: %s\n", idx, string_buffer);
+
+    jerry_release_value (property);
+  }
+
+  jerry_release_value (backtrace_array);
+
+  return jerry_create_undefined ();
+} /* backtrace_handler */
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerry_value_t global = jerry_get_global_object ();
+
+  /* Register the "dump_backtrace" method. */
+  {
+    jerry_value_t func = jerry_create_external_function (backtrace_handler);
+    jerry_value_t name = jerry_create_string ((const jerry_char_t *) "backtrace");
+    jerry_value_t result = jerry_set_property (global, name, func);
+    jerry_release_value (result);
+    jerry_release_value (name);
+    jerry_release_value (func);
+  }
+
+  jerry_release_value (global);
+
+  const char *source = ("function f() { g (); }\n"
+                        "function g() { h (); }\n"
+                        "function h() { backtrace (g); }\n"
+                        "f ();\n");
+  const char *resource = "demo_memoryjs";
+
+  jerry_value_t program = jerry_parse ((const jerry_char_t *) resource,
+                                       strlen (resource),
+                                       (const jerry_char_t *) source,
+                                       strlen (source),
+                                       JERRY_PARSE_NO_OPTS);
+  if (!jerry_value_is_error (program))
+  {
+    jerry_value_t run_result = jerry_run (program);
+    jerry_release_value (run_result);
+  }
+
+  jerry_release_value (program);
+  jerry_cleanup ();
+
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_get_backtrace](#jerry_get_backtrace)
+
+
 ## jerry_get_resource_name

 **Summary**