# `Tinkex.QueueStateObserver`
[🔗](https://github.com/North-Shore-AI/tinkex/blob/v0.4.0/lib/tinkex/queue_state_observer.ex#L1)

Behaviour for modules that want to react to queue-state transitions.

`Tinkex.Future.poll/2` emits telemetry for queue-state changes and, when given
a `queue_state_observer`, will invoke the callback below. Training and
Sampling clients can implement this behaviour to update local backpressure
tracking whenever the server sends a `TryAgainResponse`.

## Example

    defmodule MyObserver do
      @behaviour Tinkex.QueueStateObserver

      @impl true
      def on_queue_state_change(queue_state) do
        Logger.metadata(queue_state: queue_state)
        :ok
      end
    end

The observer is passed to `Tinkex.Future.poll/2` via the
`:queue_state_observer` option and will receive callbacks on every state
transition alongside the telemetry events under
`[:tinkex, :queue, :state_change]`.

## Callback Signatures

Implement either of the callbacks below. The 2-arity version receives a
metadata map (request_id, queue_state_reason, etc.) for richer context while
the 1-arity version is kept for backwards compatibility.

# `on_queue_state_change`
*optional* 

```elixir
@callback on_queue_state_change(Tinkex.Types.QueueState.t()) :: any()
```

# `on_queue_state_change`
*optional* 

```elixir
@callback on_queue_state_change(Tinkex.Types.QueueState.t(), map()) :: any()
```

---

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