Circuit Self-managed infrastructure, programmatic monitoring and orchestration

Using subscriptions

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.

Consuming events

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.

Status of subscription queue

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
}

Example

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)
	…
}