diff --git a/episodes/profiling-functions.md b/episodes/profiling-functions.md index 71ac9e1..b7cf902 100644 --- a/episodes/profiling-functions.md +++ b/episodes/profiling-functions.md @@ -73,7 +73,9 @@ def c(): a() ``` -Prints the following call stack: +Here we can see that the printing of the stack trace is called in `c()`, which is called by `b2()`, which is called by `a()`, which is called from global scope. + +Hence, this prints the following call stack: ```output File "C:\call_stack.py", line 13, in @@ -86,7 +88,11 @@ Prints the following call stack: traceback.print_stack() ``` -In this instance the base of the stack is printed first, other visualisations of call stacks may use the reverse ordering. +The first line states the file and line number where `a()` was called from (the last line of code in the file shown). The second line states that it was the function `a()` that was called, this could include it's arguments. The third line then repeats this pattern, stating the line number where `b2()` was called inside `a()`. This continues until the call to `traceback.print_stack()` is reached. + +You may see stack traces like this when an unhandled exception is thrown by your code. + +*In this instance the base of the stack has been printed first, other visualisations of call stacks may use the reverse ordering.* ::::::::::::::::::::::::::::::::::::::::::::: diff --git a/learners/reference.md b/learners/reference.md index 3cb17a2..03d71b7 100644 --- a/learners/reference.md +++ b/learners/reference.md @@ -12,6 +12,9 @@ Bottleneck *Bottleneck is a synonym of limiting factor.* +Call Stack +: The internal stack data-structure used during the execution of code, that tracks metadata related to the currently executing hierarchy of function calls. Elements in the call stack are referred to as stack frames. + `cProfile` : A function level profiler provided by the Python standard library. @@ -29,11 +32,26 @@ Limiting Factor `line_profiler` : A line level profiler for Python that can be installed via `pip`. +Pop +: The action of removing the top item from a stack data-structure (sometimes also used in reference to removing and returning the first item from a list or queue). + Profiling : The measuring and analysis of granular performance metrics of a program, to understand where time is being spent during execution. Typically used to prioritise optimisation. +Push +: The action of adding an item to the top of a stack data-structure (sometimes also used in reference to appending an item to a list or queue). + +Recursive +: A recursive function or algorithm is one that calls itself. Too many recursive calls, can lead to stack overflow exceptions. Most recursive functions can be restructured as loops. + `snakeviz` : A web-browser based visualisation tool for `cProfile` outputs that can be installed via `pip`. +Stack +: A last-in-first-out (LIFO) data structure. Similar in nature to a physical stack (e.g. of books), items are added to the top and those below the top cannot be accessed without first removing the ones above them. + +Stack Frame +: The term used to refer to elements within the call stack. A call stack's stack frame will contain metadata about a particular function call, such as where it was called from and any variables that have been allocated 'on the stack' within the function's local scope. When a stack frame is popped from the call stack, any variables allocated within the corresponding function's local scope would be deallocated. + `viztracer` : A timeline profiler for Python that can be installed via `pip`.