summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
authorPablo Galindo <Pablogsal@gmail.com>2018-01-24 12:57:49 (GMT)
committerXiang Zhang <angwerzx@126.com>2018-01-24 12:57:49 (GMT)
commit131fd7f96c619bc7eaea956e45c6337175f4b27f (patch)
treec184daaf3c2c5588b6ed4766c2742844f3593859 /Doc
parent018e1b7aad8d1a33ee14aae5c466d581d31e2369 (diff)
downloadcpython-131fd7f96c619bc7eaea956e45c6337175f4b27f.zip
cpython-131fd7f96c619bc7eaea956e45c6337175f4b27f.tar.gz
cpython-131fd7f96c619bc7eaea956e45c6337175f4b27f.tar.bz2
bpo-17799: Explain real behaviour of sys.settrace and sys.setprofile (#4056)
Diffstat (limited to 'Doc')
-rw-r--r--Doc/c-api/init.rst11
-rw-r--r--Doc/library/sys.rst49
2 files changed, 38 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