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 engine         engine in which to perform the profiling
60  * \param module_name    name recorded in the profile
61  * \param interval_nanos intended sampling interval in nanoseconds recorded in
62  *                       the profile
63  * \param modules        modules and associated names that will appear in
64  *                       captured stack traces, pointer to the first element
65  * \param modules_len    count of elements in `modules`
66  *
67  * \return Created profiler that is owned by the caller.
68  *
69  * This function does not take ownership of the arguments.
70  *
71  * For more information see the Rust documentation at:
72  * https://docs.wasmtime.dev/api/wasmtime/struct.GuestProfiler.html#method.new
73  */
74 WASM_API_EXTERN /* own */ wasmtime_guestprofiler_t *wasmtime_guestprofiler_new(
75     const wasm_engine_t *engine, const wasm_name_t *module_name,
76     uint64_t interval_nanos, const wasmtime_guestprofiler_modules_t *modules,
77     size_t modules_len);
78 
79 /**
80  * \brief Add a sample to the profile.
81  *
82  * \param guestprofiler the profiler the sample is being added to
83  * \param store         store that is being used to collect the backtraces
84  * \param delta_nanos   CPU time in nanoseconds that was used by this guest
85  *                      since the previous sample
86  *
87  * Zero can be passed as `delta_nanos` if recording CPU usage information
88  * is not needed.
89  * This function does not take ownership of the arguments.
90  *
91  * For more information see the Rust documentation at:
92  * https://docs.wasmtime.dev/api/wasmtime/struct.GuestProfiler.html#method.sample
93  */
94 WASM_API_EXTERN void
95 wasmtime_guestprofiler_sample(wasmtime_guestprofiler_t *guestprofiler,
96                               const wasmtime_store_t *store,
97                               uint64_t delta_nanos);
98 
99 /**
100  * \brief Writes out the captured profile.
101  *
102  * \param guestprofiler the profiler which is being finished and deleted
103  * \param out           pointer to where #wasm_byte_vec_t containing generated
104  *                      file will be written
105  *
106  * \return Returns #wasmtime_error_t owned by the caller in case of error,
107  * `NULL` otherwise.
108  *
109  * This function takes ownership of `guestprofiler`, even when error is
110  * returned.
111  * Only when returning without error `out` is filled with #wasm_byte_vec_t owned
112  * by the caller.
113  *
114  * For more information see the Rust documentation at:
115  * https://docs.wasmtime.dev/api/wasmtime/struct.GuestProfiler.html#method.finish
116  */
117 WASM_API_EXTERN /* own */ wasmtime_error_t *
118 wasmtime_guestprofiler_finish(/* own */ wasmtime_guestprofiler_t *guestprofiler,
119                               /* own */ wasm_byte_vec_t *out);
120 
121 #ifdef __cplusplus
122 } // extern "C"
123 #endif
124 
125 #endif // WASMTIME_FEATURE_PROFILING
126 
127 #endif // WASMTIME_PROFILING_H
128