This project augments standard Common Lisp BREAK facility with several conveniences.
- BRAKE in its simplest form with no arguments works as BREAK. However it can also wrap an s-expression, allowing for convenient breakpoints for instance in IF special operators.
- BRAKE can also be sequenced with two arguments: TAG and STEP. A tag keyword groups a number of BRAKE points across code sequenced by their STEP numbers. BRAKE points are activated only if they are either the first in the sequence or if a preceding step had already been reached. This allows for somewhat more manageable debugging of complex iterations, recursive functions and multi-threaded code.
- BRAKE-WHEN is an extended from with conditional clause.
- MARK has the semantics of tagged BRAKE, except it does not interrupt the execution.
When tagged, both BRAKE(-WHEN) and MARK allow to enable tracing.
Disclaimer: this is still an experimental project, subject to changes. As it is more complex than the simple BREAK there are almost certainly scenarios where BRAKE would work counter-intuitively or fail.
BRAKE is not thread-safe per se as it uses shared state. However there’s hope to make it usable for debugging race conditions and other multi-threading issues.
Sets a breakpoint.
Example: (brake)
Example: (if (oddp x) (brake (branch-odd)) (branch-even))
Example: (brake :walk 4)
Sets a conditional breakpoint.
Marks the step as reached in the control flow but does not interrupt execution.
Sets a conditional mark.
Enable or disable breakpoints of specified tags. Acts on all tags if none is supplied.
Clear all tagged breakpoints. Useful when you remove breakpoints in the code, followed by recompilation.
Clear the steps for the tag and disable it.
Print the summary of all tagged brakes state.
Print a trace of brakes or marks reached into *debug-io*.
Untrace either specific tags or all tags if no argument is supplied.