Subscriptions are a way of receiving notifications about events of a given type. Presently, the circuit provides two types of subscriptions:
Just like process and other elements, a subscription is an element (a persistent object) that is created and attached to an anchor. The methods of a subscription allow the user to read events, one by one, in order of appearance, at the user's convenience.
To create a new subscription element, use one of the following two Anchor
methods:
MakeOnJoin() (Subscription, error) MakeOnLeave() (Subscription, error)
MakeOnJoin subscribes to the stream of ‘host joined the cluster’ events,
while MakeOnLeave subscribes to the stream of ‘host left the cluster’ events.
An application error will occur only if the underlying anchor is not free (i.e. it has an element
already attached to it).
The subscription element is represented by the following Go interface:
type Subscription interface {
Consume() (interface{}, bool)
Peek() SubscriptionStat
Scrub()
}
Subscriptions can be closed and discarded using the Scrub method of the
subscription element or of its anchor.
Events are consumed using Consume. The first return value of Consume
holds the description of the event that was popped from the queue.
The second return value is true if an event was successfully retrieved. Otherwise, the end-of-stream
has been reached permanently and the first return value will be nil.
If the stream is still open and there are no events to be consumed, Consume will block.
Host join and leave subscriptions return string events that
hold the textual path of the host that joined or left the network. These strings will
look like /X36f63a7e4ae9df92
After a join-subscription is created, it will produce all the hosts that are currently in the cluster as events, and then it will continue producing new events as new hosts join later.
After a leave-subscription is created, it will produce events only for hosts leaving the network after the subscription was created. Some leave events may be reported more than once.
The status of a subscription queue can be queried asynchronously using Peek.
The returned structure describes the type of the subscription, the number of pending (not yet consumed)
events, and whether the subscription has already been closed (by the user).
type SubscriptionStat struct {
Source string
Pending int
Closed bool
}
Subscriptions, for join or leave events, are intended to be used via the following programming pattern:
join, err := MakeOnJoin()
if err != nil {
…
}
for {
event, ok := join.Consume()
if !ok {
…
}
host := event.(string)
…
}