Add Store::consume_fuel to manually consume fuel (#3352)

This can be useful for host functions that want to consume fuel to
reflect their relative cost. Additionally it's a relatively easy
addition to have and someone's asking for it!

Closes #3315

crates/c-api/include/wasmtime/store.h

@@ -139,6 +139,20 @@ WASM_API_EXTERN wasmtime_error_t *wasmtime_context_add_fuel(wasmtime_context_t *
  */
 WASM_API_EXTERN bool wasmtime_context_fuel_consumed(const wasmtime_context_t *context, uint64_t *fuel);
 
+/**
+ * \brief Attempt to manually consume fuel from the store.
+ *
+ * If fuel consumption is not enabled via #wasmtime_config_consume_fuel_set then
+ * this function will return an error. Otherwise this will attempt to consume
+ * the specified amount of `fuel` from the store. If successful the remaining
+ * amount of fuel is stored into `remaining`. If `fuel` couldn't be consumed
+ * then an error is returned.
+ *
+ * Also note that fuel, if enabled, must be originally configured via
+ * #wasmtime_context_add_fuel.
+ */
+WASM_API_EXTERN wasmtime_error_t *wasmtime_context_consume_fuel(wasmtime_context_t *context, uint64_t fuel, uint64_t *remaining);
+
 /**
  * \brief Configres WASI state within the specified store.
  *

crates/c-api/src/store.rs

@@ -145,6 +145,17 @@ pub extern "C" fn wasmtime_context_fuel_consumed(store: CStoreContext<'_>, fuel:
     }
 }
 
+#[no_mangle]
+pub extern "C" fn wasmtime_context_consume_fuel(
+    mut store: CStoreContextMut<'_>,
+    fuel: u64,
+    remaining_fuel: &mut u64,
+) -> Option<Box<wasmtime_error_t>> {
+    crate::handle_result(store.consume_fuel(fuel), |remaining| {
+        *remaining_fuel = remaining;
+    })
+}
+
 #[repr(C)]
 pub struct wasmtime_interrupt_handle_t {
     handle: InterruptHandle,