From 64d885147b73feeeb3785970399def407c72c0d7 Mon Sep 17 00:00:00 2001
From: Rene Rivera <grafikrobot@gmail.com>
Date: Sun, 12 Nov 2023 22:39:30 -0600
Subject: [PATCH] P2546R5 Debugging Support

---
 source/lib-intro.tex |  4 +-
 source/support.tex   |  1 +
 source/utilities.tex | 87 +++++++++++++++++++++++++++++++++++++++++++-
 3 files changed, 90 insertions(+), 2 deletions(-)

diff --git a/source/lib-intro.tex b/source/lib-intro.tex
index 48ce2278a1..85d3410799 100644
--- a/source/lib-intro.tex
+++ b/source/lib-intro.tex
@@ -1132,6 +1132,7 @@
 \tcode{<concepts>} \\
 \tcode{<condition_variable>} \\
 \tcode{<coroutine>} \\
+\tcode{<debugging>} \\
 \tcode{<deque>} \\
 \tcode{<exception>} \\
 \tcode{<execution>} \\
@@ -1139,8 +1140,8 @@
 \tcode{<filesystem>} \\
 \tcode{<flat_map>} \\
 \tcode{<flat_set>} \\
-\tcode{<format>} \\
 \columnbreak
+\tcode{<format>} \\
 \tcode{<forward_list>} \\
 \tcode{<fstream>} \\
 \tcode{<functional>} \\
@@ -1537,6 +1538,7 @@
 \ref{algorithms}         & Algorithms library        & \tcode{<algorithm>}, \tcode{<numeric>} \\ \rowsep
 \ref{c.math}             & Mathematical functions for floating-point types & \tcode{<cmath>} \\ \rowsep
 \ref{atomics}            & Atomics                   & \tcode{<atomic>}           \\ \rowsep
+\ref{debugging}          & Debugging                 & \tcode{<debugging>}        \\ \rowsep
 \end{libsumtab}
 
 \pnum
diff --git a/source/support.tex b/source/support.tex
index fa8589c155..41cfd18ec6 100644
--- a/source/support.tex
+++ b/source/support.tex
@@ -619,6 +619,7 @@
   // \libheader{deque}, \libheader{queue}, \libheader{stack}, \libheader{string}
 #define @\defnlibxname{cpp_lib_copyable_function}@                 202306L // also in \libheader{functional}
 #define @\defnlibxname{cpp_lib_coroutine}@                         201902L // also in \libheader{coroutine}
+#define @\defnlibxname{cpp_lib_debugging}@                         202311L // freestanding, also in \libheader{debugging}
 #define @\defnlibxname{cpp_lib_destroying_delete}@                 201806L // freestanding, also in \libheader{new}
 #define @\defnlibxname{cpp_lib_enable_shared_from_this}@           201603L // also in \libheader{memory}
 #define @\defnlibxname{cpp_lib_endian}@                            201907L // freestanding, also in \libheader{bit}
diff --git a/source/utilities.tex b/source/utilities.tex
index ac73913268..54cb43a0cb 100644
--- a/source/utilities.tex
+++ b/source/utilities.tex
@@ -23,7 +23,8 @@
 \ref{execpol}               & Execution policies                & \tcode{<execution>}   \\ \rowsep
 \ref{charconv}              & Primitive numeric conversions     & \tcode{<charconv>}    \\ \rowsep
 \ref{format}                & Formatting                        & \tcode{<format>}      \\ \rowsep
-\ref{bit}                   & Bit manipulation                  & \tcode{<bit>} \\
+\ref{bit}                   & Bit manipulation                  & \tcode{<bit>} \\ \rowsep
+\ref{debugging}             & Debugging                         & \tcode{<debugging>} \\
 \end{libsumtab}
 
 \rSec1[utility]{Utility components}
@@ -19170,3 +19171,87 @@
 Otherwise, \tcode{endian::native} is not equal
 to either \tcode{endian::big} or \tcode{endian::little}.
 \end{itemdescr}
+
+\rSec1[debugging]{Debugging}
+
+\rSec2[debugging.general]{General}
+
+\pnum
+Subclause \ref{debugging} describes functionality to introspect and
+interact with the execution of the program.
+
+\begin{note}
+The facilities provided by the debugging functionality interact with a program
+that could be tracing the execution of a \Cpp{} program, such as a debugger.
+\end{note}
+
+\rSec2[debugging.syn]{Header \tcode{<debugging>} synopsis}
+
+\indexheader{debugging}%
+\begin{codeblock}
+// all freestanding
+namespace std {
+  // \ref{debugging.utility}, utility
+  void breakpoint() noexcept;
+  void breakpoint_if_debugging() noexcept;
+  bool is_debugger_present() noexcept;
+}
+\end{codeblock}
+
+\rSec2[debugging.utility]{Utility}
+
+\indexlibraryglobal{breakpoint}%
+\begin{itemdecl}
+void breakpoint() noexcept;
+\end{itemdecl}
+
+\begin{itemdescr}
+
+\pnum
+The semantics of this function are \impldef{semantics of \tcode{breakpoint}}.
+
+\begin{note}
+When invoked, the execution of the program temporarily halts and execution is
+handed to the debugger until such a time as: The program is terminated by the
+debugger, or the debugger resumes execution of the program as if the function
+was not invoked.
+\end{note}
+
+\end{itemdescr}
+
+\indexlibraryglobal{breakpoint_if_debugging}%
+\begin{itemdecl}
+void breakpoint_if_debugging() noexcept;
+\end{itemdecl}
+
+\begin{itemdescr}
+
+\pnum
+\effects
+Equivalent to:
+\begin{codeblock}
+if (is_debugger_present()) breakpoint();
+\end{codeblock}
+
+\end{itemdescr}
+
+\indexlibraryglobal{is_debugger_present}%
+\begin{itemdecl}
+bool is_debugger_present() noexcept;
+\end{itemdecl}
+
+\begin{itemdescr}
+
+\pnum
+The semantics of this function are \impldef{semantics of \tcode{is_debugger_present}}.
+
+\begin{note}
+When tracing the execution of a program with a debugger, an implementation
+returns \tcode{true}. An implementation performs an immediate query, as needed,
+to determine if the program is traced by a debugger. On Windows or equivalent
+systems, this can be achieved by calling the \tcode{::IsDebuggerPresent()} Win32
+function. On POSIX, this can be achieved by checking for a tracer parent process,
+with best effort determination that such a tracer parent process is a debugger.
+\end{note}
+
+\end{itemdescr}