presence

Documentation

Overview

The presence package implements an interface for observing liveness of arbitrary keys (agents, processes, etc) on top of MongoDB. The design works by periodically updating the database so that watchers can tell an arbitrary key is alive.

Index

• type Agent
• type Change
• type Pinger
  • func NewPinger(base *mgo.Collection, modelTag names.ModelTag, key string) *Pinger
  • func (p *Pinger) KillForTesting() error
  • func (p *Pinger) Start() error
  • func (p *Pinger) Stop() error
  • func (p *Pinger) Wait() error
• type Watcher
  • func NewWatcher(base *mgo.Collection, modelTag names.ModelTag) *Watcher
  • func (w *Watcher) Alive(key string) (bool, error)
  • func (w *Watcher) Dead() <-chan struct{}
  • func (w *Watcher) Err() error
  • func (w *Watcher) StartSync()
  • func (w *Watcher) Stop() error
  • func (w *Watcher) Sync()
  • func (w *Watcher) Unwatch(key string, ch chan<- Change)
  • func (w *Watcher) Watch(key string, ch chan<- Change)
• Bugs

Types

type Agent

type Agent interface {
	AgentPresence() (bool, error)
	SetAgentPresence() (*Pinger, error)
	WaitAgentPresence(time.Duration) error
}

Agent shouldn't really live here -- it's not used in this package, and is implemented by a couple of state types for the convenience of the apiserver -- but one of the methods returns a concrete *Pinger, and that ties it down here quite effectively (until we want to take on the task of cleaning it up and promoting it to core, which might well never happen).

type Change

type Change struct {
	Key   string
	Alive bool
}

Change holds a liveness change notification.

type Pinger

type Pinger struct {
	// contains filtered or unexported fields
}

Pinger periodically reports that a specific key is alive, so that watchers interested on that fact can react appropriately.

func NewPinger

func NewPinger(base *mgo.Collection, modelTag names.ModelTag, key string) *Pinger

NewPinger returns a new Pinger to report that key is alive. It starts reporting after Start is called.

func (*Pinger) KillForTesting

func (p *Pinger) KillForTesting() error

KillForTesting stops p's periodical ping and immediately reports that it is dead. TODO(ericsnow) We should be able to drop this and the two kill* methods.

func (*Pinger) Start

func (p *Pinger) Start() error

Start starts periodically reporting that p's key is alive.

func (*Pinger) Stop

func (p *Pinger) Stop() error

Stop stops p's periodical ping. Watchers will not notice p has stopped pinging until the previous ping times out.

func (*Pinger) Wait

func (p *Pinger) Wait() error

Wait returns when the Pinger has stopped, and returns the first error it encountered.

type Watcher

type Watcher struct {
	// contains filtered or unexported fields
}

A Watcher can watch any number of pinger keys for liveness changes.

func NewWatcher

func NewWatcher(base *mgo.Collection, modelTag names.ModelTag) *Watcher

NewWatcher returns a new Watcher.

func (*Watcher) Alive

func (w *Watcher) Alive(key string) (bool, error)

Alive returns whether the key is currently considered alive by w, or an error in case the watcher is dying.

func (*Watcher) Dead

func (w *Watcher) Dead() <-chan struct{}

Dead returns a channel that is closed when the watcher has stopped.

func (*Watcher) Err

func (w *Watcher) Err() error

Err returns the error with which the watcher stopped. It returns nil if the watcher stopped cleanly, tomb.ErrStillAlive if the watcher is still running properly, or the respective error if the watcher is terminating or has terminated with an error.

func (*Watcher) StartSync

func (w *Watcher) StartSync()

StartSync forces the watcher to load new events from the database.

func (*Watcher) Stop

func (w *Watcher) Stop() error

Stop stops all the watcher activities.

func (*Watcher) Sync

func (w *Watcher) Sync()

Sync forces the watcher to load new events from the database and blocks until all events have been dispatched.

func (*Watcher) Unwatch

func (w *Watcher) Unwatch(key string, ch chan<- Change)

Unwatch stops watching the liveness of key via ch.

func (*Watcher) Watch

func (w *Watcher) Watch(key string, ch chan<- Change)

Watch starts watching the liveness of key. An event will be sent onto ch to report the initial status for the key, and from then on a new event will be sent whenever a change is detected. Change values sent to the channel must be consumed, or the whole watcher will blocked.

Notes

Bugs

• The pings and beings collection currently grow without bound.