boam

# `Boam.Dispatcher`

Dispatch process for `beam.call(...)` requests originating in JavaScript.

A dispatcher is an ordinary `GenServer` that receives messages from the Rust
runtime, resolves the requested handler, executes it on the BEAM, and replies
back to the waiting JavaScript call.

In the default setup you do not need to start this module manually;
[`Boam.Runtime`](`Boam.Runtime`) starts one automatically when no explicit
`:dispatcher` pid is supplied.

## Handler Forms

Handlers can be provided in three shapes:

  * `fn args -> result end`
  * `fn name, args -> result end`
  * `{Module, :function}` which is called as `apply(Module, :function, [args])`

## Return Contract

A handler may return:

  * any JSON-compatible value, which becomes the JavaScript return value
  * `{:ok, value}`, which unwraps to `value`
  * `{:error, reason}`, which raises a JavaScript error

If a handler crashes, the formatted exception is sent back as a JavaScript
error message instead of leaving the runtime hanging.

# `export_name`

```elixir
@type export_name() :: atom() | String.t()
```

# `handler`

```elixir
@type handler() ::
  (list() -> term()) | (String.t(), list() -> term()) | {module(), atom()}
```

Function or MFA that can satisfy a `beam.call(...)` request.

# `start_option`

```elixir
@type start_option() ::
  {:name, GenServer.name()}
  | {:exports, %{optional(export_name()) => handler()} | keyword(handler())}
  | {:fallback, (String.t(), list() -> term())}
```

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `register`

```elixir
@spec register(
  GenServer.server(),
  %{optional(export_name()) => handler()} | keyword(handler())
) :: :ok
```

Registers or replaces one or more handlers at runtime.

# `register`

```elixir
@spec register(GenServer.server(), export_name(), handler()) :: :ok
```

Registers or replaces a single handler at runtime.

# `start_link`

```elixir
@spec start_link([start_option()]) :: GenServer.on_start()
```

Starts a dispatcher process.

Most callers should let `Boam.Runtime` create a dispatcher
automatically. Start this module directly when you want to reuse a single
dispatch process across several runtimes or supervise it yourself.

# `unregister`

```elixir
@spec unregister(GenServer.server(), export_name()) :: :ok
```

Removes a handler at runtime.

---

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