From 54ee3d8a949e9694518141d51b1b8bc94317ac66 Mon Sep 17 00:00:00 2001 From: Simonas Kazlauskas Date: Sat, 18 Sep 2021 14:25:03 +0300 Subject: [PATCH 1/2] Expose TRACY_MANUAL_LIFETIME APIs to C API clients These are extremely useful for ecosystems such as Rust. There are a couple of reasons why: 1. Rust strongly advises against relying on life before/after main, as it is difficult to reason about. Most users working in Rust will generally be quite surprised when encountering this concept. 2. Rust and its package manager makes it easy to use packages (crates) and somewhat less straightforward to consider the implications of including a dependency. In case of the `rust_tracy_client` set of packages, I currently have to warn throughout the documentation of the package that simply adding a dependency on the bindings package is sufficient to potentially accidentally broadcast a lot of information about the instrumented binary to the broader world. This seems like a major footgun given how easy is it to forget about having added this dependency. Ability to manually manage the lifetime of the profiler would be a great solution to these problems. --- TracyC.h | 6 ++++++ client/TracyProfiler.cpp | 12 ++++++++++++ 2 files changed, 18 insertions(+) diff --git a/TracyC.h b/TracyC.h index ea247399..da412104 100644 --- a/TracyC.h +++ b/TracyC.h @@ -101,6 +101,12 @@ struct ___tracy_c_zone_context // This struct, as visible to user, is immutable, so treat it as if const was declared here. typedef /*const*/ struct ___tracy_c_zone_context TracyCZoneCtx; + +#ifdef TRACY_MANUAL_LIFETIME +TRACY_API void ___tracy_startup_profiler(void); +TRACY_API void ___tracy_shutdown_profiler(void); +#endif + TRACY_API uint64_t ___tracy_alloc_srcloc( uint32_t line, const char* source, size_t sourceSz, const char* function, size_t functionSz ); TRACY_API uint64_t ___tracy_alloc_srcloc_name( uint32_t line, const char* source, size_t sourceSz, const char* function, size_t functionSz, const char* name, size_t nameSz ); diff --git a/client/TracyProfiler.cpp b/client/TracyProfiler.cpp index 17062305..b4973791 100644 --- a/client/TracyProfiler.cpp +++ b/client/TracyProfiler.cpp @@ -3602,6 +3602,18 @@ TRACY_API uint64_t ___tracy_alloc_srcloc_name( uint32_t line, const char* source return tracy::Profiler::AllocSourceLocation( line, source, sourceSz, function, functionSz, name, nameSz ); } +# ifdef TRACY_MANUAL_LIFETIME +TRACY_API void ___tracy_startup_profiler( void ) +{ + tracy::StartupProfiler(); +} + +TRACY_API void ___tracy_shutdown_profiler( void ) +{ + tracy::ShutdownProfiler(); +} +# endif + #ifdef __cplusplus } #endif From 173a165a57ce392dd1364465600b9ed08e516337 Mon Sep 17 00:00:00 2001 From: Simonas Kazlauskas Date: Sat, 18 Sep 2021 14:39:19 +0300 Subject: [PATCH 2/2] Add `startup/shutdown_profiler` to the manual Also remove the documentation for the now-gone `___tracy_init_thread` function. --- manual/tracy.tex | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/manual/tracy.tex b/manual/tracy.tex index aa67bba0..c7db9f22 100644 --- a/manual/tracy.tex +++ b/manual/tracy.tex @@ -1793,7 +1793,8 @@ You can collect call stacks of zones and memory allocation events, as described Tracy C API exposes functions with the \texttt{\_\_\_tracy} prefix that may be used to write bindings to other programming languages. Most of the functions available are a counterpart to macros described in section~\ref{capi}. Some functions do not have macro equivalents and are dedicated expressly for binding implementation purposes. This includes the following: \begin{itemize} -\item \texttt{\_\_\_tracy\_init\_thread(void)} +\item \texttt{\_\_\_tracy\_startup\_profiler(void)} +\item \texttt{\_\_\_tracy\_shutdown\_profiler(void)} \item \texttt{\_\_\_tracy\_alloc\_srcloc(uint32\_t line, const char* source, size\_t sourceSz, const char* function, size\_t functionSz)} \item \texttt{\_\_\_tracy\_alloc\_srcloc\_name(uint32\_t line, const char* source, size\_t sourceSz, const char* function, size\_t functionSz, const char* name, size\_t nameSz)} \end{itemize} @@ -1809,11 +1810,6 @@ location}. As these functions do not require for the provided string data to be return, calling code is free to deallocate them at any time afterwards. This way the string lifetime requirements described in section~\ref{textstrings} are relaxed. -Before the \texttt{\_\_\_tracy\_alloc\_*} functions are called on a non-main thread for the first -time, care should be taken to ensure that \texttt{\_\_\_tracy\_init\_thread} has been called first. -The \texttt{\_\_\_tracy\_init\_thread} function initializes per-thread structures Tracy uses and -can be safely called multiple times. - The \texttt{uint64\_t} return value from allocation functions must be passed to one of the zone begin functions: