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