Ruby  3.1.4p223 (2023-03-30 revision HEAD)
vm_debug.h
1 #ifndef RUBY_DEBUG_H
2 #define RUBY_DEBUG_H
3 /**********************************************************************
4 
5  vm_debug.h - YARV Debug function interface
6 
7  $Author$
8  created at: 04/08/25 02:33:49 JST
9 
10  Copyright (C) 2004-2007 Koichi Sasada
11 
12 **********************************************************************/
13 
14 #include "ruby/ruby.h"
15 
16 RUBY_SYMBOL_EXPORT_BEGIN
17 
18 #define dpv(h,v) ruby_debug_print_value(-1, 0, (h), (v))
19 #define dp(v) ruby_debug_print_value(-1, 0, "", (v))
20 #define dpi(i) ruby_debug_print_id(-1, 0, "", (i))
21 #define dpn(n) ruby_debug_print_node(-1, 0, "", (n))
22 
23 struct RNode;
24 
25 VALUE ruby_debug_print_value(int level, int debug_level, const char *header, VALUE v);
26 ID ruby_debug_print_id(int level, int debug_level, const char *header, ID id);
27 struct RNode *ruby_debug_print_node(int level, int debug_level, const char *header, const struct RNode *node);
28 int ruby_debug_print_indent(int level, int debug_level, int indent_level);
29 void ruby_debug_gc_check_func(void);
30 void ruby_set_debug_option(const char *str);
31 
32 RUBY_SYMBOL_EXPORT_END
33 
34 #ifndef RUBY_DEVEL
35 # define RUBY_DEVEL 0
36 #endif
37 
38 #if RUBY_DEVEL
39 #ifndef USE_RUBY_DEBUG_LOG
40 #define USE_RUBY_DEBUG_LOG 0
41 #endif
42 #else
43 // disable on !RUBY_DEVEL
44 #ifdef USE_RUBY_DEBUG_LOG
45 #undef USE_RUBY_DEBUG_LOG
46 #endif
47 #endif
48 
49 /* RUBY_DEBUG_LOG: Logging debug information mechanism
50  *
51  * This feature provides a mechanism to store logging information
52  * to a file, stderr or memory space with simple macros.
53  *
54  * The following information will be stored.
55  * * (1) __FILE__, __LINE__ in C
56  * * (2) __FILE__, __LINE__ in Ruby
57  * * (3) __func__ in C (message title)
58  * * (4) given string with sprintf format
59  * * (5) Thread number (if multiple threads are running)
60  *
61  * This feature is enabled only USE_RUBY_DEBUG_LOG is enabled.
62  * Release version should not enable it.
63  *
64  * Running with the `RUBY_DEBUG_LOG` environment variable enables
65  * this feature.
66  *
67  * # logging into a file
68  * RUBY_DEBUG_LOG=/path/to/file STDERR
69  *
70  * # logging into STDERR
71  * RUBY_DEBUG_LOG=stderr
72  *
73  * # logging into memory space (check with a debugger)
74  * # It will help if the timing is important.
75  * RUBY_DEBUG_LOG=mem
76  *
77  * RUBY_DEBUG_LOG_FILTER environment variable can specify the filter string.
78  * If "(3) __func__ in C (message title)" contains the specified string, the
79  * information will be stored (example: RUBY_DEBUG_LOG_FILTER=str will enable
80  * only on str related information).
81  *
82  * In a MRI source code, you can use the following macros:
83  * * RUBY_DEBUG_LOG(fmt, ...): Above (1) to (4) will be logged.
84  * * RUBY_DEBUG_LOG2(file, line, fmt, ...):
85  * Same as RUBY_DEBUG_LOG(), but (1) will be replaced with given file, line.
86  */
87 
88 extern enum ruby_debug_log_mode {
89  ruby_debug_log_disabled = 0x00,
90  ruby_debug_log_memory = 0x01,
91  ruby_debug_log_stderr = 0x02,
92  ruby_debug_log_file = 0x04,
93 } ruby_debug_log_mode;
94 
95 RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 4, 5)
96 void ruby_debug_log(const char *file, int line, const char *func_name, const char *fmt, ...);
97 void ruby_debug_log_print(unsigned int n);
98 bool ruby_debug_log_filter(const char *func_name);
99 
100 // convenient macro to log even if the USE_RUBY_DEBUG_LOG macro is not specified.
101 // You can use this macro for temporary usage (you should not commit it).
102 #define _RUBY_DEBUG_LOG(...) ruby_debug_log(__FILE__, __LINE__, RUBY_FUNCTION_NAME_STRING, "" __VA_ARGS__)
103 
104 #if defined(USE_RUBY_DEBUG_LOG) && USE_RUBY_DEBUG_LOG
105 # define RUBY_DEBUG_LOG_ENABLED(func_name) \
106  (ruby_debug_log_mode && ruby_debug_log_filter(func_name))
107 
108 #define RUBY_DEBUG_LOG(...) do { \
109  if (RUBY_DEBUG_LOG_ENABLED(RUBY_FUNCTION_NAME_STRING)) \
110  ruby_debug_log(__FILE__, __LINE__, RUBY_FUNCTION_NAME_STRING, "" __VA_ARGS__); \
111 } while (0)
112 
113 #define RUBY_DEBUG_LOG2(file, line, ...) do { \
114  if (RUBY_DEBUG_LOG_ENABLED(RUBY_FUNCTION_NAME_STRING)) \
115  ruby_debug_log(file, line, RUBY_FUNCTION_NAME_STRING, "" __VA_ARGS__); \
116 } while (0)
117 
118 #else
119 // do nothing
120 #define RUBY_DEBUG_LOG(...)
121 #define RUBY_DEBUG_LOG2(file, line, ...)
122 #endif // USE_RUBY_DEBUG_LOG
123 
124 #endif /* RUBY_DEBUG_H */
#define RBIMPL_ATTR_FORMAT(x, y, z)
Wraps (or simulates) __attribute__((format))
Definition: format.h:27
Definition: node.h:155
uintptr_t ID
Type that represents a Ruby identifier such as a variable name.
Definition: value.h:52
uintptr_t VALUE
Type that represents a Ruby object.
Definition: value.h:40