P2546R5 Debugging Support

Editorial notes: entries to the C++ headers table and the "new
headers" compatibility statement have been added.

Author: grafikrobot

source/compatibility.tex

@@ -82,6 +82,7 @@
 New functionality.
 \effect
 The following \Cpp{} headers are new:
+\libheaderref{debugging},
 \libheaderrefx{hazard_pointer}{hazard.pointer.syn},
 \libheaderref{rcu}, and
 \libheaderrefx{text_encoding}{text.encoding.syn}.

source/lib-intro.tex

@@ -1132,15 +1132,16 @@
 \tcode{<concepts>} \\
 \tcode{<condition_variable>} \\
 \tcode{<coroutine>} \\
+\tcode{<debugging>} \\
 \tcode{<deque>} \\
 \tcode{<exception>} \\
 \tcode{<execution>} \\
 \tcode{<expected>} \\
 \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

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}

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}