From bf475a4cc2e89e4fa7f611d6801b6f92ab2e073a Mon Sep 17 00:00:00 2001 From: Bartosz Taudul Date: Sat, 4 Aug 2018 22:49:16 +0200 Subject: [PATCH] Describe how text strings in macros are handled. --- manual/tracy.tex | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/manual/tracy.tex b/manual/tracy.tex index 98b5a5d6..1227b5b5 100644 --- a/manual/tracy.tex +++ b/manual/tracy.tex @@ -179,6 +179,16 @@ Be aware that even if you already have thread naming functionality implemented, With the aforementioned steps you will be able to connect to the profiled program, but there won't be any data collection performed. In order to begin profiling, Tracy requires that you manually instrument the application\footnote{Automatic tracing of every entered function is not feasible due to the amount of data that would generate.}. All the user-facing interface is contained in the \texttt{tracy/Tracy.hpp} header file. +\subsection{Handling text strings} + +When dealing with Tracy macros, you will encounter two ways of providing string data for the profiler. In both cases you should pass \texttt{const char*} pointers, but there are differences in expected life-time of the pointed data. + +\begin{enumerate} +\item When a macro only accepts a pointer (for example: \texttt{TracyMessageL(text)}), the provided string data must be accessible at any time in program execution (\emph{this also includes the time after exiting the \texttt{main} function}). The string also cannot be changed. This basically means that the only option is to use a string literal (e.g.: \texttt{TracyMessageL("Hello")}). + +\item If there's a string pointer with a size parameter (for example: \texttt{TracyMessage(text, size)}), the profiler will allocate an internal temporary buffer to store the data. The pointed-to data is not used afterwards. You should be aware that allocating and copying memory involved in this operation has a time cost. +\end{enumerate} + \subsection{Marking frames} \begin{bclogo}[ @@ -197,11 +207,11 @@ In some cases you may want to track more than one set of frames in your program. \subsection{Marking zones} -To record a zone's\footnote{A \texttt{zone} represents the life-time of a special on-stack profiler variable. Typically it would exist for the duration of a whole scope of the profiled function, but you also can measure time spent in scopes of a for-loop, or an if-branch.} execution time add the \texttt{ZoneScoped} macro at the beginning of the scope you want to measure. This will automatically record function name, source file name and location. Optionally you may use the \texttt{ZoneScopedC(0xRRGGBB)} macro to set a custom color for the zone. Note that the color value will be constant in the recording (don't try to parametrize it). You may also set a custom name for the zone, using the \texttt{ZoneScopedN(name)} macro, where name is a string literal. Color and name may be combined by using the \texttt{ZoneScopedNC(name, color)} macro. +To record a zone's\footnote{A \texttt{zone} represents the life-time of a special on-stack profiler variable. Typically it would exist for the duration of a whole scope of the profiled function, but you also can measure time spent in scopes of a for-loop, or an if-branch.} execution time add the \texttt{ZoneScoped} macro at the beginning of the scope you want to measure. This will automatically record function name, source file name and location. Optionally you may use the \texttt{ZoneScopedC(0xRRGGBB)} macro to set a custom color for the zone. Note that the color value will be constant in the recording (don't try to parametrize it). You may also set a custom name for the zone, using the \texttt{ZoneScopedN(name)} macro. Color and name may be combined by using the \texttt{ZoneScopedNC(name, color)} macro. -Use the \texttt{ZoneText(const char* text, size\_t size)} macro to add a custom text string that will be displayed along the zone information (for example, name of the file you are opening). Note that every time \texttt{ZoneText} is invoked, a memory allocation is performed to store an internal copy of the data. The provided string is not used by Tracy after \texttt{ZoneText} returns. +Use the \texttt{ZoneText(text, size)} macro to add a custom text string that will be displayed along the zone information (for example, name of the file you are opening). -If you want to set zone name on a per-call basis, you may do so using the \texttt{ZoneName(text, size)} macro. +If you want to set zone name on a per-call basis, you may do so using the \texttt{ZoneName(text, size)} macro. This name won't be used for in the process of grouping the zones for statistical purposes. \begin{bclogo}[ noborder=true, @@ -252,7 +262,7 @@ Tracy is able to capture and draw numeric value changes over time. You may use i \subsection{Message log} -Fast navigation in large data sets and correlation of zones with what was happening in application may be difficult. To ease these issues Tracy provides a message log functionality. You can send messages (for example, your typical debug output) using the \texttt{TracyMessage(text, size)} macro (Tracy will allocate memory for message storage). Alternatively, use \texttt{TracyMessageL(text)} for string literal messages. Messages are displayed on a chronological list and in the zone view. +Fast navigation in large data sets and correlation of zones with what was happening in application may be difficult. To ease these issues Tracy provides a message log functionality. You can send messages (for example, your typical debug output) using the \texttt{TracyMessage(text, size)} macro. Alternatively, use \texttt{TracyMessageL(text)} for string literal messages. \subsection{Memory profiling}