From 6811415a7a29f1b41c96cd7041f5efddec050235 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9goire=20Roussel?= Date: Tue, 27 Feb 2024 23:03:16 +0100 Subject: [PATCH 1/2] update manual --- manual/techdoc.tex | 10 ++-------- manual/tracy.tex | 10 +++++----- 2 files changed, 7 insertions(+), 13 deletions(-) diff --git a/manual/techdoc.tex b/manual/techdoc.tex index fe54f2a259..d60e16ad86 100644 --- a/manual/techdoc.tex +++ b/manual/techdoc.tex @@ -96,7 +96,7 @@ This document assumes that you have basic knowledge of how the Tracy Profiler works, as the concepts which are already described in the user manual won't be covered here. -The information found in this documentation is intended to give you only a brief overview of the algorithms and data structures used in the profiler. It may be incomplete, cursory, or even plainly wrong. This is not a requirements specification. As usual, the source code is the ultimate place to gain knowledge and insight. You are expected to do your homework. +The information found in this documentation is intended to give you only a brief overview of the algorithms and data structures used in the profiler. It may be obsolete, incomplete, cursory, or even plainly wrong. This is not a requirements specification. As usual, the source code is the ultimate place to gain knowledge and insight. You are expected to do your homework. \end{abstract} \tableofcontents @@ -266,7 +266,7 @@ \subsubsection{Getting the frames} To perform unwinding various OS functions are used: \texttt{RtlWalkFrameChain()}, \texttt{\_Unwind\_Backtrace()}, \texttt{backtrace()}. A list of returned frame pointers is saved in a buffer, which will be later sent to the server. The maximum unwinding depth limit (63 entries) is due to the specifics of the underlying OS functionality. -On some platforms you can define \texttt{TRACE\_CLIENT\_LIBUNWIND\_BACKTRACE} to use libunwind to perform callstack captures, as it might be a faster alternative than the default implementation. If you do, you must compile/link you client against libunwind. See \url{https://github.com/libunwind/libunwind} for more details. +On some platforms you can define \texttt{TRACY\_LIBUNWIND\_BACKTRACE} to use libunwind to perform callstack captures, as it might be a faster alternative than the default implementation. If you do, you must compile/link you client against libunwind. See \url{https://github.com/libunwind/libunwind} for more details. \subsubsection{Decoding stack frames} @@ -519,10 +519,4 @@ \subsection{Frame images compression} The DXT1 compression used to reduce size of the images is a from-scratch implementation of the Extreme DXT Compression\footnote{\url{http://www.cauldron.sk/files/extreme_dxt_compression.pdf}} algorithm. The conversion of natural color index order to DXT1 order is performed on the server side, as it is an invariant operation, without dependencies on the input data. -\subsection{Thread naming} - -Most operating systems don't have adequate support for giving threads arbitrary names. On such systems the \texttt{TRACY\_COLLECT\_THREAD\_NAMES} macro will be defined, which enables storage of thread names in a lock-free list. On subsequent thread name queries this list is used, instead of the system facilities. - -Even if the lock-free list is used, Tracy will also set the thread name using the OS functionality. These names can be then used by debuggers and other external tools. - \end{document} diff --git a/manual/tracy.tex b/manual/tracy.tex index 9b06e7c2b2..c35e5d363a 100644 --- a/manual/tracy.tex +++ b/manual/tracy.tex @@ -1758,7 +1758,7 @@ \subsection{Collecting call stacks} couleur=black!5, logo=\bclampe ]{libunwind} -On some platforms you can define \texttt{TRACE\_CLIENT\_LIBUNWIND\_BACKTRACE} to use libunwind to perform callstack captures as it might be a faster alternative than the default implementation. If you do, you must compile/link you client against libunwind. See \url{https://github.com/libunwind/libunwind} for more details. +On some platforms you can define \texttt{TRACY\_LIBUNWIND\_BACKTRACE} to use libunwind to perform callstack captures as it might be a faster alternative than the default implementation. If you do, you must compile/link you client against libunwind. See \url{https://github.com/libunwind/libunwind} for more details. \end{bclogo} \subsubsection{Debugging symbols} @@ -1840,17 +1840,17 @@ \subsubsection{Debugging symbols} \paragraph{Offline symbol resolution} By default, tracy client resolves callstack symbols in a background thread at runtime. -This process requires that tracy client load symbols for the shared libraries +This process requires that tracy client load symbols for the shared libraries involved, which requires additial memory allocations, and potential impact runtime performance if a lot of symbol queries are involved. As an alternative to to runtime symbol resolution, we can set the environment variable \texttt{TRACY\_SYMBOL\_OFFLINE\_RESOLVE} to 1 and instead have tracy client only resolve the minimal set of info required for offline resolution (a shared library path and an offset into that shared library). - + The generated tracy capture will have callstack frames symbols showing \texttt{[unresolved]}. The \texttt{update} tool can be used to load that capture, perform symbol resolution offline (by passing \texttt{-r}) and writing out a new capture with symbols resolved. -By default \texttt{update} will use the original shared libraries paths that were recorded -in the capture (which assumes running in the same machine or a machine with identical +By default \texttt{update} will use the original shared libraries paths that were recorded +in the capture (which assumes running in the same machine or a machine with identical filesystem setup as the one used to run the tracy instrumented application). You can do path substitution with the \texttt{-p} option to perform any number of path substitions in order to use symbols located elsewhere. From 6d2cae28429f578f918c4e47a7b83b8c0c2d4308 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9goire=20Roussel?= Date: Tue, 27 Feb 2024 23:27:06 +0100 Subject: [PATCH 2/2] Update Thread naming section --- manual/techdoc.tex | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/manual/techdoc.tex b/manual/techdoc.tex index d60e16ad86..6d0d7675c4 100644 --- a/manual/techdoc.tex +++ b/manual/techdoc.tex @@ -519,4 +519,10 @@ \subsection{Frame images compression} The DXT1 compression used to reduce size of the images is a from-scratch implementation of the Extreme DXT Compression\footnote{\url{http://www.cauldron.sk/files/extreme_dxt_compression.pdf}} algorithm. The conversion of natural color index order to DXT1 order is performed on the server side, as it is an invariant operation, without dependencies on the input data. +\subsection{Thread naming} + +Most operating systems don't have adequate support for giving threads arbitrary names. Tracy supplements this by providing an alternative way via an internal lock-free list. On subsequent thread name queries this list is used, instead of the system facilities. + +When `setThreadName()` is called, Tracy will also set the thread name using the OS functionality when possible. These names can be then used by debuggers and other external tools. + \end{document}