# `Wasmex.Store`

A Store is a collection of Wasm instances and host-defined state.

All Wasm instances and items will be attached to and refer to a Store.
For example instances, functions, globals, and tables are all attached to a Store.
Instances are created by instantiating a Module within a Store.
Many functions of the Wasmex API require a Store in the form of a `Wasmex.StoreOrCaller`
to be passed in.

A Store is intended to be a short-lived object in a program. No form of GC is
implemented at this time so once an instance is created within a Store it will
not be deallocated until the Store itself is garbage collected. This makes Store
unsuitable for creating an unbounded number of instances in it because Store will
never release this memory. It’s recommended to have a Store correspond roughly
to the lifetime of a “main instance”.

Store operations are submitted to a bounded asynchronous executor and processed
one at a time in submission order. WebAssembly execution yields cooperatively,
allowing other async work to run between epochs, but a long-running operation
still prevents later operations on the same Store from starting.

# `new`

```elixir
@spec new(Wasmex.StoreLimits.t() | nil, Wasmex.Engine.t() | nil) ::
  {:error, reason :: binary()} | {:ok, Wasmex.StoreOrCaller.t()}
```

Creates a new Wasm store.

Returns a `Wasmex.StoreOrCaller` even though we know it’s definitely a Store.
This allows Elixir-provided imported functions, which only have a "Caller", to use the same Wasmex APIs.

Optionally, a `Wasmex.StoreLimits` can be passed in to limit the resources that can be created within the store.

## Examples

    iex> {:ok, %Wasmex.StoreOrCaller{}} = Wasmex.Store.new()

    iex> limits = %Wasmex.StoreLimits{memory_size: 1_000_000}
    iex> {:ok, %Wasmex.StoreOrCaller{}} = Wasmex.Store.new(limits)

# `new_wasi`

```elixir
@spec new_wasi(
  Wasmex.Wasi.WasiOptions.t(),
  Wasmex.StoreLimits.t() | nil,
  Wasmex.Engine.t() | nil
) ::
  {:error, reason :: binary()} | {:ok, Wasmex.StoreOrCaller.t()}
```

Creates a new Wasm store with WASI support.

Returns a `Wasmex.StoreOrCaller` even though we know it’s definitely a Store.
This allows Elixir-provided imported functions, which only have a "Caller", to use the same Wasmex APIs.

See `Wasmex.Wasi.WasiOptions` for WASI configuration options.

## Examples

    iex> {:ok, %Wasmex.StoreOrCaller{}} = Wasmex.Store.new_wasi(%Wasmex.Wasi.WasiOptions{})

    iex> wasi_opts = %Wasmex.Wasi.WasiOptions{args: ["arg1", "arg2"]}
    iex> limits = %Wasmex.StoreLimits{memory_size: 1_000_000}
    iex> {:ok, %Wasmex.StoreOrCaller{}} = Wasmex.Store.new_wasi(wasi_opts, limits)

---

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