diff options
| -rw-r--r-- | Doc/c-api/init.rst | 11 | ||||
| -rw-r--r-- | Doc/library/sys.rst | 49 | ||||
| -rw-r--r-- | Misc/NEWS.d/next/Documentation/2018-01-22-21-13-46.bpo-17799.rdZ-Vk.rst | 2 |
3 files changed, 40 insertions, 22 deletions
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 4ee61e8..86faf47 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1300,7 +1300,6 @@ Python-level trace functions in previous versions. | :const:`PyTrace_C_RETURN` | Function object being called. | +------------------------------+--------------------------------------+ - .. c:var:: int PyTrace_CALL The value of the *what* parameter to a :c:type:`Py_tracefunc` function when a new @@ -1357,16 +1356,18 @@ Python-level trace functions in previous versions. function as its first parameter, and may be any Python object, or *NULL*. If the profile function needs to maintain state, using a different value for *obj* for each thread provides a convenient and thread-safe place to store it. The - profile function is called for all monitored events except the line-number - events. + profile function is called for all monitored events except :const:`PyTrace_LINE` + and :const:`PyTrace_EXCEPTION`. .. c:function:: void PyEval_SetTrace(Py_tracefunc func, PyObject *obj) Set the tracing function to *func*. This is similar to :c:func:`PyEval_SetProfile`, except the tracing function does receive line-number - events. - + events and does not receive any event related to C function objects being called. Any + trace function registered using :c:func:`PyEval_SetTrace` will not receive + :const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION` or :const:`PyTrace_C_RETURN` + as a value for the *what* parameter. .. _advanced-debugging: diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index 54281a3..ab08f61 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -1084,13 +1084,38 @@ always available. Set the system's profile function, which allows you to implement a Python source code profiler in Python. See chapter :ref:`profile` for more information on the Python profiler. The system's profile function is called similarly to the - system's trace function (see :func:`settrace`), but it isn't called for each - executed line of code (only on call and return, but the return event is reported - even when an exception has been set). The function is thread-specific, but - there is no way for the profiler to know about context switches between threads, - so it does not make sense to use this in the presence of multiple threads. Also, + system's trace function (see :func:`settrace`), but it is called with different events, + for example it isn't called for each executed line of code (only on call and return, + but the return event is reported even when an exception has been set). The function is + thread-specific, but there is no way for the profiler to know about context switches between + threads, so it does not make sense to use this in the presence of multiple threads. Also, its return value is not used, so it can simply return ``None``. + Profile functions should have three arguments: *frame*, *event*, and + *arg*. *frame* is the current stack frame. *event* is a string: ``'call'``, + ``'return'``, ``'c_call'``, ``'c_return'``, or ``'c_exception'``. *arg* depends + on the event type. + + The events have the following meaning: + + ``'call'`` + A function is called (or some other code block entered). The + profile function is called; *arg* is ``None``. + + ``'return'`` + A function (or other code block) is about to return. The profile + function is called; *arg* is the value that will be returned, or ``None`` + if the event is caused by an exception being raised. + + ``'c_call'`` + A C function is about to be called. This may be an extension function or + a built-in. *arg* is the C function object. + + ``'c_return'`` + A C function has returned. *arg* is the C function object. + + ``'c_exception'`` + A C function has raised an exception. *arg* is the C function object. .. function:: setrecursionlimit(limit) @@ -1137,8 +1162,8 @@ always available. Trace functions should have three arguments: *frame*, *event*, and *arg*. *frame* is the current stack frame. *event* is a string: ``'call'``, - ``'line'``, ``'return'``, ``'exception'``, ``'c_call'``, ``'c_return'``, or - ``'c_exception'``, ``'opcode'``. *arg* depends on the event type. + ``'line'``, ``'return'``, ``'exception'`` or ``'opcode'``. *arg* depends on + the event type. The trace function is invoked (with *event* set to ``'call'``) whenever a new local scope is entered; it should return a reference to a local trace @@ -1175,16 +1200,6 @@ always available. tuple ``(exception, value, traceback)``; the return value specifies the new local trace function. - ``'c_call'`` - A C function is about to be called. This may be an extension function or - a built-in. *arg* is the C function object. - - ``'c_return'`` - A C function has returned. *arg* is the C function object. - - ``'c_exception'`` - A C function has raised an exception. *arg* is the C function object. - ``'opcode'`` The interpreter is about to execute a new opcode (see :mod:`dis` for opcode details). The local trace function is called; *arg* is diff --git a/Misc/NEWS.d/next/Documentation/2018-01-22-21-13-46.bpo-17799.rdZ-Vk.rst b/Misc/NEWS.d/next/Documentation/2018-01-22-21-13-46.bpo-17799.rdZ-Vk.rst new file mode 100644 index 0000000..ccc52f6 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2018-01-22-21-13-46.bpo-17799.rdZ-Vk.rst @@ -0,0 +1,2 @@ +Explain real behaviour of sys.settrace and sys.setprofile and their C-API counterparts +regarding which type of events are received in each function. Patch by Pablo Galindo Salgado. |