Ruby: vm_debug.h Source File

Ruby 3.3.7p123 (2025-01-15 revision be31f993d7fa0219d85f7b3c694d454da4ecc10b)

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
16RUBY_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
23struct 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);
27struct RNode *ruby_debug_print_node(int level, int debug_level, const char *header, const struct RNode *node);
28int ruby_debug_print_indent(int level, int debug_level, int indent_level);
29void ruby_debug_gc_check_func(void);
30void ruby_set_debug_option(const char *str);
31
32RUBY_SYMBOL_EXPORT_END
33
34#ifndef USE_RUBY_DEBUG_LOG
35#define USE_RUBY_DEBUG_LOG 0
36#endif
37
38/* RUBY_DEBUG_LOG: Logging debug information mechanism
39 *
40 * This feature provides a mechanism to store logging information
41 * to a file, stderr or memory space with simple macros.
42 *
43 * The following information will be stored.
44 * * (1) __FILE__, __LINE__ in C
45 * * (2) __FILE__, __LINE__ in Ruby
46 * * (3) __func__ in C (message title)
47 * * (4) given string with sprintf format
48 * * (5) Thread number (if multiple threads are running)
49 *
50 * This feature is enabled only USE_RUBY_DEBUG_LOG is enabled.
51 * Release version should not enable it.
52 *
53 * Running with the `RUBY_DEBUG_LOG` environment variable enables
54 * this feature.
55 *
56 * # logging into a file
57 * RUBY_DEBUG_LOG=/path/to/file STDERR
58 *
59 * # logging into STDERR
60 * RUBY_DEBUG_LOG=stderr
61 *
62 * # logging into memory space (check with a debugger)
63 * # It will help if the timing is important.
64 * RUBY_DEBUG_LOG=mem
65 *
66 * RUBY_DEBUG_LOG_FILTER environment variable can specify the filter string.
67 * If "(3) __func__ in C (message title)" contains the specified string, the
68 * information will be stored (example: RUBY_DEBUG_LOG_FILTER=str will enable
69 * only on str related information).
70 *
71 * In a MRI source code, you can use the following macros:
72 * * RUBY_DEBUG_LOG(fmt, ...): Above (1) to (4) will be logged.
73 * * RUBY_DEBUG_LOG2(file, line, fmt, ...):
74 * Same as RUBY_DEBUG_LOG(), but (1) will be replaced with given file, line.
75 */
76
77extern enum ruby_debug_log_mode {
78 ruby_debug_log_disabled = 0x00,
79 ruby_debug_log_memory = 0x01,
80 ruby_debug_log_stderr = 0x02,
81 ruby_debug_log_file = 0x04,
82} ruby_debug_log_mode;
83
84 RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 4, 5)
85void ruby_debug_log(const char *file, int line, const char *func_name, const char *fmt, ...);
86void ruby_debug_log_print(unsigned int n);
87bool ruby_debug_log_filter(const char *func_name, const char *file_name);
88
89#if RBIMPL_COMPILER_IS(GCC) && defined(__OPTIMIZE__)
90# define ruby_debug_log(...) \
91 RB_GNUC_EXTENSION_BLOCK( \
92 RBIMPL_WARNING_PUSH(); \
93 RBIMPL_WARNING_IGNORED(-Wformat-zero-length); \
94 ruby_debug_log(__VA_ARGS__); \
95 RBIMPL_WARNING_POP())
96#endif
97
98// convenient macro to log even if the USE_RUBY_DEBUG_LOG macro is not specified.
99// You can use this macro for temporary usage (you should not commit it).
100#define _RUBY_DEBUG_LOG(...) ruby_debug_log(__FILE__, __LINE__, RUBY_FUNCTION_NAME_STRING, "" __VA_ARGS__)
101
102#if USE_RUBY_DEBUG_LOG
103# define RUBY_DEBUG_LOG_ENABLED(func_name, file_name) \
104 (ruby_debug_log_mode && ruby_debug_log_filter(func_name, file_name))
105
106#define RUBY_DEBUG_LOG(...) do { \
107 if (RUBY_DEBUG_LOG_ENABLED(RUBY_FUNCTION_NAME_STRING, __FILE__)) \
108 ruby_debug_log(__FILE__, __LINE__, RUBY_FUNCTION_NAME_STRING, "" __VA_ARGS__); \
109} while (0)
110
111#define RUBY_DEBUG_LOG2(file, line, ...) do { \
112 if (RUBY_DEBUG_LOG_ENABLED(RUBY_FUNCTION_NAME_STRING, file)) \
113 ruby_debug_log(file, line, RUBY_FUNCTION_NAME_STRING, "" __VA_ARGS__); \
114} while (0)
115
116#else // USE_RUBY_DEBUG_LOG
117// do nothing
118#define RUBY_DEBUG_LOG(...)
119#define RUBY_DEBUG_LOG2(file, line, ...)
120#endif // USE_RUBY_DEBUG_LOG
121
122#endif /* RUBY_DEBUG_H */
RBIMPL_ATTR_FORMAT
#define RBIMPL_ATTR_FORMAT(x, y, z)
Wraps (or simulates) __attribute__((format))
Definition format.h:29
ruby.h
RNode
Definition rubyparser.h:166
ID
uintptr_t ID
Type that represents a Ruby identifier such as a variable name.
Definition value.h:52
VALUE
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40