bpo-17799: Explain real behaviour of sys.settrace and sys.setprofile … · python/cpython@e64a47b (original) (raw)
`@@ -857,13 +857,38 @@ always available.
`
857
857
` Set the system's profile function, which allows you to implement a Python source
`
858
858
`` code profiler in Python. See chapter :ref:profile for more information on the
``
859
859
` Python profiler. The system's profile function is called similarly to the
`
860
``
`` -
system's trace function (see :func:settrace), but it isn't called for each
``
861
``
`-
executed line of code (only on call and return, but the return event is reported
`
862
``
`-
even when an exception has been set). The function is thread-specific, but
`
863
``
`-
there is no way for the profiler to know about context switches between threads,
`
864
``
`-
so it does not make sense to use this in the presence of multiple threads. Also,
`
``
860
`` +
system's trace function (see :func:settrace), but it is called with different events,
``
``
861
`+
for example it isn't called for each executed line of code (only on call and return,
`
``
862
`+
but the return event is reported even when an exception has been set). The function is
`
``
863
`+
thread-specific, but there is no way for the profiler to know about context switches between
`
``
864
`+
threads, so it does not make sense to use this in the presence of multiple threads. Also,
`
865
865
``` its return value is not used, so it can simply return None.
`866`
`866`
``
``
`867`
`+
Profile functions should have three arguments: *frame*, *event*, and
`
``
`868`
``` +
*arg*. *frame* is the current stack frame. *event* is a string: ``'call'``,
``
869
``'return'``, ``'c_call'``, ``'c_return'``, or ``'c_exception'``. *arg* depends
``
870
`+
on the event type.
`
``
871
+
``
872
`+
The events have the following meaning:
`
``
873
+
``
874
``'call'``
``
875
`+
A function is called (or some other code block entered). The
`
``
876
profile function is called; *arg* is ``None``.
``
877
+
``
878
``'return'``
``
879
`+
A function (or other code block) is about to return. The profile
`
``
880
function is called; *arg* is the value that will be returned, or ``None``
``
881
`+
if the event is caused by an exception being raised.
`
``
882
+
``
883
``'c_call'``
``
884
`+
A C function is about to be called. This may be an extension function or
`
``
885
`+
a built-in. arg is the C function object.
`
``
886
+
``
887
``'c_return'``
``
888
`+
A C function has returned. arg is the C function object.
`
``
889
+
``
890
``'c_exception'``
``
891
`+
A C function has raised an exception. arg is the C function object.
`
867
892
``
868
893
`.. function:: setrecursionlimit(limit)
`
869
894
``
`@@ -890,8 +915,8 @@ always available.
`
890
915
``
891
916
` Trace functions should have three arguments: frame, event, and
`
892
917
``` *arg*. *frame* is the current stack frame. *event* is a string: 'call',
`893`
``
``` -
``'line'``, ``'return'``, ``'exception'``, ``'c_call'``, ``'c_return'``, or
894
``
``'c_exception'``. *arg* depends on the event type.
``
918
``'line'``, ``'return'`` or ``'exception'``. *arg* depends on
``
919
`+
the event type.
`
895
920
``
896
921
``` The trace function is invoked (with *event* set to 'call') whenever a new
`897`
`922`
` local scope is entered; it should return a reference to a local trace
`
`@@ -926,16 +951,6 @@ always available.
`
`926`
`951`
``` tuple ``(exception, value, traceback)``; the return value specifies the
927
952
` new local trace function.
`
928
953
``
929
``
``'c_call'``
930
``
`-
A C function is about to be called. This may be an extension function or
`
931
``
`-
a built-in. arg is the C function object.
`
932
``
-
933
``
``'c_return'``
934
``
`-
A C function has returned. arg is the C function object.
`
935
``
-
936
``
``'c_exception'``
937
``
`-
A C function has raised an exception. arg is the C function object.
`
938
``
-
939
954
` Note that as an exception is propagated down the chain of callers, an
`
940
955
``` 'exception' event is generated at each level.
```
941
956
``
`@@ -1078,4 +1093,3 @@ always available.
`
1078
1093
`.. rubric:: Citations
`
1079
1094
``
1080
1095
`.. [C99] ISO/IEC 9899:1999. "Programming languages -- C." A public draft of this standard is available at http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf\ .
`
1081
``
-