Topical (topical v0.2.2)
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}
: thevalue
has been set at thepath
.{:unset, path, key}
: thekey
has been unset from the object at thepath
.{:insert, path, index, values}
: thevalues
have been inserted into the array at thepath
.{:delete, path, index, count}
:count
values 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
(in the specified registry
).
Link to this section Functions
capture(registry, topic, context \\ nil)
Captures the state of the topic
(in the specified registry
) without subscribing.
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)
Executes an action in a topic
.
example
Example
Topical.execute(MyApp.Topical, ["lists", "foo"], "add_item", {"Test", false})
#=> {:ok, "item123"}
notify(registry, topic, action, args \\ {}, context \\ nil)
Send a notification to a registry.
This is similar to execute/4
, except no result is waited for.
example
Example
Topical.notify(MyApp.Topical, ["lists", "foo"], "update_done", {"item123", true})
#=> :ok
subscribe(registry, topic, pid, context \\ nil)
Subscribes to the specified topic
(in the specified registry
).
Returns {:ok, ref}
, where the ref
is a reference to the subscription.
The pid
will be send messages, as described above.
example
Example
Topical.subscribe(MyApp.Topical, ["lists", "foo"], self())
#=> {:ok, #Reference<0.4021726225.4145020932.239110>}
unsubscribe(registry, topic, ref)
Unsubscribes from a topic
(in the specified registry
).
example
Example
Topical.unsubscribe(MyApp.Topical, ["lists", "foo"], ref)