Debian Codegraph @

Modules/clinic/_remote_debugging_module.c.h

raw
1 /*[clinic input]
2 preserve
3 [clinic start generated code]*/
4
5 #if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)
6 # include "pycore_gc.h" // PyGC_Head
7 # include "pycore_runtime.h" // _Py_ID()
8 #endif
9 #include "pycore_critical_section.h"// Py_BEGIN_CRITICAL_SECTION()
10 #include "pycore_modsupport.h" // _PyArg_UnpackKeywords()
11
12 PyDoc_STRVAR(_remote_debugging_RemoteUnwinder___init____doc__,
13 "RemoteUnwinder(pid, *, all_threads=False, only_active_thread=False,\n"
14 " debug=False)\n"
15 "--\n"
16 "\n"
17 "Initialize a new RemoteUnwinder object for debugging a remote Python process.\n"
18 "\n"
19 "Args:\n"
20 " pid: Process ID of the target Python process to debug\n"
21 " all_threads: If True, initialize state for all threads in the process.\n"
22 " If False, only initialize for the main thread.\n"
23 " only_active_thread: If True, only sample the thread holding the GIL.\n"
24 " Cannot be used together with all_threads=True.\n"
25 " debug: If True, chain exceptions to explain the sequence of events that\n"
26 " lead to the exception.\n"
27 "\n"
28 "The RemoteUnwinder provides functionality to inspect and debug a running Python\n"
29 "process, including examining thread states, stack frames and other runtime data.\n"
30 "\n"
31 "Raises:\n"
32 " PermissionError: If access to the target process is denied\n"
33 " OSError: If unable to attach to the target process or access its memory\n"
34 " RuntimeError: If unable to read debug information from the target process\n"
35 " ValueError: If both all_threads and only_active_thread are True");
36
37 static int
38 _remote_debugging_RemoteUnwinder___init___impl(RemoteUnwinderObject *self,
39 int pid, int all_threads,
40 int only_active_thread,
41 int debug);
42
43 static int
44 _remote_debugging_RemoteUnwinder___init__(PyObject *self, PyObject *args, PyObject *kwargs)
45 {
46 int return_value = -1;
47 #if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)
48
49 #define NUM_KEYWORDS 4
50 static struct {
51 PyGC_Head _this_is_not_used;
52 PyObject_VAR_HEAD
53 Py_hash_t ob_hash;
54 PyObject *ob_item[NUM_KEYWORDS];
55 } _kwtuple = {
56 .ob_base = PyVarObject_HEAD_INIT(&PyTuple_Type, NUM_KEYWORDS)
57 .ob_hash = -1,
58 .ob_item = { &_Py_ID(pid), &_Py_ID(all_threads), &_Py_ID(only_active_thread), &_Py_ID(debug), },
59 };
60 #undef NUM_KEYWORDS
61 #define KWTUPLE (&_kwtuple.ob_base.ob_base)
62
63 #else // !Py_BUILD_CORE
64 # define KWTUPLE NULL
65 #endif // !Py_BUILD_CORE
66
67 static const char * const _keywords[] = {"pid", "all_threads", "only_active_thread", "debug", NULL};
68 static _PyArg_Parser _parser = {
69 .keywords = _keywords,
70 .fname = "RemoteUnwinder",
71 .kwtuple = KWTUPLE,
72 };
73 #undef KWTUPLE
74 PyObject *argsbuf[4];
75 PyObject * const *fastargs;
76 Py_ssize_t nargs = PyTuple_GET_SIZE(args);
77 Py_ssize_t noptargs = nargs + (kwargs ? PyDict_GET_SIZE(kwargs) : 0) - 1;
78 int pid;
79 int all_threads = 0;
80 int only_active_thread = 0;
81 int debug = 0;
82
83 fastargs = _PyArg_UnpackKeywords(_PyTuple_CAST(args)->ob_item, nargs, kwargs, NULL, &_parser,
84 /*minpos*/ 1, /*maxpos*/ 1, /*minkw*/ 0, /*varpos*/ 0, argsbuf);
85 if (!fastargs) {
86 goto exit;
87 }
88 pid = PyLong_AsInt(fastargs[0]);
89 if (pid == -1 && PyErr_Occurred()) {
90 goto exit;
91 }
92 if (!noptargs) {
93 goto skip_optional_kwonly;
94 }
95 if (fastargs[1]) {
96 all_threads = PyObject_IsTrue(fastargs[1]);
97 if (all_threads < 0) {
98 goto exit;
99 }
100 if (!--noptargs) {
101 goto skip_optional_kwonly;
102 }
103 }
104 if (fastargs[2]) {
105 only_active_thread = PyObject_IsTrue(fastargs[2]);
106 if (only_active_thread < 0) {
107 goto exit;
108 }
109 if (!--noptargs) {
110 goto skip_optional_kwonly;
111 }
112 }
113 debug = PyObject_IsTrue(fastargs[3]);
114 if (debug < 0) {
115 goto exit;
116 }
117 skip_optional_kwonly:
118 return_value = _remote_debugging_RemoteUnwinder___init___impl((RemoteUnwinderObject *)self, pid, all_threads, only_active_thread, debug);
119
120 exit:
121 return return_value;
122 }
123
124 PyDoc_STRVAR(_remote_debugging_RemoteUnwinder_get_stack_trace__doc__,
125 "get_stack_trace($self, /)\n"
126 "--\n"
127 "\n"
128 "Returns a list of stack traces for threads in the target process.\n"
129 "\n"
130 "Each element in the returned list is a tuple of (thread_id, frame_list), where:\n"
131 "- thread_id is the OS thread identifier\n"
132 "- frame_list is a list of tuples (function_name, filename, line_number) representing\n"
133 " the Python stack frames for that thread, ordered from most recent to oldest\n"
134 "\n"
135 "The threads returned depend on the initialization parameters:\n"
136 "- If only_active_thread was True: returns only the thread holding the GIL\n"
137 "- If all_threads was True: returns all threads\n"
138 "- Otherwise: returns only the main thread\n"
139 "\n"
140 "Example:\n"
141 " [\n"
142 " (1234, [\n"
143 " (\'process_data\', \'worker.py\', 127),\n"
144 " (\'run_worker\', \'worker.py\', 45),\n"
145 " (\'main\', \'app.py\', 23)\n"
146 " ]),\n"
147 " (1235, [\n"
148 " (\'handle_request\', \'server.py\', 89),\n"
149 " (\'serve_forever\', \'server.py\', 52)\n"
150 " ])\n"
151 " ]\n"
152 "\n"
153 "Raises:\n"
154 " RuntimeError: If there is an error copying memory from the target process\n"
155 " OSError: If there is an error accessing the target process\n"
156 " PermissionError: If access to the target process is denied\n"
157 " UnicodeDecodeError: If there is an error decoding strings from the target process");
158
159 #define _REMOTE_DEBUGGING_REMOTEUNWINDER_GET_STACK_TRACE_METHODDEF \
160 {"get_stack_trace", (PyCFunction)_remote_debugging_RemoteUnwinder_get_stack_trace, METH_NOARGS, _remote_debugging_RemoteUnwinder_get_stack_trace__doc__},
161
162 static PyObject *
163 _remote_debugging_RemoteUnwinder_get_stack_trace_impl(RemoteUnwinderObject *self);
164
165 static PyObject *
166 _remote_debugging_RemoteUnwinder_get_stack_trace(PyObject *self, PyObject *Py_UNUSED(ignored))
167 {
168 PyObject *return_value = NULL;
169
170 Py_BEGIN_CRITICAL_SECTION(self);
171 return_value = _remote_debugging_RemoteUnwinder_get_stack_trace_impl((RemoteUnwinderObject *)self);
172 Py_END_CRITICAL_SECTION();
173
174 return return_value;
175 }
176
177 PyDoc_STRVAR(_remote_debugging_RemoteUnwinder_get_all_awaited_by__doc__,
178 "get_all_awaited_by($self, /)\n"
179 "--\n"
180 "\n"
181 "Get all tasks and their awaited_by relationships from the remote process.\n"
182 "\n"
183 "This provides a tree structure showing which tasks are waiting for other tasks.\n"
184 "\n"
185 "For each task, returns:\n"
186 "1. The call stack frames leading to where the task is currently executing\n"
187 "2. The name of the task\n"
188 "3. A list of tasks that this task is waiting for, with their own frames/names/etc\n"
189 "\n"
190 "Returns a list of [frames, task_name, subtasks] where:\n"
191 "- frames: List of (func_name, filename, lineno) showing the call stack\n"
192 "- task_name: String identifier for the task\n"
193 "- subtasks: List of tasks being awaited by this task, in same format\n"
194 "\n"
195 "Raises:\n"
196 " RuntimeError: If AsyncioDebug section is not available in the remote process\n"
197 " MemoryError: If memory allocation fails\n"
198 " OSError: If reading from the remote process fails\n"
199 "\n"
200 "Example output:\n"
201 "[\n"
202 " [\n"
203 " [(\"c5\", \"script.py\", 10), (\"c4\", \"script.py\", 14)],\n"
204 " \"c2_root\",\n"
205 " [\n"
206 " [\n"
207 " [(\"c1\", \"script.py\", 23)],\n"
208 " \"sub_main_2\",\n"
209 " [...]\n"
210 " ],\n"
211 " [...]\n"
212 " ]\n"
213 " ]\n"
214 "]");
215
216 #define _REMOTE_DEBUGGING_REMOTEUNWINDER_GET_ALL_AWAITED_BY_METHODDEF \
217 {"get_all_awaited_by", (PyCFunction)_remote_debugging_RemoteUnwinder_get_all_awaited_by, METH_NOARGS, _remote_debugging_RemoteUnwinder_get_all_awaited_by__doc__},
218
219 static PyObject *
220 _remote_debugging_RemoteUnwinder_get_all_awaited_by_impl(RemoteUnwinderObject *self);
221
222 static PyObject *
223 _remote_debugging_RemoteUnwinder_get_all_awaited_by(PyObject *self, PyObject *Py_UNUSED(ignored))
224 {
225 PyObject *return_value = NULL;
226
227 Py_BEGIN_CRITICAL_SECTION(self);
228 return_value = _remote_debugging_RemoteUnwinder_get_all_awaited_by_impl((RemoteUnwinderObject *)self);
229 Py_END_CRITICAL_SECTION();
230
231 return return_value;
232 }
233
234 PyDoc_STRVAR(_remote_debugging_RemoteUnwinder_get_async_stack_trace__doc__,
235 "get_async_stack_trace($self, /)\n"
236 "--\n"
237 "\n"
238 "Get the currently running async tasks and their dependency graphs from the remote process.\n"
239 "\n"
240 "This returns information about running tasks and all tasks that are waiting for them,\n"
241 "forming a complete dependency graph for each thread\'s active task.\n"
242 "\n"
243 "For each thread with a running task, returns the running task plus all tasks that\n"
244 "transitively depend on it (tasks waiting for the running task, tasks waiting for\n"
245 "those tasks, etc.).\n"
246 "\n"
247 "Returns a list of per-thread results, where each thread result contains:\n"
248 "- Thread ID\n"
249 "- List of task information for the running task and all its waiters\n"
250 "\n"
251 "Each task info contains:\n"
252 "- Task ID (memory address)\n"
253 "- Task name\n"
254 "- Call stack frames: List of (func_name, filename, lineno)\n"
255 "- List of tasks waiting for this task (recursive structure)\n"
256 "\n"
257 "Raises:\n"
258 " RuntimeError: If AsyncioDebug section is not available in the target process\n"
259 " MemoryError: If memory allocation fails\n"
260 " OSError: If reading from the remote process fails\n"
261 "\n"
262 "Example output (similar structure to get_all_awaited_by but only for running tasks):\n"
263 "[\n"
264 " (140234, [\n"
265 " (4345585712, \'main_task\',\n"
266 " [(\"run_server\", \"server.py\", 127), (\"main\", \"app.py\", 23)],\n"
267 " [\n"
268 " (4345585800, \'worker_1\', [...], [...]),\n"
269 " (4345585900, \'worker_2\', [...], [...])\n"
270 " ])\n"
271 " ])\n"
272 "]");
273
274 #define _REMOTE_DEBUGGING_REMOTEUNWINDER_GET_ASYNC_STACK_TRACE_METHODDEF \
275 {"get_async_stack_trace", (PyCFunction)_remote_debugging_RemoteUnwinder_get_async_stack_trace, METH_NOARGS, _remote_debugging_RemoteUnwinder_get_async_stack_trace__doc__},
276
277 static PyObject *
278 _remote_debugging_RemoteUnwinder_get_async_stack_trace_impl(RemoteUnwinderObject *self);
279
280 static PyObject *
281 _remote_debugging_RemoteUnwinder_get_async_stack_trace(PyObject *self, PyObject *Py_UNUSED(ignored))
282 {
283 PyObject *return_value = NULL;
284
285 Py_BEGIN_CRITICAL_SECTION(self);
286 return_value = _remote_debugging_RemoteUnwinder_get_async_stack_trace_impl((RemoteUnwinderObject *)self);
287 Py_END_CRITICAL_SECTION();
288
289 return return_value;
290 }
291 /*[clinic end generated code: output=0dd1e6e8bab2a8b1 input=a9049054013a1b77]*/