# `Beaver.MLIR.MemoryEffects`

Implements MLIR's `MemoryEffectsOpInterface` for dynamic operations.

A callback returns `:pure` or a list of effect specifications. An effect is
one of `:allocate`, `:free`, `:read`, or `:write`, optionally associated with
an operand, result, block argument, or symbol:

    [
      {:read, {:operand, 0}},
      {:write, {:result, 0}},
      {:read, {:symbol, symbol_ref}, stage: 1}
    ]

A bare effect such as `:write` is not associated with a particular IR
entity. Options are `:parameters`, `:stage`, `:effect_on_full_region`, and
`:resource`. The default resource and a null parameters attribute are used
when omitted.

The effects list passed to a two-argument callback is borrowed and valid only
until that callback returns. Prefer returning declarative specifications.
Callback exceptions are diagnosed and native code adds a conservative
unknown write effect.

# `effect`

```elixir
@type effect() :: :allocate | :free | :read | :write
```

# `effect_spec`

```elixir
@type effect_spec() ::
  effect() | {effect(), target()} | {effect(), target(), keyword()}
```

# `target`

```elixir
@type target() ::
  nil
  | :operation
  | {:operand, non_neg_integer() | Beaver.MLIR.OpOperand.t()}
  | {:result, non_neg_integer() | Beaver.MLIR.Value.t()}
  | {:block_argument, Beaver.MLIR.Value.t()}
  | {:symbol, Beaver.MLIR.Attribute.t()}
  | Beaver.MLIR.OpOperand.t()
  | Beaver.MLIR.Value.t()
  | Beaver.MLIR.Attribute.t()
```

# `memory_effects`

```elixir
@callback memory_effects(Beaver.MLIR.Operation.t()) ::
  :pure | [effect_spec()] | {:ok, [effect_spec()]}
```

# `attach`

```elixir
@spec attach(Beaver.MLIR.Context.t(), String.t(), module() | function(), keyword()) ::
  Beaver.MLIR.ExternalInterface.Attachment.t()
```

Attaches a callback-backed memory effects interface model.

# `consumes_handle`

Adds the standard transform-dialect effects for consumed handle operands.

# `modifies_payload`

Marks a transform operation as potentially modifying payload IR.

# `only_reads_handle`

Adds the standard transform-dialect effects for read-only handle operands.

# `only_reads_payload`

Marks a transform operation as only reading payload IR.

# `produces_handle`

Adds the standard transform-dialect effects for produced handle results.