Beaver.MLIR.Conversion.Plan (beaver v0.4.8)

Copy Markdown

An inspectable, declarative, scoped composition layer for MLIR dialect conversion.

A conversion plan records target legality rules, type conversions, materializations, and rewrite patterns into a reusable data structure. When executed via run/2 or run!/2, the plan materializes fresh conversion targets, type converters, and pattern sets in declaration order for the target MLIR.Context.

Callbacks and Metadata

Callbacks registered with plan builders accept optional :version metadata. declaration/1 returns a deterministic map of plan configuration and step metadata with function bodies and runtime state omitted. Unversioned callbacks are marked as :unversioned. This metadata is only reproducible across runs when callback versions are explicitly provided.

Ownership & Scoping

Plans do not hold native handles; they can be safely reused across multiple MLIR contexts. During run/2, temporary native resources (MLIR.ConversionTarget, MLIR.TypeConverter, MLIR.RewritePatternSet) are created and cleaned up. In case of errors or caller termination, resources are cleaned up deterministically: pattern destruction occurs before type converter destruction, which occurs before conversion target destruction.

Summary

Types

mode()
option()
t()

Functions

add_1_to_n_conversion(plan, callback, opts \\ [])
add_1_to_n_target_materialization(plan, callback, opts \\ [])
add_conversion(plan, callback, opts \\ [])
add_conversion_pattern(plan, root_name, callback, opts \\ [])
add_dynamically_legal_dialect(plan, name, callback, opts \\ [])
add_dynamically_legal_op(plan, name, callback, opts \\ [])
add_illegal_dialect(plan, name)
add_illegal_op(plan, name)
add_legal_dialect(plan, name)
add_legal_op(plan, name)
add_pattern(plan, descriptor, opts \\ [])
add_source_materialization(plan, callback, opts \\ [])
add_target_materialization(plan, callback, opts \\ [])
declaration(plan)

Returns deterministic metadata for the given plan.

mark_recursively_legal(plan, name, callback_or_opts \\ nil, opts \\ [])
mark_unknown_dynamically_legal(plan, callback, opts \\ [])
new(opts \\ [])

Creates a new conversion plan.

run(plan, ir)

Executes the conversion plan on the given IR (MLIR.Module or MLIR.Operation).

run!(plan, ir)

Executes the conversion plan on the given IR, returning the converted IR or raising MLIR.Conversion.Error.

Types

mode()

@type mode() :: :full | :partial

option()

@type option() ::
  {:mode, mode()}
  | {:timeout, non_neg_integer() | nil}
  | {:folding_mode, :never | :before_patterns | :after_patterns | nil}
  | {:build_materializations, boolean() | nil}

t()

@type t() :: %Beaver.MLIR.Conversion.Plan{
  build_materializations: boolean() | nil,
  entries: [term()],
  folding_mode: :never | :before_patterns | :after_patterns | nil,
  mode: mode(),
  timeout: non_neg_integer() | nil
}

Functions

add_1_to_n_conversion(plan, callback, opts \\ [])

@spec add_1_to_n_conversion(
  t(),
  (Beaver.MLIR.Type.t() -> Beaver.MLIR.TypeConverter.one_to_n_result()),
  keyword()
) :: t()

add_1_to_n_target_materialization(plan, callback, opts \\ [])

@spec add_1_to_n_target_materialization(t(), function(), keyword()) :: t()

add_conversion(plan, callback, opts \\ [])

@spec add_conversion(
  t(),
  (Beaver.MLIR.Type.t() -> Beaver.MLIR.TypeConverter.conversion_result()),
  keyword()
) :: t()

add_conversion_pattern(plan, root_name, callback, opts \\ [])

@spec add_conversion_pattern(
  t(),
  String.Chars.t(),
  Beaver.MLIR.ConversionPattern.callback(),
  keyword()
) :: t()

add_illegal_dialect(plan, name)

@spec add_illegal_dialect(t(), String.Chars.t()) :: t()

add_illegal_op(plan, name)

@spec add_illegal_op(t(), String.Chars.t()) :: t()

add_pattern(plan, descriptor, opts \\ [])

@spec add_pattern(t(), Beaver.Pattern.Native.Descriptor.t(), keyword()) :: t()

add_source_materialization(plan, callback, opts \\ [])

@spec add_source_materialization(t(), function(), keyword()) :: t()

add_target_materialization(plan, callback, opts \\ [])

@spec add_target_materialization(t(), function(), keyword()) :: t()

declaration(plan)

@spec declaration(t()) :: map()

Returns deterministic metadata for the given plan.

Function bodies and runtime state are omitted. Callback entries include their :version if explicitly provided, or :unversioned if omitted.

Note: Declaration metadata is only deterministic and reproducible across processes or runs when all callback versions are explicitly specified.

mark_recursively_legal(plan, name, callback_or_opts \\ nil, opts \\ [])

@spec mark_recursively_legal(
  t(),
  String.Chars.t(),
  Beaver.MLIR.ConversionTarget.legality_callback() | nil | keyword(),
  keyword()
) :: t()

mark_unknown_dynamically_legal(plan, callback, opts \\ [])

@spec mark_unknown_dynamically_legal(
  t(),
  Beaver.MLIR.ConversionTarget.legality_callback(),
  keyword()
) :: t()

new(opts \\ [])

@spec new(keyword()) :: t()

Creates a new conversion plan.

Options:

  • :mode - :full (default) or :partial.
  • :timeout - Timeout in milliseconds for conversion and callbacks (default 30_000).
  • :folding_mode - :never, :before_patterns, :after_patterns, or nil.
  • :build_materializations - boolean or nil.

run(plan, ir)

@spec run(t(), Beaver.MLIR.Conversion.conversion_ir()) ::
  Beaver.MLIR.Conversion.result()

Executes the conversion plan on the given IR (MLIR.Module or MLIR.Operation).

Fresh MLIR.ConversionTarget, MLIR.TypeConverter, and MLIR.RewritePatternSet instances are created for the duration of the conversion and cleaned up afterwards. Returns MLIR.Conversion.result().

run!(plan, ir)

@spec run!(t(), Beaver.MLIR.Conversion.conversion_ir()) ::
  Beaver.MLIR.Conversion.conversion_ir()

Executes the conversion plan on the given IR, returning the converted IR or raising MLIR.Conversion.Error.