Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[doc] Minor documentation updates #737

Merged
merged 2 commits into from
Feb 28, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions manual/techdoc.tex
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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}

Expand Down Expand Up @@ -521,8 +521,8 @@ \subsection{Frame images compression}

\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.
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.

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.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is now always enabled, see 71b54dd. A reword to remove mention of the macro would be better.

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}
10 changes: 5 additions & 5 deletions manual/tracy.tex
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand Down Expand Up @@ -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.
Expand Down