bpo-32649: Add C API docs for per-opcode tracing & profiling (GH-5360) · python/cpython@255f7a2 (original) (raw)

`@@ -1277,8 +1277,8 @@ Python-level trace functions in previous versions.

1277

` registration function as obj, frame is the frame object to which the event

1278

`` pertains, what is one of the constants :const:PyTrace_CALL,

1279

`` :const:PyTrace_EXCEPTION, :const:PyTrace_LINE, :const:PyTrace_RETURN,

1280

`` -

:const:PyTrace_C_CALL, :const:PyTrace_C_EXCEPTION, or

1281

`` -

:const:PyTrace_C_RETURN, and arg depends on the value of what:

1280

`` +

:const:PyTrace_C_CALL, :const:PyTrace_C_EXCEPTION, :const:PyTrace_C_RETURN,

1281

`` +

or :const:PyTrace_OPCODE, and arg depends on the value of what:

1282

1283

`+------------------------------+--------------------------------------+

1284

` | Value of what | Meaning of arg |

`@@ -1299,6 +1299,8 @@ Python-level trace functions in previous versions.

1299

`+------------------------------+--------------------------------------+

1300

`` | :const:PyTrace_C_RETURN | Function object being called. |

1301

`+------------------------------+--------------------------------------+

1302

`` +

| :const:PyTrace_OPCODE | Always :c:data:Py_None. |

1303

+------------------------------+--------------------------------------+

1302

1304

1303

1305

`.. c:var:: int PyTrace_CALL

1304

1306

`@@ -1322,8 +1324,9 @@ Python-level trace functions in previous versions.

1322

1324

1323

1325

`.. c:var:: int PyTrace_LINE

1324

1326

1325

The value passed as the what parameter to a trace function (but not a

1326

profiling function) when a line-number event is being reported.

1327

`` +

The value passed as the what parameter to a :c:type:Py_tracefunc function

1328

(but not a profiling function) when a line-number event is being reported.

1329

`` +

It may be disabled for a frame by setting :attr:f_trace_lines to 0 on that frame.

1327

1330

1328

1331

1329

1332

`.. c:var:: int PyTrace_RETURN

`@@ -1350,24 +1353,32 @@ Python-level trace functions in previous versions.

1350

1353

` function has returned.

1351

1354

1352

1355

1356

.. c:var:: int PyTrace_OPCODE

1357

+

1358

`` +

The value for the what parameter to :c:type:Py_tracefunc functions (but not

1359

profiling functions) when a new opcode is about to be executed. This event is

1360

not emitted by default: it must be explicitly requested by setting

1361

`` +

:attr:f_trace_opcodes to 1 on the frame.

1362

+

1363

+

1353

1364

`.. c:function:: void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)

1354

1365

1355

1366

` Set the profiler function to func. The obj parameter is passed to the

1356

1367

` function as its first parameter, and may be any Python object, or NULL. If

1357

1368

` the profile function needs to maintain state, using a different value for obj

1358

1369

` for each thread provides a convenient and thread-safe place to store it. The

1359

1370

`` profile function is called for all monitored events except :const:PyTrace_LINE

1360

`` -

and :const:PyTrace_EXCEPTION.

1371

`` +

:const:PyTrace_OPCODE and :const:PyTrace_EXCEPTION.

1361

1372

1362

1373

1363

1374

`.. c:function:: void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)

1364

1375

1365

1376

` Set the tracing function to func. This is similar to

1366

1377

`` :c:func:PyEval_SetProfile, except the tracing function does receive line-number

1367

events and does not receive any event related to C function objects being called. Any

1368

`` -

trace function registered using :c:func:PyEval_SetTrace will not receive

1369

`` -

:const:PyTrace_C_CALL, :const:PyTrace_C_EXCEPTION or :const:PyTrace_C_RETURN

1370

as a value for the what parameter.

1378

events and per-opcode events, but does not receive any event related to C function

1379

`` +

objects being called. Any trace function registered using :c:func:PyEval_SetTrace

1380

`` +

will not receive :const:PyTrace_C_CALL, :const:PyTrace_C_EXCEPTION or

1381

`` +

:const:PyTrace_C_RETURN as a value for the what parameter.

1371

1382

1372

1383

`.. _advanced-debugging:

1373

1384