Beaver.MLIR.CompilationRuntime (beaver v0.4.8)

Copy Markdown

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.

Summary

Types

compile_option()
plan_runtime_option()

Functions

compile(source, opts_or_plan \\ [])
compile(source, plan, runtime_opts)
compile!(source, opts_or_plan \\ [])
compile!(source, plan, runtime_opts)
emit_object!(artifact, path, opts \\ [])

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

invalidate(cache \\ :memory, key \\ :all)

Explicitly invalidate one cache lookup key, or all entries.

jit!(artifact, opts \\ [])

Create and initialize a JIT from a validated compilation artifact.

llvm_revision()

Types

compile_option()

@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()

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

Functions

compile(source, opts_or_plan \\ [])

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

compile(source, plan, runtime_opts)

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

compile!(source, opts_or_plan \\ [])

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

compile!(source, plan, runtime_opts)

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

emit_object!(artifact, path, opts \\ [])

@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(cache \\ :memory, key \\ :all)

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

Explicitly invalidate one cache lookup key, or all entries.

jit!(artifact, opts \\ [])

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

Create and initialize a JIT from a validated compilation artifact.

llvm_revision()

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