Documentation
¶
Overview ¶
Copyright 2017 Canonical Ltd. Licensed under the AGPLv3, see LICENCE file for details.
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 ¶
- func RemovePresenceForModel(base *mgo.Collection, modelTag names.ModelTag) error
- type Agent
- type Change
- type PingBatcher
- type PingRecorder
- type Pinger
- type Pruner
- type Watcher
- func (w *Watcher) Alive(key string) (bool, error)
- func (w *Watcher) Dead() <-chan struct{}
- func (w *Watcher) Err() error
- func (w *Watcher) Kill()
- func (w *Watcher) StartSync()
- func (w *Watcher) Stop() error
- func (w *Watcher) String() string
- func (w *Watcher) Sync()
- func (w *Watcher) Unwatch(key string, ch chan<- Change)
- func (w *Watcher) Wait() error
- func (w *Watcher) Watch(key string, ch chan<- Change)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RemovePresenceForModel ¶
func RemovePresenceForModel(base *mgo.Collection, modelTag names.ModelTag) error
RemovePresenceForModel removes all of the records of entities for a given model across all of the collections.
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 PingBatcher ¶
type PingBatcher struct {
// contains filtered or unexported fields
}
PingBatcher aggregates several pingers to update the database on a fixed schedule.
func NewDeadPingBatcher ¶
func NewDeadPingBatcher(err error) *PingBatcher
NewDeadPingBatcher returns a PingBatcher that is already stopped with an error.
func NewPingBatcher ¶
func NewPingBatcher(base *mgo.Collection, flushInterval time.Duration) *PingBatcher
NewPingBatcher creates a worker that will batch ping requests and prepare them for insertion into the Pings collection. Pass in the base "presence" collection. flushInterval is how often we will write the contents to the database. It should be shorter than the 30s slot window for us to not cause active pingers to show up as missing. The current default is 1s as it provides a good balance of significant-batching-for-performance while still having responsiveness to agents coming alive. Note that we don't strictly sync on flushInterval times, but use a range of times around that interval to avoid having all ping batchers get synchronized and still be issuing all requests concurrently.
func (*PingBatcher) Kill ¶
func (pb *PingBatcher) Kill()
Kill is part of the worker.Worker interface.
func (*PingBatcher) Ping ¶
Ping should be called by a Pinger when it is ready to update its time slot. It passes in all of the pre-resolved information (what exact field bit is being set), rather than the higher level "I'm pinging for this Agent". Internally, we synchronize with the main worker loop. Which means that this function will return once the main loop recognizes that we have a ping request but it will not have updated its internal structures, and certainly not the database.
func (*PingBatcher) Stop ¶
func (pb *PingBatcher) Stop() error
Stop this PingBatcher, part of the extended Worker interface.
func (*PingBatcher) Sync ¶
func (pb *PingBatcher) Sync() error
Sync schedules a flush of the current state to the database. This is not immediate, but actually within a short timeout so that many calls to sync in a short time frame will only trigger one write to the database.
func (*PingBatcher) Wait ¶
func (pb *PingBatcher) Wait() error
Wait returns when the Pinger has stopped, and returns the first error it encountered.
type PingRecorder ¶
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, recorderFunc func() PingRecorder) *Pinger
NewPinger returns a new Pinger to report that key is alive. It starts reporting after Start is called.
func (*Pinger) KillForTesting ¶
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.
type Pruner ¶
type Pruner struct {
// contains filtered or unexported fields
}
Pruner tracks the state of removing unworthy beings from the presence.beings and presence.pings collections. Being sequences are unworthy once their sequence has been superseded, and pings older than 2 slots are no longer referenced.
type Watcher ¶
type Watcher struct {
// contains filtered or unexported fields
}
A Watcher can watch any number of pinger keys for liveness changes.
func NewDeadWatcher ¶
NewDeadWatcher returns a new watcher that is already dead and always returns the given error from its Err method.
func NewWatcher ¶
func NewWatcher(base *mgo.Collection, modelTag names.ModelTag) *Watcher
NewWatcher returns a new Watcher.
func (*Watcher) Alive ¶
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 ¶
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) Sync ¶
func (w *Watcher) Sync()
Sync forces the watcher to load new events from the database and blocks until all events have been dispatched.
Source Files