Skip to content

Commit 7ddb75f

Browse files
committed
Update v3/docs/developer-overview.md
1 parent 8d4cb58 commit 7ddb75f

1 file changed

Lines changed: 22 additions & 2 deletions

File tree

v3/docs/developer-overview.md

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -202,6 +202,26 @@ except SystemExit:
202202
The `run` method is actually [inherited from bdb.Bdb](http://docs.python.org/library/bdb.html#bdb.Bdb.run).
203203
It executes the contents of `script_str` in a modified global environment (`user_globals`).
204204

205-
Ok, the debugger has just started executing the script that the user passed in (from `example.py` in our example).
206-
What happens now?
205+
Ok, the debugger has just started executing the program that the user passed in (from `example.py` in our example).
206+
What happens now? Here's where the magic happens. Look at the methods called
207+
`user_call`, `user_return`, `user_exception`, and `user_line`. Again, those are all
208+
[inherited from bdb.Bdb](http://docs.python.org/library/bdb.html#bdb). As the user's program is running, bdb
209+
will pause execution at every function call, return, exception, and single-step and transfer control
210+
over to the respective handler methods. Since `PGLogger` overrides those methods, it can hijack control at
211+
crucial points during program execution to do what it needs to do.
212+
213+
Since `PGLogger` does similar things regardless of why execution was paused (function call, return, exception, or single-step),
214+
all handlers dispatch to a giant method called `interaction`.
215+
216+
During a call to `interaction`, the backend collects the state of the stack and all run-time data and then creates a
217+
trace entry (`trace_entry` dict). Then it appends `trace_entry` onto `self.trace`:
218+
219+
```python
220+
self.trace.append(trace_entry)
221+
```
222+
223+
Every time bdb pauses the user's program's execution and dispatches to `interaction` in `PGLogger`, one new trace
224+
entry is created. At the end of execution, `self.trace` contains as many trace entries as there were "steps"
225+
in the user's program execution.
226+
(To guard against infinite loops, `PGLogger` terminates execution when `MAX_EXECUTED_LINES` steps have been executed.)
207227

0 commit comments

Comments
 (0)