Xirsys.Sockets.Pipeline (xturn_sockets v2.2.0)

Declarative multi-tier pipeline specification.

use Xirsys.Sockets.Pipeline

tier :root,
  accumulator: {Xirsys.Sockets.Accumulator.LengthPrefixed, header_size: 2},
  handler: MyApp.Handlers.Root

tier :inner,
  accumulator: Xirsys.Sockets.Accumulator.Raw,
  handler: MyApp.Handlers.Inner,
  dispatch: :pool,
  pool_size: 8

Every pipeline must declare :root. Duplicate tier names fail at compile time.

Acceptor / DatagramServer also accept the legacy {accumulator, handler} pair, which resolve/1 turns into a single-tier pipeline.

Summary

Types

t()

Compiled pipeline: a map of tier name to Pipeline.Tier.

Functions

__using__(opts)

Imports tier/2 and compiles __tiers__/0 / __tier_spec__/1.

fresh_session(pipeline, opts)

Builds fresh root-tier session maps for a single datagram (stateless UDP).

init_session(pipeline, conn, opts)

Initializes root-tier accumulator and handler state for a stream connection.

multi_tier?(pipeline)

Returns true when the pipeline declares more than the mandatory :root tier.

resolve(pipeline_mod)

Resolves a compiled pipeline module or {accumulator, handler} sugar into a runtime %Pipeline{}.

tier(name, opts)

Declares one named tier on the using module.

tier_spec(pipeline, key)

Returns the %Pipeline.Tier{} for key.

Types

t()

@type t() :: %Xirsys.Sockets.Pipeline{
  tiers: %{required(atom()) => Xirsys.Sockets.Pipeline.Tier.t()}
}

Compiled pipeline: a map of tier name to Pipeline.Tier.

Functions

using(opts)

(macro)

Imports tier/2 and compiles __tiers__/0 / __tier_spec__/1.

Parameters

_opts - unused; reserved for future use options

fresh_session(pipeline, opts)

@spec fresh_session(
  t(),
  keyword()
) :: {map(), map()}

Builds fresh root-tier session maps for a single datagram (stateless UDP).

Parameters

pipeline - struct from resolve/1
opts - :handler_state stored under :root
iex> p = Xirsys.Sockets.Pipeline.resolve({Xirsys.Sockets.Accumulator.Raw, :handler}) iex> {accs, states} = Xirsys.Sockets.Pipeline.fresh_session(p, handler_state: :idle) iex> Map.keys(accs) [:root] iex> states %{root: :idle}

init_session(pipeline, conn, opts)

@spec init_session(t(), Xirsys.Sockets.Conn.t(), keyword()) :: {map(), map()}

Initializes root-tier accumulator and handler state for a stream connection.

Calls handle_connect/1 when the root handler exports it.

Parameters

pipeline - struct from resolve/1
conn - new connection context
opts - :handler_state used when handle_connect/1 is absent

multi_tier?(pipeline)

@spec multi_tier?(t()) :: boolean()

Returns true when the pipeline declares more than the mandatory :root tier.

Parameters

pipeline - struct from resolve/1

resolve(pipeline_mod)

@spec resolve(module() | {Xirsys.Sockets.Spec.spec(), module()}) :: t()

Resolves a compiled pipeline module or {accumulator, handler} sugar into a runtime %Pipeline{}.

Parameters

pipeline - a module that uses this one, or {accumulator_spec, handler_mod}
iex> p = Xirsys.Sockets.Pipeline.resolve({Xirsys.Sockets.Accumulator.Raw, :handler}) iex> Xirsys.Sockets.Pipeline.multi_tier?(p) false iex> spec = Xirsys.Sockets.Pipeline.tier_spec(p, :root) iex> spec.accumulator Xirsys.Sockets.Accumulator.Raw iex> spec.handler :handler iex> spec.dispatch :inline

tier(name, opts)

(macro)

Declares one named tier on the using module.

Parameters

name - atom key (:root is required on every pipeline)
opts - :accumulator and :handler (required); optional :dispatch (:inline | :task | :pool), :pool_size, :task_supervisor, :pool_supervisor

tier_spec(pipeline, key)

@spec tier_spec(t(), atom()) :: Xirsys.Sockets.Pipeline.Tier.t()

Returns the %Pipeline.Tier{} for key.

Raises if key was not declared.

Parameters

pipeline - struct from resolve/1
key - tier name (:root, ...)