# `Wasmex.StoreOrCaller`

Either a `Wasmex.Store` or "Caller" for imported functions.

A Store is a collection of Wasm instances and host-defined state, see `Wasmex.Store`.
A Caller takes the place of a Store in imported function calls. If a Store is needed in
Elixir-provided imported functions, always use the provided Caller because
using the Store will cause a deadlock (the Store is already processing the current Wasm call).

When configured, a StoreOrCaller can consume fuel to halt or yield execution as desired.
See `Wasmex.EngineConfig.consume_fuel/2` for more information on fuel consumption.

# `t`

```elixir
@type t() :: %Wasmex.StoreOrCaller{reference: reference(), resource: binary()}
```

# `get_fuel`

```elixir
@spec get_fuel(t()) :: {:ok, pos_integer()} | {:error, binary()}
```

Returns the amount of fuel available for future execution of this store.

## Examples

    iex> {:ok, engine} = Wasmex.Engine.new(%Wasmex.EngineConfig{consume_fuel: true})
    iex> {:ok, store} = Wasmex.Store.new(nil, engine)
    iex> Wasmex.StoreOrCaller.set_fuel(store, 10)
    iex> Wasmex.StoreOrCaller.get_fuel(store)
    {:ok, 10}

# `set_fuel`

```elixir
@spec set_fuel(t(), pos_integer()) :: :ok | {:error, binary()}
```

Sets fuel to for Wasm to consume while executing.

For this method to work, fuel consumption must be enabled via
`Wasmex.EngineConfig.consume_fuel/2`. By default a `Wasmex.Store`
starts with 0 fuel for Wasm to execute with (meaning it will
immediately trap and halt execution). This function must be
called for the store to have some fuel to allow WebAssembly
to execute.

Most Wasm instructions consume 1 unit of fuel. Some
instructions, such as `nop`, `drop`, `block`, and `loop`, consume 0
units, as any execution cost associated with them involves other
instructions which do consume fuel.

Note that at this time when fuel is entirely consumed it will cause
Wasm to trap.

## Errors

This function will return an error if fuel consumption is not enabled
via `Wasmex.EngineConfig.consume_fuel/2`.

## Examples

    iex> {:ok, engine} = Wasmex.Engine.new(%Wasmex.EngineConfig{consume_fuel: true})
    iex> {:ok, store} = Wasmex.Store.new(nil, engine)
    iex> Wasmex.StoreOrCaller.set_fuel(store, 10)
    :ok

---

*Consult [api-reference.md](api-reference.md) for complete listing*