Boam.Dispatcher (boam v0.1.4)

Copy Markdown

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 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.

Summary

Types

export_name()
handler()

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

start_option()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

register(dispatcher, exports)

Registers or replaces one or more handlers at runtime.

register(dispatcher, name, handler)

Registers or replaces a single handler at runtime.

start_link(opts \\ [])

Starts a dispatcher process.

unregister(dispatcher, name)

Removes a handler at runtime.

Types

export_name()

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

handler()

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

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

start_option()

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

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

register(dispatcher, exports)

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

Registers or replaces one or more handlers at runtime.

register(dispatcher, name, handler)

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

Registers or replaces a single handler at runtime.

start_link(opts \\ [])

@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(dispatcher, name)

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

Removes a handler at runtime.