bpo-17799: Explain real behaviour of sys.settrace and sys.setprofile … · python/cpython@fd844ef (original) (raw)

`@@ -1005,13 +1005,38 @@ always available.

1005

` Set the system's profile function, which allows you to implement a Python source

1006

`` code profiler in Python. See chapter :ref:profile for more information on the

1007

` Python profiler. The system's profile function is called similarly to the

1008

`` -

system's trace function (see :func:settrace), but it isn't called for each

1009

executed line of code (only on call and return, but the return event is reported

1010

even when an exception has been set). The function is thread-specific, but

1011

there is no way for the profiler to know about context switches between threads,

1012

so it does not make sense to use this in the presence of multiple threads. Also,

1008

`` +

system's trace function (see :func:settrace), but it is called with different events,

1009

for example it isn't called for each executed line of code (only on call and return,

1010

but the return event is reported even when an exception has been set). The function is

1011

thread-specific, but there is no way for the profiler to know about context switches between

1012

threads, so it does not make sense to use this in the presence of multiple threads. Also,

1013

``` its return value is not used, so it can simply return None.


`1014`

`1014`

``

``

`1015`

`+

Profile functions should have three arguments: *frame*, *event*, and

`

``

`1016`

``` +

*arg*. *frame* is the current stack frame. *event* is a string: ``'call'``,

1017


 ``'return'``, ``'c_call'``, ``'c_return'``, or ``'c_exception'``. *arg* depends

1018

on the event type.

1019

+

1020

The events have the following meaning:

1021

+

1022


 ``'call'``

1023

A function is called (or some other code block entered). The

1024


 profile function is called; *arg* is ``None``.

1025

+

1026


 ``'return'``

1027

A function (or other code block) is about to return. The profile

1028


 function is called; *arg* is the value that will be returned, or ``None``

1029

if the event is caused by an exception being raised.

1030

+

1031


 ``'c_call'``

1032

A C function is about to be called. This may be an extension function or

1033

a built-in. arg is the C function object.

1034

+

1035


 ``'c_return'``

1036

A C function has returned. arg is the C function object.

1037

+

1038


 ``'c_exception'``

1039

A C function has raised an exception. arg is the C function object.

1015

1040

1016

1041

`.. function:: setrecursionlimit(limit)

1017

1042

`@@ -1058,8 +1083,8 @@ always available.

1058

1083

1059

1084

` Trace functions should have three arguments: frame, event, and

1060

1085

``` *arg*. *frame* is the current stack frame. *event* is a string: 'call',


`1061`

``

``` -

``'line'``, ``'return'``, ``'exception'``, ``'c_call'``, ``'c_return'``, or

1062


``'c_exception'``. *arg* depends on the event type.

1086


 ``'line'``, ``'return'`` or ``'exception'``. *arg* depends on

1087

the event type.

1063

1088

1064

1089

``` The trace function is invoked (with *event* set to 'call') whenever a new


`1065`

`1090`

` local scope is entered; it should return a reference to a local trace

`

`@@ -1094,16 +1119,6 @@ always available.

`

`1094`

`1119`

```  tuple ``(exception, value, traceback)``; the return value specifies the

1095

1120

` new local trace function.

1096

1121

1097


 ``'c_call'``

1098

A C function is about to be called. This may be an extension function or

1099

a built-in. arg is the C function object.

1100

-

1101


 ``'c_return'``

1102

A C function has returned. arg is the C function object.

1103

-

1104


 ``'c_exception'``

1105

A C function has raised an exception. arg is the C function object.

1106

-

1107

1122

` Note that as an exception is propagated down the chain of callers, an

1108

1123

``` 'exception' event is generated at each level.

```

1109

1124