# `Wasmex.Engine`

An `Engine` which is a global context for compilation and management of Wasm
modules.

Engines store global configuration preferences such as compilation settings,
enabled features, etc. You'll likely only need at most one of these for a
program.

You can create an engine with default configuration settings using
`Wasmex.Engine.default/0`. Be sure to consult the documentation of
`Wasmex.EngineConfig` for default settings.

## Example

    iex> {:ok, _engine} = Wasmex.Engine.new(%Wasmex.EngineConfig{})

# `t`

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

# `default`

```elixir
@spec default() :: t()
```

Creates a new `Wasmex.Engine` with default settings.

## Example

    iex> _engine = Wasmex.Engine.default()

# `new`

```elixir
@spec new(Wasmex.EngineConfig.t()) :: {:ok, t()} | {:error, binary()}
```

Creates a new `Wasmex.Engine` with the specified options.

## Example

    iex> {:ok, _engine} = Wasmex.Engine.new(%Wasmex.EngineConfig{})

# `precompile_module`

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

Ahead-of-time (AOT) compiles a WebAssembly module.

The `bytes` provided must be in one of two formats:

* A [binary-encoded][binary] WebAssembly module
* A [text-encoded][text] instance of the WebAssembly text format

This method may be used to compile a module for use with a
different target host. The output of this method may be used with
`Wasmex.Module.unsafe_deserialize/2` on hosts compatible with the
`Wasmex.EngineConfig` associated with this `Wasmex.Engine`.

The output of this method is safe to send to another host machine
for later execution. As the output is already a compiled module,
translation and code generation will be skipped and this will
improve the performance of constructing a `Wasmex.Module` from
the output of this method.

[binary]: https://webassembly.github.io/spec/core/binary/index.html
[text]: https://webassembly.github.io/spec/core/text/index.html

## Example

    iex> {:ok, engine} = Wasmex.Engine.new(%Wasmex.EngineConfig{})
    iex> bytes = File.read!(TestHelper.wasm_test_file_path())
    iex> {:ok, _serialized_module} = Wasmex.Engine.precompile_module(engine, bytes)

---

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