Solve.Lookup behaviour (Solve v0.2.3)

Process-local facade for interacting with a Solve app.

Summary

Functions

cleanup()

Drops cached refs and monitors for retired local app instances. No live subscriptions are removed.

collection(source)

collection(app, source)

dispatch(arg)

dispatch(target, payload)

dispatch(target, event, payload)

dispatch(app, target, event, payload)

event(controller, event_name)

Reads an instance-bound direct event tuple from a lookup item.

event(controller, event_name, payload)

events(arg1)

handle_message(arg1)

Consumes update/dispatch envelopes, or owned :solve_lookup_down monitor messages.

solve(target)

solve(app, target)

unsubscribe(target)

Releases a lookup interest using the calling process's :solve_app context.

unsubscribe(app, target)

Releases the calling process's cached interest in a target and requests raw detachment.

Types

dispatch_event()

@type dispatch_event() ::
  {pid(), {:solve_event, atom()}} | {pid(), {:solve_event, atom(), term()}}

target()

@type target() :: Solve.controller_target()

Callbacks

handle_solve_updated(map, term)

(optional)

@callback handle_solve_updated(map(), term()) :: {:ok, term()}

Functions

cleanup()

@spec cleanup() :: :ok

Drops cached refs and monitors for retired local app instances. No live subscriptions are removed.

collection(source)

@spec collection(atom()) :: Solve.Collection.t(map())

collection(app, source)

@spec collection(GenServer.server() | nil, atom()) :: Solve.Collection.t(map())

dispatch(arg)

@spec dispatch(dispatch_event()) :: :ok

dispatch(target, payload)

@spec dispatch(target() | dispatch_event(), term()) :: :ok

dispatch(target, event, payload)

@spec dispatch(target(), atom(), term()) :: :ok

dispatch(app, target, event, payload)

@spec dispatch(GenServer.server() | nil, target(), atom(), term()) :: :ok

event(controller, event_name)

@spec event(map() | nil, atom()) :: dispatch_event() | nil

Reads an instance-bound direct event tuple from a lookup item.

event(controller, event_name, payload)

@spec event(map() | nil, atom(), term()) :: dispatch_event() | nil

events(arg1)

@spec events(map() | nil) :: map() | nil

handle_message(arg1)

@spec handle_message(
  Solve.Message.t()
  | {:solve_lookup_down, reference(), :process, pid(), term()}
) ::
  map()

Consumes update/dispatch envelopes, or owned :solve_lookup_down monitor messages.

Manual mode should forward the tagged monitor messages here as well as envelopes. Acquire a target with solve/2 or collection/2 before forwarding its updates. Only versioned updates carrying the canonical app PID for an existing ref are accepted. Unsolicited, versionless, obsolete, and retired-app updates are ignored; messages never create subscriptions or seed the cache. Forward the complete runtime envelope rather than rebuilding an update from its value.

solve(target)

@spec solve(target()) :: map() | nil

solve(app, target)

@spec solve(GenServer.server() | nil, target()) :: map() | nil

unsubscribe(target)

@spec unsubscribe(target()) :: :ok | {:error, term()}

Releases a lookup interest using the calling process's :solve_app context.

See unsubscribe/2 for ownership and partial-failure semantics.

unsubscribe(app, target)

@spec unsubscribe(GenServer.server() | nil, target()) :: :ok | {:error, term()}

Releases the calling process's cached interest in a target and requests raw detachment.

Use an app PID or a name previously used to acquire a lookup. Names identify their cached app instance: this function never resolves a name to discover a replacement app. An unknown alias or missing ref returns :ok without an app call. Passing nil uses the calling process's :solve_app context.

Removes only this target. Collection sources and individual items are independent; repeated reads and aliases share one interest, not reference counts. The last ref for an app also releases its lookup monitor and aliases. Queued updates cannot recreate a removed ref; a later solve/2 or collection/2 explicitly reacquires it. No update callback is invoked and previously returned event tuples remain usable.

A raw reentrancy error preserves the cache unchanged. Other raw errors remove the ref but leave physical detachment unconfirmed. Outer app-call exits also remove the ref before propagating; confirmed app death is treated as successful cleanup.

:ok for a missing ref certifies only a local no-op, not physical detachment. After a timeout, another lookup unsubscribe does not retry the raw operation. Use Solve.unsubscribe/2 with the original app PID if confirmation is needed, or to release raw subscriptions that have no lookup ref (including failed acquisitions).