README.org

September 29, 2024 ยท View on GitHub

#+startup: showall #+TITLE: Brake: an extended BREAK facility for Common Lisp #+PROPERTY: header-args :results output #+OPTIONS: toc:nil #+INFOJS_OPT: view:showall toc:nil #+LATEX_CLASS: article #+LATEX_CLASS_OPTIONS: [a4paper, 11pt] #+LaTeX_HEADER: \usepackage{minted} #+LaTeX_HEADER: \usemintedstyle{common-lisp, fontsize=\scriptsize} #+LaTeX_HEADER: \usepackage[left=0.6in, right=0.6in]{geometry} #+LATEX_HEADER: \usepackage{fancyhdr} #+LATEX_HEADER: \pagestyle{fancyplain} #+LATEX_HEADER: \lhead{} #+LATEX_HEADER: \rhead{} #+LATEX_HEADER: \lfoot{} #+LATEX_HEADER: \rfoot{} #+HTML_HEAD:

  • Summary

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.

  • Multi-threading

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.

  • Definitions

** (brake &optional /tag-or-sexp/ /step/ /sexp/)

Sets a breakpoint.

Example: (brake)

Example: (if (oddp x) (brake (branch-odd)) (branch-even))

Example: (brake :walk 4)

** (brake-when /conditional/ &optional /tag-or-sexp/ /step/ /sexp/)

Sets a conditional breakpoint.

** (mark /tag/ /step/ &optional /sexp/)

Marks the step as reached in the control flow but does not interrupt execution.

** (mark-when /conditional/ &optional /tag-or-sexp/ /step/ /sexp/)

Sets a conditional mark.

** (brake-enable &rest /tags/)

** (brake-disable &rest /tags/)

Enable or disable breakpoints of specified tags. Acts on all tags if none is supplied.

** (clear-brake-points)

Clear all tagged breakpoints. Useful when you remove breakpoints in the code, followed by recompilation.

** (clear-brake-tag /tag/)

Clear the steps for the tag and disable it.

** (report-brakes)

Print the summary of all tagged brakes state.

** (brake-trace /tag/ &rest /tags/)

Print a trace of brakes or marks reached into trace-output.

** (brake-untrace &rest /tags/)

Untrace either specific tags or all tags if no argument is supplied.