Ruby: vm_debug.h Source File

Ruby 3.0.5p211 (2022-11-24 revision ba5cf0f7c52d4d35cc6a173c89eda98ceffa2dcf)

vm_debug.h
Go to the documentation of this file.
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#include "node.h"
16
17RUBY_SYMBOL_EXPORT_BEGIN
18
19#define dpv(h,v) ruby_debug_print_value(-1, 0, (h), (v))
20#define dp(v) ruby_debug_print_value(-1, 0, "", (v))
21#define dpi(i) ruby_debug_print_id(-1, 0, "", (i))
22#define dpn(n) ruby_debug_print_node(-1, 0, "", (n))
23
24 VALUE ruby_debug_print_value(int level, int debug_level, const char *header, VALUE v);
25 ID ruby_debug_print_id(int level, int debug_level, const char *header, ID id);
26 NODE *ruby_debug_print_node(int level, int debug_level, const char *header, const NODE *node);
27int ruby_debug_print_indent(int level, int debug_level, int indent_level);
28 void ruby_debug_gc_check_func(void);
29void ruby_set_debug_option(const char *str);
30
31RUBY_SYMBOL_EXPORT_END
32
33#if RUBY_DEVEL
34#ifndef USE_RUBY_DEBUG_LOG
35#define USE_RUBY_DEBUG_LOG 0
36#endif
37#else
38// disable on !RUBY_DEVEL
39#ifdef USE_RUBY_DEBUG_LOG
40#undef USE_RUBY_DEBUG_LOG
41#endif
42#endif
43
44/* RUBY_DEBUG_LOG: Logging debug information mechanism
45 *
46 * This feature provides a mechanism to store logging information
47 * to a file, stderr or memory space with simple macros.
48 *
49 * The following information will be stored.
50 * * (1) __FILE__, __LINE__ in C
51 * * (2) __FILE__, __LINE__ in Ruby
52 * * (3) __func__ in C (message title)
53 * * (4) given string with sprintf format
54 * * (5) Thread number (if multiple threads are running)
55 *
56 * This feature is enabled only USE_RUBY_DEBUG_LOG is enabled.
57 * Release version should not enable it.
58 *
59 * Running with the `RUBY_DEBUG_LOG` environment variable enables
60 * this feature.
61 *
62 * # logging into a file
63 * RUBY_DEBUG_LOG=/path/to/file STDERR
64 *
65 * # logging into STDERR
66 * RUBY_DEBUG_LOG=stderr
67 *
68 * # logging into memory space (check with a debugger)
69 * # It will help if the timing is important.
70 * RUBY_DEBUG_LOG=mem
71 *
72 * RUBY_DEBUG_LOG_FILTER environment variable can specify the filter string.
73 * If "(3) __func__ in C (message title)" contains the specified string, the
74 * information will be stored (example: RUBY_DEBUG_LOG_FILTER=str will enable
75 * only on str related information).
76 *
77 * In a MRI source code, you can use the following macros:
78 * * RUBY_DEBUG_LOG(fmt, ...): Above (1) to (4) will be logged.
79 * * RUBY_DEBUG_LOG2(file, line, fmt, ...):
80 * Same as RUBY_DEBUG_LOG(), but (1) will be replaced with given file, line.
81 */
82
83 extern enum ruby_debug_log_mode {
84 ruby_debug_log_disabled = 0x00,
85 ruby_debug_log_memory = 0x01,
86 ruby_debug_log_stderr = 0x02,
87 ruby_debug_log_file = 0x04,
88} ruby_debug_log_mode;
89
90 void ruby_debug_log(const char *file, int line, const char *func_name, const char *fmt, ...);
91 void ruby_debug_log_print(unsigned int n);
92 bool ruby_debug_log_filter(const char *func_name);
93
94// convenient macro to log even if the USE_RUBY_DEBUG_LOG macro is not specified.
95// You can use this macro for temporary usage (you should not commit it).
96#define _RUBY_DEBUG_LOG(fmt, ...) ruby_debug_log(__FILE__, __LINE__, __func__, fmt, __VA_ARGS__)
97
98#if USE_RUBY_DEBUG_LOG
99
100#define RUBY_DEBUG_LOG(fmt, ...) do { \
101 if (ruby_debug_log_mode && ruby_debug_log_filter(__func__)) \
102 ruby_debug_log(__FILE__, __LINE__, __func__, fmt, __VA_ARGS__); \
103} while (0)
104
105#define RUBY_DEBUG_LOG2(file, line, fmt, ...) do { \
106 if (ruby_debug_log_mode && ruby_debug_log_filter(__func__)) \
107 ruby_debug_log(file, line, __func__, fmt, __VA_ARGS__); \
108} while (0)
109
110#else
111// do nothing
112#define RUBY_DEBUG_LOG(fmt, ...)
113#define RUBY_DEBUG_LOG2(file, line, fmt, ...)
114#endif // USE_RUBY_DEBUG_LOG
115
116#endif /* RUBY_DEBUG_H */
str
char str[HTML_ESCAPE_MAX_LEN+1]
Definition: escape.c:18
node.h
ruby.h
RNode
Definition: node.h:149
file
Definition: gzappend.c:170
VALUE
unsigned long VALUE
Definition: value.h:38
ID
unsigned long ID
Definition: value.h:39
ruby_debug_log_filter
bool ruby_debug_log_filter(const char *func_name)
ruby_debug_print_indent
int ruby_debug_print_indent(int level, int debug_level, int indent_level)
Definition: debug.c:97
ruby_debug_log
void ruby_debug_log(const char *file, int line, const char *func_name, const char *fmt,...)
ruby_debug_print_value
VALUE ruby_debug_print_value(int level, int debug_level, const char *header, VALUE v)
Definition: debug.c:119
ruby_set_debug_option
void ruby_set_debug_option(const char *str)
Definition: debug.c:259
ruby_debug_log_print
void ruby_debug_log_print(unsigned int n)
ruby_debug_gc_check_func
void ruby_debug_gc_check_func(void)
ruby_debug_log_mode
ruby_debug_log_mode
Definition: vm_debug.h:83
ruby_debug_log_file
@ ruby_debug_log_file
Definition: vm_debug.h:87
ruby_debug_log_stderr
@ ruby_debug_log_stderr
Definition: vm_debug.h:86
ruby_debug_log_memory
@ ruby_debug_log_memory
Definition: vm_debug.h:85
ruby_debug_log_disabled
@ ruby_debug_log_disabled
Definition: vm_debug.h:84
ruby_debug_print_id
ID ruby_debug_print_id(int level, int debug_level, const char *header, ID id)
Definition: debug.c:138
ruby_debug_print_node
NODE * ruby_debug_print_node(int level, int debug_level, const char *header, const NODE *node)
Definition: debug.c:148