Skuld.PageMachine (skuld_concurrency v0.44.0)

LiveView integration for FiberPool.Server — a multi-fiber page machine with bidirectional message passing.

Usage

use Skuld.PageMachine,
  tag: :checkout,
  on_yield: &handle_yield/2,
  on_complete: &handle_complete/2

Multi-spindle mode

For pages with concurrent spindles, use /3 callbacks:

on_yield: &handle_yield/3

defp handle_yield(:cart, status, socket), do: ...
defp handle_yield(:checkout, step, socket), do: ...

Event routing

Events route to spindles by name:

def_pipe_event "search", into: :products, before: &start_spinner/1
def_pipe_event "buy", into: :products

Typed protocol

For compile-time validation of the entire spindle ↔ LiveView contract, define a protocol module with use Skuld.PageMachine.Contract and pass it via the :protocol option:

defmodule MyApp.StoreProtocol do
  use Skuld.PageMachine.Contract

  defevent "search", into: :products, params: [query: String.t()]
  defevent "buy", into: :products

  defyield :products, :browsing
  defyield :products, :results, params: [products: [Product.t()], total: integer()]
  defyield :checkout, :shipping
end

use Skuld.PageMachine,
  protocol: MyApp.StoreProtocol,
  on_yield: &handle_yield/3

The protocol auto-generates handle_event/3 clauses for each event, so manual def_pipe_event declarations are unnecessary (though still available for ad-hoc additions).

Summary

Functions

cancel(pid)

Cancel a running page machine and all its spindles.

def_pipe_event(event, opts \\ [])

def_pipe_event(event, pattern, opts)

default_assign_key()

The default assign key used to look up the PageMachine pid from socket.assigns.

default_tag()

The default PageMachine tag.

resume(pid, fiber_key, value)

Resume a yielded spindle with a value.

run(fibers, fibers \\ [])

Start a page machine in a separate FiberPool.Server process.