# `Beaver.MLIR.CompilationRuntime`

Incremental MLIR compilation for long-running BEAM applications.

The runtime caches transformed, versioned MLIR bytecode. Cache lookup uses a
fast source digest plus every compatibility input; the stored artifact key
additionally contains MLIR's structural hash. A hit therefore skips parsing
and the transform pipeline, while JIT and object emission consume the same
validated bytecode.

## Cache compatibility

The following inputs invalidate an artifact automatically:

  * source content and structural hash;
  * the LLVM revision used to build Beaver;
  * pass/transform pipeline identity;
  * resolved Transform schedule identity;
  * target configuration;
  * dynamic dialect/schema version;
  * requested bytecode emit version.

Custom pass functions are not stable cache identities. In the keyword API,
supply `:pipeline_version` whenever `:pipeline` contains runtime functions.
`Beaver.MLIR.CompilationPlan` instead requires an explicit version on every
module- or callback-backed pass step.

## Telemetry

If the `:telemetry` library is loaded, events are emitted below
`[:beaver, :mlir, :compilation, ...]`. A three-argument callback can also be
supplied in the `:telemetry` option. Durations use native time units.

# `compile_option`

```elixir
@type compile_option() ::
  {:cache, Beaver.MLIR.CompilationCache.cache()}
  | {:pipeline, term()}
  | {:pipeline_version, term()}
  | {:transform_schedule,
     Beaver.MLIR.Transform.Schedule.Resolved.t() | binary()}
  | {:transform_options, keyword()}
  | {:target, term()}
  | {:schema_version, term()}
  | {:desired_emit_version, integer() | nil}
  | {:context, Beaver.MLIR.Context.t()}
  | {:context_options, keyword()}
  | {:llvm_revision, String.t()}
  | {:telemetry, ([atom()], map(), map() -> any())}
```

# `plan_runtime_option`

```elixir
@type plan_runtime_option() ::
  {:cache, Beaver.MLIR.CompilationCache.cache()}
  | {:context, Beaver.MLIR.Context.t()}
  | {:llvm_revision, String.t()}
  | {:telemetry, ([atom()], map(), map() -> any())}
```

# `compile`

```elixir
@spec compile(
  binary() | Beaver.MLIR.Module.t(),
  [compile_option()] | Beaver.MLIR.CompilationPlan.t()
) ::
  {:ok, Beaver.MLIR.CompilationRuntime.Artifact.t()} | {:error, Exception.t()}
```

# `compile`

```elixir
@spec compile(binary() | Beaver.MLIR.Module.t(), Beaver.MLIR.CompilationPlan.t(), [
  plan_runtime_option()
]) ::
  {:ok, Beaver.MLIR.CompilationRuntime.Artifact.t()} | {:error, Exception.t()}
```

# `compile!`

```elixir
@spec compile!(
  binary() | Beaver.MLIR.Module.t(),
  [compile_option()] | Beaver.MLIR.CompilationPlan.t()
) ::
  Beaver.MLIR.CompilationRuntime.Artifact.t()
```

# `compile!`

```elixir
@spec compile!(binary() | Beaver.MLIR.Module.t(), Beaver.MLIR.CompilationPlan.t(), [
  plan_runtime_option()
]) :: Beaver.MLIR.CompilationRuntime.Artifact.t()
```

# `emit_object!`

```elixir
@spec emit_object!(Beaver.MLIR.CompilationRuntime.Artifact.t(), Path.t(), keyword()) ::
  Path.t()
```

Emit an object file from the same normalized artifact used by `jit!/2`.

# `invalidate`

```elixir
@spec invalidate(Beaver.MLIR.CompilationCache.cache(), String.t() | :all) ::
  :ok | {:error, term()}
```

Explicitly invalidate one cache lookup key, or all entries.

# `jit!`

```elixir
@spec jit!(
  Beaver.MLIR.CompilationRuntime.Artifact.t(),
  keyword()
) :: Beaver.MLIR.ExecutionEngine.t()
```

Create and initialize a JIT from a validated compilation artifact.

# `llvm_revision`

```elixir
@spec llvm_revision() :: String.t()
```