Ignore breakpoint for a specified number of iterations. (#19157)

* Implement new debugger command `:ignore` to set an `ignore count`
  for a specified breakpoint.
* Allow new optional parameter on `:continue` command to set an
  `ignore count` for the current breakpoint.

* In the Interpreter replace the current `Word8` BreakArray with
  an `Int` array.
* Change semantics of values in `BreakArray` to:
   n < 0  : Breakpoint is disabled.
   n == 0 : Breakpoint is enabled.
   n > 0  : Breakpoint is enabled, but ignore next `n` iterations.
* Rewrite `:enable`/`:disable` processing as a special case of `:ignore`.
* Remove references to `BreakArray` from `ghc/UI.hs`.

2 files changed, 34 insertions, 7 deletions

diff --git a/docs/users_guide/9.2.1-notes.rst b/docs/users_guide/9.2.1-notes.rst
index 6e36f1dbeb..4fdf6b070b 100644
--- a/docs/users_guide/9.2.1-notes.rst
+++ b/docs/users_guide/9.2.1-notes.rst
@@ -125,9 +125,6 @@ Compiler
   For more details see :ghc-flag:`-finline-generics` and
   :ghc-flag:`-finline-generics-aggressively`.
 
-- GHCi's ``:kind!`` command now expands through type synonyms in addition to type
-  families. See :ghci-cmd:`:kind`.
-
 - GHC now supports a flag, :ghc-flag:`-fprof-callers=⟨name⟩`, for requesting
   that the compiler automatically insert cost-centres on all call-sites of
   the named function.
@@ -147,6 +144,9 @@ Compiler
 GHCi
 ~~~~
 
+- GHCi's ``:kind!`` command now expands through type synonyms in addition to
+  type families. See :ghci-cmd:`:kind`.
+
 - GHCi's :ghci-cmd:`:edit` command now looks for an editor in
   the :envvar:`VISUAL` environment variable before
   :envvar:`EDITOR`, following UNIX convention.
@@ -156,6 +156,13 @@ GHCi
   ``$HOME/.ghc`` is found it will fallback to the old paths to give you
   time to migrate. This fallback will be removed in three releases.
 
+- New debugger command :ghci-cmd:`:ignore` to set an ``ignore count`` for a
+  specified breakpoint.  The next ``ignore count`` times the program hits this
+  breakpoint, the breakpoint is ignored, and the program doesn't stop.
+
+- New optional parameter added to the command :ghci-cmd:`:continue` to set the
+  ``ignore count`` for the current breakpoint.
+
 Runtime system
 ~~~~~~~~~~~~~~
 
diff --git a/docs/users_guide/ghci.rst b/docs/users_guide/ghci.rst
index ac9f33f362..5ffe323f5f 100644
--- a/docs/users_guide/ghci.rst
+++ b/docs/users_guide/ghci.rst
@@ -2347,10 +2347,14 @@ commonly used commands.
         ghci> :complete repl 5-10 "map"
         0 3 ""
 
-.. ghci-cmd:: :continue
+.. ghci-cmd:: :continue; [⟨ignoreCount⟩]
 
     Continue the current evaluation, when stopped at a breakpoint.
 
+    If an ``⟨ignoreCount⟩`` is specified, the program will ignore
+    the current breakpoint for the next ``⟨ignoreCount⟩`` iterations.
+    See command :ghci-cmd:`:ignore`.
+
 .. ghci-cmd:: :ctags; [⟨filename⟩]
 
     Generates a "tags" file for Vi-style editors (:ghci-cmd:`:ctags`) or
@@ -2459,7 +2463,8 @@ commonly used commands.
 
     Enable one or more disabled breakpoints by number (use :ghci-cmd:`:show breaks` to
     see the number and state of each breakpoint). The ``*`` form enables all the
-    disabled breakpoints.
+    disabled breakpoints. Enabling a break point will reset its ``ignore count``
+    to 0. (See :ghci-cmd:`:ignore`)
 
 .. ghci-cmd:: :etags
 
@@ -2577,6 +2582,20 @@ commonly used commands.
     current module if omitted). This includes the trust type of the
     module and its containing package.
 
+.. ghci-cmd:: :ignore; ⟨break⟩ ⟨ignoreCount⟩
+
+    Set the ignore count of the breakpoint with number ``⟨break⟩`` to
+    ``⟨ignoreCount⟩``.
+
+    The next ``⟨ignoreCount⟩`` times the program hits the breakpoint
+    ``⟨break⟩``, this breakpoint is ignored and the program doesn't
+    stop. Every time the breakpoint is ignored, the ``ignore count``
+    is decremented by 1. When the ``ignore count`` is zero, the program
+    again stops at the break point.
+
+    You can also specify an ``⟨ignoreCount⟩`` on a :ghci-cmd:`:continue`
+    command when you resume execution of your program.
+
 .. ghci-cmd:: :kind;[!] ⟨type⟩
 
     Infers and prints the kind of ⟨type⟩. The latter can be an arbitrary
@@ -2866,8 +2885,9 @@ commonly used commands.
         *ghci> :def cond \expr -> return (":cmd if (" ++ expr ++ ") then return \"\" else return \":continue\"")
         *ghci> :set stop 0 :cond (x < 3)
 
-    Ignoring breakpoints for a specified number of iterations is also
-    possible using similar techniques.
+    To ignore breakpoints for a specified number of iterations use
+    the :ghci-cmd:`:ignore` or the ``⟨ignoreCount⟩`` parameter of the
+    :ghci-cmd:`:continue` command.
 
 .. ghci-cmd:: :seti; [⟨option⟩ ...]