1 /** 2 * \file wasmtime/store.h 3 * 4 * Wasmtime definition of a "store". 5 */ 6 7 #ifndef WASMTIME_STORE_H 8 #define WASMTIME_STORE_H 9 10 #include <wasi.h> 11 #include <wasm.h> 12 #include <wasmtime/conf.h> 13 #include <wasmtime/error.h> 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 /** 20 * \typedef wasmtime_store_t 21 * \brief Convenience alias for #wasmtime_store_t 22 * 23 * \struct wasmtime_store 24 * \brief Storage of WebAssembly objects 25 * 26 * A store is the unit of isolation between WebAssembly instances in an 27 * embedding of Wasmtime. Values in one #wasmtime_store_t cannot flow into 28 * another #wasmtime_store_t. Stores are cheap to create and cheap to dispose. 29 * It's expected that one-off stores are common in embeddings. 30 * 31 * Objects stored within a #wasmtime_store_t are referenced with integer handles 32 * rather than interior pointers. This means that most APIs require that the 33 * store be explicitly passed in, which is done via #wasmtime_context_t. It is 34 * safe to move a #wasmtime_store_t to any thread at any time. A store generally 35 * cannot be concurrently used, however. 36 */ 37 typedef struct wasmtime_store wasmtime_store_t; 38 39 /** 40 * \typedef wasmtime_context_t 41 * \brief Convenience alias for #wasmtime_context 42 * 43 * \struct wasmtime_context 44 * \brief An interior pointer into a #wasmtime_store_t which is used as 45 * "context" for many functions. 46 * 47 * This context pointer is used pervasively throughout Wasmtime's API. This can 48 * be acquired from #wasmtime_store_context or #wasmtime_caller_context. The 49 * context pointer for a store is the same for the entire lifetime of a store, 50 * so it can safely be stored adjacent to a #wasmtime_store_t itself. 51 * 52 * Usage of a #wasmtime_context_t must not outlive the original 53 * #wasmtime_store_t. Additionally #wasmtime_context_t can only be used in 54 * situations where it has explicitly been granted access to doing so. For 55 * example finalizers cannot use #wasmtime_context_t because they are not given 56 * access to it. 57 */ 58 typedef struct wasmtime_context wasmtime_context_t; 59 60 /** 61 * \brief Creates a new store within the specified engine. 62 * 63 * \param engine the compilation environment with configuration this store is 64 * connected to 65 * \param data user-provided data to store, can later be acquired with 66 * #wasmtime_context_get_data. 67 * \param finalizer an optional finalizer for `data` 68 * 69 * This function creates a fresh store with the provided configuration settings. 70 * The returned store must be deleted with #wasmtime_store_delete. 71 */ 72 WASM_API_EXTERN wasmtime_store_t *wasmtime_store_new(wasm_engine_t *engine, 73 void *data, 74 void (*finalizer)(void *)); 75 76 /** 77 * \brief Returns the interior #wasmtime_context_t pointer to this store 78 */ 79 WASM_API_EXTERN wasmtime_context_t * 80 wasmtime_store_context(wasmtime_store_t *store); 81 82 /** 83 * \brief Provides limits for a store. Used by hosts to limit resource 84 * consumption of instances. Use negative value to keep the default value 85 * for the limit. 86 * 87 * \param store store where the limits should be set. 88 * \param memory_size the maximum number of bytes a linear memory can grow to. 89 * Growing a linear memory beyond this limit will fail. By default, 90 * linear memory will not be limited. 91 * \param table_elements the maximum number of elements in a table. 92 * Growing a table beyond this limit will fail. By default, table elements 93 * will not be limited. 94 * \param instances the maximum number of instances that can be created 95 * for a Store. Module instantiation will fail if this limit is exceeded. 96 * This value defaults to 10,000. 97 * \param tables the maximum number of tables that can be created for a Store. 98 * Module instantiation will fail if this limit is exceeded. This value 99 * defaults to 10,000. 100 * \param memories the maximum number of linear memories that can be created 101 * for a Store. Instantiation will fail with an error if this limit is exceeded. 102 * This value defaults to 10,000. 103 * 104 * Use any negative value for the parameters that should be kept on 105 * the default values. 106 * 107 * Note that the limits are only used to limit the creation/growth of 108 * resources in the future, this does not retroactively attempt to apply 109 * limits to the store. 110 */ 111 WASM_API_EXTERN void wasmtime_store_limiter(wasmtime_store_t *store, 112 int64_t memory_size, 113 int64_t table_elements, 114 int64_t instances, int64_t tables, 115 int64_t memories); 116 117 /** 118 * \brief Deletes a store. 119 */ 120 WASM_API_EXTERN void wasmtime_store_delete(wasmtime_store_t *store); 121 122 /** 123 * \brief Returns the user-specified data associated with the specified store 124 */ 125 WASM_API_EXTERN void * 126 wasmtime_context_get_data(const wasmtime_context_t *context); 127 128 /** 129 * \brief Overwrites the user-specified data associated with this store. 130 * 131 * Note that this does not execute the original finalizer for the provided data, 132 * and the original finalizer will be executed for the provided data when the 133 * store is deleted. 134 */ 135 WASM_API_EXTERN void wasmtime_context_set_data(wasmtime_context_t *context, 136 void *data); 137 138 /** 139 * \brief Perform garbage collection within the given context. 140 * 141 * Garbage collects `externref`s that are used within this store. Any 142 * `externref`s that are discovered to be unreachable by other code or objects 143 * will have their finalizers run. 144 * 145 * The `context` argument must not be NULL. 146 */ 147 WASM_API_EXTERN wasmtime_error_t * 148 wasmtime_context_gc(wasmtime_context_t *context); 149 150 /** 151 * \brief Set fuel to this context's store for wasm to consume while executing. 152 * 153 * For this method to work fuel consumption must be enabled via 154 * #wasmtime_config_consume_fuel_set. By default a store starts with 0 fuel 155 * for wasm to execute with (meaning it will immediately trap). 156 * This function must be called for the store to have 157 * some fuel to allow WebAssembly to execute. 158 * 159 * Note that when fuel is entirely consumed it will cause wasm to trap. 160 * 161 * If fuel is not enabled within this store then an error is returned. If fuel 162 * is successfully added then NULL is returned. 163 */ 164 WASM_API_EXTERN wasmtime_error_t * 165 wasmtime_context_set_fuel(wasmtime_context_t *store, uint64_t fuel); 166 167 /** 168 * \brief Returns the amount of fuel remaining in this context's store. 169 * 170 * If fuel consumption is not enabled via #wasmtime_config_consume_fuel_set 171 * then this function will return an error. Otherwise `NULL` is returned and the 172 * fuel parameter is filled in with fuel consumed so far. 173 * 174 * Also note that fuel, if enabled, must be originally configured via 175 * #wasmtime_context_set_fuel. 176 */ 177 WASM_API_EXTERN wasmtime_error_t * 178 wasmtime_context_get_fuel(const wasmtime_context_t *context, uint64_t *fuel); 179 180 #ifdef WASMTIME_FEATURE_WASI 181 182 /** 183 * \brief Configures WASI state within the specified store. 184 * 185 * This function is required if #wasmtime_linker_define_wasi is called. This 186 * will configure the WASI state for instances defined within this store to the 187 * configuration specified. 188 * 189 * This function does not take ownership of `context` but it does take ownership 190 * of `wasi`. The caller should no longer use `wasi` after calling this function 191 * (even if an error is returned). 192 */ 193 WASM_API_EXTERN wasmtime_error_t * 194 wasmtime_context_set_wasi(wasmtime_context_t *context, wasi_config_t *wasi); 195 196 #endif // WASMTIME_FEATURE_WASI 197 198 /** 199 * \brief Configures the relative deadline at which point WebAssembly code will 200 * trap or invoke the callback function. 201 * 202 * This function configures the store-local epoch deadline after which point 203 * WebAssembly code will trap or invoke the callback function. 204 * 205 * See also #wasmtime_config_epoch_interruption_set and 206 * #wasmtime_store_epoch_deadline_callback. 207 */ 208 WASM_API_EXTERN void 209 wasmtime_context_set_epoch_deadline(wasmtime_context_t *context, 210 uint64_t ticks_beyond_current); 211 212 /// \brief An enum for the behavior before extending the epoch deadline. 213 typedef uint8_t wasmtime_update_deadline_kind_t; 214 /// \brief Directly continue to updating the deadline and executing WebAssembly. 215 #define WASMTIME_UPDATE_DEADLINE_CONTINUE 0 216 /// \brief Yield control (via async support) then update the deadline. 217 #define WASMTIME_UPDATE_DEADLINE_YIELD 1 218 219 /** 220 * \brief Configures epoch deadline callback to C function. 221 * 222 * This function configures a store-local callback function that will be 223 * called when the running WebAssembly function has exceeded its epoch 224 * deadline. That function can: 225 * - return a #wasmtime_error_t to terminate the function 226 * - set the delta argument and return NULL to update the 227 * epoch deadline delta and resume function execution. 228 * - set the delta argument, update the epoch deadline, 229 * set update_kind to WASMTIME_UPDATE_DEADLINE_YIELD, 230 * and return NULL to yield (via async support) and 231 * resume function execution. 232 * 233 * To use WASMTIME_UPDATE_DEADLINE_YIELD async support must be enabled 234 * for this store. 235 * 236 * See also #wasmtime_config_epoch_interruption_set and 237 * #wasmtime_context_set_epoch_deadline. 238 */ 239 WASM_API_EXTERN void wasmtime_store_epoch_deadline_callback( 240 wasmtime_store_t *store, 241 wasmtime_error_t *(*func)(wasmtime_context_t *context, void *data, 242 uint64_t *epoch_deadline_delta, 243 wasmtime_update_deadline_kind_t *update_kind), 244 void *data, void (*finalizer)(void *)); 245 246 #ifdef __cplusplus 247 } // extern "C" 248 #endif 249 250 #endif // WASMTIME_STORE_H 251