1 /**
2  * \file wasmtime/profiling.h
3  *
4  * \brief API for Wasmtime guest profiler
5  */
6 
7 #ifndef WASMTIME_PROFILING_H
8 #define WASMTIME_PROFILING_H
9 
10 #include <wasm.h>
11 #include <wasmtime/conf.h>
12 #include <wasmtime/error.h>
13 #include <wasmtime/module.h>
14 #include <wasmtime/store.h>
15 
16 #ifdef WASMTIME_FEATURE_PROFILING
17 
18 #ifdef __cplusplus
19 extern "C" {
20 #endif
21 
22 /**
23  * \brief Collects basic profiling data for a single WebAssembly guest.
24  *
25  * To use this, you’ll need to arrange to call #wasmtime_guestprofiler_sample at
26  * regular intervals while the guest is on the stack. The most straightforward
27  * way to do that is to call it from a callback registered with
28  * #wasmtime_store_epoch_deadline_callback.
29  *
30  * For more information see the Rust documentation at:
31  * https://docs.wasmtime.dev/api/wasmtime/struct.GuestProfiler.html
32  */
33 typedef struct wasmtime_guestprofiler wasmtime_guestprofiler_t;
34 
35 /**
36  * \brief Deletes profiler without finishing it.
37  *
38  * \param guestprofiler profiler that is being deleted
39  */
40 WASM_API_EXTERN void wasmtime_guestprofiler_delete(
41     /* own */ wasmtime_guestprofiler_t *guestprofiler);
42 
43 /**
44  * \typedef wasmtime_guestprofiler_modules_t
45  * \brief Alias to #wasmtime_guestprofiler_modules
46  *
47  * \struct #wasmtime_guestprofiler_modules
48  * \brief Tuple of name and module for passing into #wasmtime_guestprofiler_new.
49  */
50 typedef struct wasmtime_guestprofiler_modules {
51   const wasm_name_t *name; //!< Name recorded in the profile.
52   const wasmtime_module_t
53       *mod; //!< Module that is being allowed to appear in captured stack trace.
54 } wasmtime_guestprofiler_modules_t;
55 
56 /**
57  * \brief Begin profiling a new guest.
58  *
59  * \param module_name    name recorded in the profile
60  * \param interval_nanos intended sampling interval in nanoseconds recorded in
61  *                       the profile
62  * \param modules        modules and associated names that will appear in
63  *                       captured stack traces, pointer to the first element
64  * \param modules_len    count of elements in `modules`
65  *
66  * \return Created profiler that is owned by the caller.
67  *
68  * This function does not take ownership of the arguments.
69  *
70  * For more information see the Rust documentation at:
71  * https://docs.wasmtime.dev/api/wasmtime/struct.GuestProfiler.html#method.new
72  */
73 WASM_API_EXTERN /* own */ wasmtime_guestprofiler_t *wasmtime_guestprofiler_new(
74     const wasm_name_t *module_name, uint64_t interval_nanos,
75     const wasmtime_guestprofiler_modules_t *modules, size_t modules_len);
76 
77 /**
78  * \brief Add a sample to the profile.
79  *
80  * \param guestprofiler the profiler the sample is being added to
81  * \param store         store that is being used to collect the backtraces
82  * \param delta_nanos   CPU time in nanoseconds that was used by this guest
83  *                      since the previous sample
84  *
85  * Zero can be passed as `delta_nanos` if recording CPU usage information
86  * is not needed.
87  * This function does not take ownership of the arguments.
88  *
89  * For more information see the Rust documentation at:
90  * https://docs.wasmtime.dev/api/wasmtime/struct.GuestProfiler.html#method.sample
91  */
92 WASM_API_EXTERN void
93 wasmtime_guestprofiler_sample(wasmtime_guestprofiler_t *guestprofiler,
94                               const wasmtime_store_t *store,
95                               uint64_t delta_nanos);
96 
97 /**
98  * \brief Writes out the captured profile.
99  *
100  * \param guestprofiler the profiler which is being finished and deleted
101  * \param out           pointer to where #wasm_byte_vec_t containing generated
102  *                      file will be written
103  *
104  * \return Returns #wasmtime_error_t owned by the caller in case of error,
105  * `NULL` otherwise.
106  *
107  * This function takes ownership of `guestprofiler`, even when error is
108  * returned.
109  * Only when returning without error `out` is filled with #wasm_byte_vec_t owned
110  * by the caller.
111  *
112  * For more information see the Rust documentation at:
113  * https://docs.wasmtime.dev/api/wasmtime/struct.GuestProfiler.html#method.finish
114  */
115 WASM_API_EXTERN /* own */ wasmtime_error_t *
116 wasmtime_guestprofiler_finish(/* own */ wasmtime_guestprofiler_t *guestprofiler,
117                               /* own */ wasm_byte_vec_t *out);
118 
119 #ifdef __cplusplus
120 } // extern "C"
121 #endif
122 
123 #endif // WASMTIME_FEATURE_PROFILING
124 
125 #endif // WASMTIME_PROFILING_H
126