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