+++ /dev/null
-All about co_lnotab, the line number table.\r
-\r
-Code objects store a field named co_lnotab. This is an array of unsigned bytes\r
-disguised as a Python string. It is used to map bytecode offsets to source code\r
-line #s for tracebacks and to identify line number boundaries for line tracing.\r
-\r
-The array is conceptually a compressed list of\r
- (bytecode offset increment, line number increment)\r
-pairs. The details are important and delicate, best illustrated by example:\r
-\r
- byte code offset source code line number\r
- 0 1\r
- 6 2\r
- 50 7\r
- 350 307\r
- 361 308\r
-\r
-Instead of storing these numbers literally, we compress the list by storing only\r
-the increments from one row to the next. Conceptually, the stored list might\r
-look like:\r
-\r
- 0, 1, 6, 1, 44, 5, 300, 300, 11, 1\r
-\r
-The above doesn't really work, but it's a start. Note that an unsigned byte\r
-can't hold negative values, or values larger than 255, and the above example\r
-contains two such values. So we make two tweaks:\r
-\r
- (a) there's a deep assumption that byte code offsets and their corresponding\r
- line #s both increase monotonically, and\r
- (b) if at least one column jumps by more than 255 from one row to the next,\r
- more than one pair is written to the table. In case #b, there's no way to know\r
- from looking at the table later how many were written. That's the delicate\r
- part. A user of co_lnotab desiring to find the source line number\r
- corresponding to a bytecode address A should do something like this\r
-\r
- lineno = addr = 0\r
- for addr_incr, line_incr in co_lnotab:\r
- addr += addr_incr\r
- if addr > A:\r
- return lineno\r
- lineno += line_incr\r
-\r
-(In C, this is implemented by PyCode_Addr2Line().) In order for this to work,\r
-when the addr field increments by more than 255, the line # increment in each\r
-pair generated must be 0 until the remaining addr increment is < 256. So, in\r
-the example above, assemble_lnotab in compile.c should not (as was actually done\r
-until 2.2) expand 300, 300 to\r
- 255, 255, 45, 45,\r
-but to\r
- 255, 0, 45, 255, 0, 45.\r
-\r
-The above is sufficient to reconstruct line numbers for tracebacks, but not for\r
-line tracing. Tracing is handled by PyCode_CheckLineNumber() in codeobject.c\r
-and maybe_call_line_trace() in ceval.c.\r
-\r
-*** Tracing ***\r
-\r
-To a first approximation, we want to call the tracing function when the line\r
-number of the current instruction changes. Re-computing the current line for\r
-every instruction is a little slow, though, so each time we compute the line\r
-number we save the bytecode indices where it's valid:\r
-\r
- *instr_lb <= frame->f_lasti < *instr_ub\r
-\r
-is true so long as execution does not change lines. That is, *instr_lb holds\r
-the first bytecode index of the current line, and *instr_ub holds the first\r
-bytecode index of the next line. As long as the above expression is true,\r
-maybe_call_line_trace() does not need to call PyCode_CheckLineNumber(). Note\r
-that the same line may appear multiple times in the lnotab, either because the\r
-bytecode jumped more than 255 indices between line number changes or because\r
-the compiler inserted the same line twice. Even in that case, *instr_ub holds\r
-the first index of the next line.\r
-\r
-However, we don't *always* want to call the line trace function when the above\r
-test fails.\r
-\r
-Consider this code:\r
-\r
-1: def f(a):\r
-2: while a:\r
-3: print 1,\r
-4: break\r
-5: else:\r
-6: print 2,\r
-\r
-which compiles to this:\r
-\r
- 2 0 SETUP_LOOP 19 (to 22)\r
- >> 3 LOAD_FAST 0 (a)\r
- 6 POP_JUMP_IF_FALSE 17\r
-\r
- 3 9 LOAD_CONST 1 (1)\r
- 12 PRINT_ITEM \r
-\r
- 4 13 BREAK_LOOP \r
- 14 JUMP_ABSOLUTE 3\r
- >> 17 POP_BLOCK \r
-\r
- 6 18 LOAD_CONST 2 (2)\r
- 21 PRINT_ITEM \r
- >> 22 LOAD_CONST 0 (None)\r
- 25 RETURN_VALUE \r
-\r
-If 'a' is false, execution will jump to the POP_BLOCK instruction at offset 17\r
-and the co_lnotab will claim that execution has moved to line 4, which is wrong.\r
-In this case, we could instead associate the POP_BLOCK with line 5, but that\r
-would break jumps around loops without else clauses.\r
-\r
-We fix this by only calling the line trace function for a forward jump if the\r
-co_lnotab indicates we have jumped to the *start* of a line, i.e. if the current\r
-instruction offset matches the offset given for the start of a line by the\r
-co_lnotab. For backward jumps, however, we always call the line trace function,\r
-which lets a debugger stop on every evaluation of a loop guard (which usually\r
-won't be the first opcode in a line).\r
-\r
-Why do we set f_lineno when tracing, and only just before calling the trace\r
-function? Well, consider the code above when 'a' is true. If stepping through\r
-this with 'n' in pdb, you would stop at line 1 with a "call" type event, then\r
-line events on lines 2, 3, and 4, then a "return" type event -- but because the\r
-code for the return actually falls in the range of the "line 6" opcodes, you\r
-would be shown line 6 during this event. This is a change from the behaviour in\r
-2.2 and before, and I've found it confusing in practice. By setting and using\r
-f_lineno when tracing, one can report a line number different from that\r
-suggested by f_lasti on this one occasion where it's desirable.\r
projects / mirror_edk2.git / blobdiff