Topical (topical v0.3.1)
This module provides the high level interface for interacting with topics. Primarily for subscribing (and unsubscribing), but also for sending requests.
After subscribing, a client will initially receive a {:reset, ref, value} message, and then
subsequent {:updates, ref, updates} messages when the value of the topic changes, where
updates is a list with each item being one of:
{:set, path, value}: thevaluehas been set at thepath.{:unset, path, key}: thekeyhas been unset from the object at thepath.{:insert, path, index, values}: thevalueshave been inserted into the array at thepath.{:delete, path, index, count}:countvalues have been deleted from the array at thepath, from the positionindex.
A client can interact directly with a topic by executing actions (which returns a result), or
by notifying (without waiting for a result). These are analogous to GenServer.call/3 and
GenServer.cast/2. Be aware that a topic is blocked while processing a request.
Link to this section Summary
Functions
Captures the state of the topic (in the specified registry) without subscribing.
Returns a specification to start a Topical registry under a supervisor.
Executes an action in a topic.
Send a notification to a registry.
Subscribes to the specified topic (in the specified registry).
Unsubscribes from a topic.
Link to this section Functions
capture(registry, topic, context \\ nil, params \\ %{})
Captures the state of the topic (in the specified registry) without subscribing.
options
Options
params- Optional map of params to pass to the topic (default:%{}).
example
Example
Topical.capture(MyApp.Topical, ["lists", "foo"])
# => {:ok, %{items: %{}, order: []}}child_spec(options)
Returns a specification to start a Topical registry under a supervisor.
execute(registry, topic, action, args \\ {}, context \\ nil, params \\ %{})
Executes an action in a topic.
options
Options
params- Optional map of params to pass to the topic (default:%{}).
example
Example
Topical.execute(MyApp.Topical, ["lists", "foo"], "add_item", {"Test", false})
#=> {:ok, "item123"}notify(registry, topic, action, args \\ {}, context \\ nil, params \\ %{})
Send a notification to a registry.
This is similar to execute/4, except no result is waited for.
options
Options
params- Optional map of params to pass to the topic (default:%{}).
example
Example
Topical.notify(MyApp.Topical, ["lists", "foo"], "update_done", {"item123", true})
#=> :oksubscribe(registry, topic, pid, context \\ nil, params \\ %{})
Subscribes to the specified topic (in the specified registry).
Returns {:ok, ref, server}, where ref is a reference to the subscription and
server is the topic server PID (used for unsubscribing).
The pid will be sent messages, as described above.
options
Options
params- Optional map of params to pass to the topic (default:%{}). These are merged with route params and passed toconnect/2andinit/1. Topics with different param values are separate instances and do not share state.
example
Example
Topical.subscribe(MyApp.Topical, ["lists", "foo"], self())
#=> {:ok, #Reference<0.4021726225.4145020932.239110>, #PID<0.123.0>}unsubscribe(server, ref)
Unsubscribes from a topic.
Takes the server PID and ref returned from subscribe/5.
example
Example
{:ok, ref, server} = Topical.subscribe(MyApp.Topical, ["lists", "foo"], self())
Topical.unsubscribe(server, ref)