PubSub publishes data to subscriptions. However, it can do so much more than just push some data to a subscription. Each subscription is placed in a tree. When data is published, it traverses the tree and finds each interested subscription. This allows for sophisticated filters and routing.
A subscription tree is a collection of subscriptions that are organized based on what data they want published to them. When subscribing, a path is provided to give directions to PubSub about where to store the subscription and what data should be published to it.
So for example, say there are three subscriptions with the following paths:
Name | Path |
---|---|
sub-1 | ["a", "b", "c"] |
sub-2 | ["a", "b", "d"] |
sub-3 | ["a", "b"] |
After both subscriptions have been registered PubSub will have the following subscription tree:
a
|
b <-(sub-3)
/ \
(sub-1)-> c d <-(sub-2)
To better draw out each's subscriptions view of the tree:
a
|
b
/
(sub-1)-> c
a
|
b
\
d <-(sub-2)
a
|
b <-(sub-3)
So to give a few exapmles of how data could be published:
a
|
b <-(sub-3)
\
d <-(sub-2)
In this example both sub-2
and sub-3
would have the data written to it.
a
|
b <-(sub-3)
/ \
(sub-1)-> c d <-(sub-2)
In this example all sub-1
, sub-2
and sub-3
would have the data written
to it.
a
|
b <-(sub-3)
In this example only sub-3
would have the data written to it.
x
|
y
In this example, no subscriptions would have data written to them.
ps := pubsub.New()
subscription := func(name string) pubsub.SubscriptionFunc {
return func(data interface{}) {
fmt.Printf("%s -> %v\n", name, data)
}
}
ps.Subscribe(subscription("sub-1"), []string{"a", "b", "c"})
ps.Subscribe(subscription("sub-2"), []string{"a", "b", "d"})
ps.Subscribe(subscription("sub-3"), []string{"a", "b", "e"})
ps.Publish("data-1", pubsub.LinearTreeTraverser([]string{"a", "b"}))
ps.Publish("data-2", pubsub.LinearTreeTraverser([]string{"a", "b", "c"}))
ps.Publish("data-3", pubsub.LinearTreeTraverser([]string{"a", "b", "d"}))
ps.Publish("data-3", pubsub.LinearTreeTraverser([]string{"x", "y"}))
// Output:
// sub-1 -> data-2
// sub-2 -> data-3
In this example the LinearTreeTraverser
is used to traverse the tree of
subscriptions. When an interested subscription is found (in this case sub-1
and sub-2
for data-2
and data-3
respectively), the subscription is
handed the data.
More complex examples can be found in the examples directory.
A TreeTraverser
is used to traverse the subscription tree and find what
subscriptions should have the data published to them. There are a few
implementations provided, however it is likely a user will need to implement
their own to suit their data.
When creating a TreeTraverser
it is important to note how the data is
structured. A TreeTraverser
must be deterministic and ideally stateless. The
order the data is parsed and returned (via Traverse()
) must align with the
given path of Subscribe()
.
This means if the TreeTraverser
intends to look at field A, then B, and then
finally C, then the subscription path must be A, B and then C (and not B, A, C
or something).
A Subscription
is used when publishing data. The given path is used to
determine it's placement in the subscription tree.
The tree traversers and subscriptions are quite complicated. Laying out a tree structure is not something humans are going to find natural. Therefore a generator is provided for structs.
The struct is inspected (at go generate
time) and creates the tree layout
code. There is a provided
example.