From 8655c2e69041cc812d30c2e951a8ac9ea7a60c47 Mon Sep 17 00:00:00 2001
From: Koichi Sasada <ko1@atdot.net>
Date: Fri, 3 Jul 2020 16:55:54 +0900
Subject: RUBY_DEBUG_LOG: Logging debug information mechanism (#3279)

* RUBY_DEBUG_LOG: Logging debug information mechanism

This feature provides a mechanism to store logging information
to a file, stderr or memory space with simple macros.

The following information will be stored.
  * (1) __FILE__, __LINE__ in C
  * (2) __FILE__, __LINE__ in Ruby
  * (3) __func__ in C (message title)
  * (4) given string with sprintf format
  * (5) Thread number (if multiple threads are running)

This feature is enabled only USE_RUBY_DEBUG_LOG is enabled.
Release version should not enable it.

Running with the `RUBY_DEBUG_LOG` environment variable enables
this feature.

  # logging into a file
  RUBY_DEBUG_LOG=/path/to/file STDERR

  # logging into STDERR
  RUBY_DEBUG_LOG=stderr

  # logging into memory space (check with a debugger)
  # It will help if the timing is important.
  RUBY_DEBUG_LOG=mem

RUBY_DEBUG_LOG_FILTER environment variable can specify the fileter string.
If "(3) __func__ in C (message title)" contains the specified string, the
infomation will be stored (example: RUBY_DEBUG_LOG_FILTER=str will enable
only on str related information).

In a MRI source code, you can use the following macros:
  * RUBY_DEBUG_LOG(fmt, ...): Above (1) to (4) will be logged.
  * RUBY_DEBUG_LOG2(file, line, fmt, ...):
    Same as RUBY_DEBUG_LOG(), but (1) will be replaced with given file, line.
---
 vm_debug.h | 73 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)

(limited to 'vm_debug.h')

diff --git a/vm_debug.h b/vm_debug.h
index 93ee2e4297..fbfcb05a68 100644
--- a/vm_debug.h
+++ b/vm_debug.h
@@ -30,4 +30,77 @@ void ruby_set_debug_option(const char *str);
 
 RUBY_SYMBOL_EXPORT_END
 
+#if RUBY_DEVEL
+#ifndef USE_RUBY_DEBUG_LOG
+#define USE_RUBY_DEBUG_LOG 0
+#endif
+#else
+// disable on !RUBY_DEVEL
+#ifdef USE_RUBY_DEBUG_LOG
+#undef USE_RUBY_DEBUG_LOG
+#endif
+#endif
+
+/* RUBY_DEBUG_LOG: Logging debug information mechanism
+ *
+ * This feature provides a mechanism to store logging information
+ * to a file, stderr or memory space with simple macros.
+ *
+ * The following information will be stored.
+ *   * (1) __FILE__, __LINE__ in C
+ *   * (2) __FILE__, __LINE__ in Ruby
+ *   * (3) __func__ in C (message title)
+ *   * (4) given string with sprintf format
+ *   * (5) Thread number (if multiple threads are running)
+ *
+ * This feature is enabled only USE_RUBY_DEBUG_LOG is enabled.
+ * Release version should not enable it.
+ *
+ * Running with the `RUBY_DEBUG_LOG` environment variable enables
+ * this feature.
+ *
+ *   # logging into a file
+ *   RUBY_DEBUG_LOG=/path/to/file STDERR
+ *
+ *   # logging into STDERR
+ *   RUBY_DEBUG_LOG=stderr
+ *
+ *   # logging into memory space (check with a debugger)
+ *   # It will help if the timing is important.
+ *   RUBY_DEBUG_LOG=mem
+ *
+ * RUBY_DEBUG_LOG_FILTER environment variable can specify the fileter string.
+ * If "(3) __func__ in C (message title)" contains the specified string, the
+ * infomation will be stored (example: RUBY_DEBUG_LOG_FILTER=str will enable
+ * only on str related information).
+ *
+ * In a MRI source code, you can use the following macros:
+ *   * RUBY_DEBUG_LOG(fmt, ...): Above (1) to (4) will be logged.
+ *   * RUBY_DEBUG_LOG2(file, line, fmt, ...):
+ *     Same as RUBY_DEBUG_LOG(), but (1) will be replaced with given file, line.
+ */
+
+extern enum ruby_debug_log_mode {
+    ruby_debug_log_disabled = 0x00,
+    ruby_debug_log_memory   = 0x01,
+    ruby_debug_log_stderr   = 0x02,
+    ruby_debug_log_file     = 0x04,
+} ruby_debug_log_mode;
+
+void ruby_debug_log(const char *file, int line, const char *func_name, const char *fmt, ...);
+void ruby_debug_log_print(unsigned int n);
+
+// convenient macro to log even if the USE_RUBY_DEBUG_LOG macro is not specified.
+// You can use this macro for temporary usage (you should not commit it).
+#define _RUBY_DEBUG_LOG(fmt, ...) ruby_debug_log(__FILE__, __LINE__, __func__, fmt, __VA_ARGS__)
+
+#if USE_RUBY_DEBUG_LOG
+#define RUBY_DEBUG_LOG(fmt, ...) do { if (ruby_debug_log_mode) ruby_debug_log(__FILE__, __LINE__, __func__, fmt, __VA_ARGS__); } while (0)
+#define RUBY_DEBUG_LOG2(file, line, fmt, ...) do { if (ruby_debug_log_mode) ruby_debug_log(file, line, __func__, fmt, __VA_ARGS__); } while (0)
+#else
+// do nothing
+#define RUBY_DEBUG_LOG(fmt, ...)
+#define RUBY_DEBUG_LOG2(file, line, fmt, ...)
+#endif // USE_RUBY_DEBUG_LOG
+
 #endif /* RUBY_DEBUG_H */
-- 
cgit v1.2.1