watcher

type CoreWatcher ¶

type CoreWatcher interface {
	worker.Worker
}

CoreWatcher encodes some features of a watcher. The most obvious one:

Changes() <-chan <T>

...can't be expressed cleanly; and this is annoying because every such chan needs to share common behaviours for the abstraction to be generally helpful. The critical features of a Changes chan are as follows:

• The channel should never be closed.

• The channel should send a single baseline value, representing the change from a nil state; and subsequently send values representing deltas from whatever had previously been sent.

• The channel should really never be closed. Many existing watchers *do* close their channels when the watcher stops; this is harmful because it mixes lifetime-handling into change-handling at the cost of clarity (and in some cases correctness). So long as a watcher implements Worker, it can be safely managed with the worker/catacomb package; of course, all sensible clients will still check for closed channels (never trust a contract...) but can treat that scenario as a simple error.

  (This rule only applies to watchers outside the API; watchers inside the API boundary need to close their changes channel so that the .Next() method implementations inside the API server (see apiserver/watcher.go) finish correctly.)

To convert a state/watcher.Watcher to a CoreWatcher, ensure that the watcher no longer closes its Changes() channel; and replace Stop() and Err() with the usual worker boilerplate. Namely:

// Kill is part of the worker.Worker interface.
func (w *watcher) Kill() {
    w.tomb.Kill(nil)
}

// Wait is part of the worker.Worker interface.
func (w *watcher) Wait() error {
    return w.tomb.Wait()
}

Tests using state/testing/{$Kind}WatcherC should be converted to use the equivalents in watcher/watchertest.

type EntitiesWatcher ¶

type EntitiesWatcher interface {
	CoreWatcher
	Changes() StringsChannel
}

EntitiesWatcher conveniently ties an StringsChannel to the worker.Worker that represents its validity.

It purports to deliver strings that can be parsed as tags, but since it doesn't actually produce tags today we may as well make it compatible with StringsWatcher so we can use it with a StringsHandler. In an ideal world we'd have something like `type EntitiesChannel <-chan []names.Tag` instead.

type MachineStorageId ¶

type MachineStorageId struct {
	MachineTag    string
	AttachmentTag string
}

MachineStorageId associates a machine entity with a storage entity. They're expressed as tags because they arrived here as a move, not a change; ideally a MachineStorageIdsWatcher would return them in a more model-appropriate format (i.e. not as strings-that-probably-parse-to-tags).

type MachineStorageIdsChannel ¶

type MachineStorageIdsChannel <-chan []MachineStorageId

MachineStorageIdsChannel is a change channel as described in the CoreWatcher docs.

It reports additions and removals to a set of attachments; and lifecycle changes within the active set.

type MachineStorageIdsWatcher ¶

type MachineStorageIdsWatcher interface {
	CoreWatcher
	Changes() MachineStorageIdsChannel
}

MachineStorageIdsWatcher conveniently ties a MachineStorageIdsChannel to the worker.Worker that represents its validity.

type MigrationStatus ¶

type MigrationStatus struct {
	MigrationId    string
	Attempt        int
	Phase          migration.Phase
	SourceAPIAddrs []string
	SourceCACert   string
	TargetAPIAddrs []string
	TargetCACert   string
}

MigrationStatus is the client side version of params.MigrationStatus.

type MigrationStatusWatcher ¶

type MigrationStatusWatcher interface {
	CoreWatcher
	Changes() <-chan MigrationStatus
}

MigrationStatusWatcher describes a watcher that reports the latest status of a migration for a model.

type MultiNotifyWatcher ¶

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

MultiNotifyWatcher implements NotifyWatcher, combining multiple NotifyWatchers.

func NewMultiNotifyWatcher(w ...NotifyWatcher) *MultiNotifyWatcher

func (w *MultiNotifyWatcher) Changes() NotifyChannel

func (w *MultiNotifyWatcher) Err() error

func (w *MultiNotifyWatcher) Kill()

func (w *MultiNotifyWatcher) Stop() error

func (w *MultiNotifyWatcher) Wait() error

type NotifyChannel ¶

type NotifyChannel <-chan struct{}

NotifyChannel is a change channel as described in the CoreWatcher docs.

It sends a single value to indicate that the watch is active, and subsequent values whenever the value(s) under observation change(s).

type NotifyConfig ¶

type NotifyConfig struct {
	Handler NotifyHandler
}

NotifyConfig holds the direct dependencies of a NotifyWorker.

func (config NotifyConfig) Validate() error

type NotifyHandler ¶

type NotifyHandler interface {

	// SetUp is called once when creating a NotifyWorker. It must return a
	// NotifyWatcher or an error. The NotifyHandler takes responsibility for
	// stopping any returned watcher and handling any errors.
	SetUp() (NotifyWatcher, error)

	// Handle is called whenever a value is received from the NotifyWatcher
	// returned by SetUp. If it returns an error, the NotifyWorker will be
	// stopped.
	//
	// If Handle runs any blocking operations it must pass through, or select
	// on, the supplied abort channel; this channel will be closed when the
	// NotifyWorker is killed. An aborted Handle should not return an error.
	Handle(abort <-chan struct{}) error

	// TearDown is called once when stopping a NotifyWorker, whether or not
	// SetUp succeeded. It need not concern itself with the NotifyWatcher, but
	// must clean up any other resources created in SetUp or Handle.
	TearDown() error
}

NotifyHandler defines the operation of a NotifyWorker.

type NotifyWatcher ¶

type NotifyWatcher interface {
	CoreWatcher
	Changes() NotifyChannel
}

NotifyWatcher conveniently ties a NotifyChannel to the worker.Worker that represents its validity.

type NotifyWorker ¶

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

NotifyWorker is a worker that wraps a NotifyWatcher.

func NewNotifyWorker(config NotifyConfig) (*NotifyWorker, error)

func (nw *NotifyWorker) Kill()

func (nw *NotifyWorker) Report() map[string]interface{}

func (nw *NotifyWorker) Wait() error

type OfferStatusChange ¶

type OfferStatusChange struct {
	// Name is the name of the offer.
	Name string

	// Status is the status of the offer.
	Status status.StatusInfo
}

OfferStatusChange describes changes to some offer.

type OfferStatusChannel ¶

type OfferStatusChannel <-chan []OfferStatusChange

OfferStatusChannel is a channel used to notify of changes to an offer's status.

type OfferStatusWatcher ¶

type OfferStatusWatcher interface {
	CoreWatcher
	Changes() OfferStatusChannel
}

OfferStatusWatcher conveniently ties an OfferStatusChannel to the worker.Worker that represents its validity.

type RelationStatusChange ¶

type RelationStatusChange struct {
	// Key is the relation key of the changed relation.
	Key string

	// Suspended is the suspended status of the relation.
	Suspended bool

	// SuspendedReason is an optional message to explain why suspend is true.
	SuspendedReason string

	// Life is the relation life value, eg Alive.
	Life life.Value
}

RelationStatusChange describes changes to some relation.

type RelationStatusChannel ¶

type RelationStatusChannel <-chan []RelationStatusChange

RelationStatusChannel is a channel used to notify of changes to a relation's life or suspended status.

type RelationStatusWatcher ¶

type RelationStatusWatcher interface {
	CoreWatcher
	Changes() RelationStatusChannel
}

RelationStatusWatcher conveniently ties a RelationStatusChannel to the worker.Worker that represents its validity.

type RelationUnitsChange ¶

type RelationUnitsChange struct {

	// Changed holds a set of units that are known to be in scope, and the
	// latest known settings version for each.
	Changed map[string]UnitSettings

	// AppChanged holds the latest known settings version for associated
	// applications.
	AppChanged map[string]int64

	// Departed holds a set of units that have previously been reported to
	// be in scope, but which no longer are.
	Departed []string
}

RelationUnitsChange describes the membership and settings of; or changes to; some relation scope.

type RelationUnitsChannel ¶

type RelationUnitsChannel <-chan RelationUnitsChange

RelationUnitsChannel is a change channel as described in the CoreWatcher docs.

It sends a single value representing the current membership of a relation scope; and the versions of the settings documents for each; and subsequent values representing entry, settings-change, and departure for units in that scope.

It feeds the joined-changed-departed logic in worker/uniter, but these events do not map 1:1 with hooks.

type RelationUnitsWatcher ¶

type RelationUnitsWatcher interface {
	CoreWatcher
	Changes() RelationUnitsChannel
}

RelationUnitsWatcher conveniently ties a RelationUnitsChannel to the worker.Worker that represents its validity.

type SecretBackendRotateChange ¶

type SecretBackendRotateChange struct {
	ID              string
	Name            string
	NextTriggerTime time.Time
}

SecretBackendRotateChange describes changes to a secret backend rotation trigger.

func (s SecretBackendRotateChange) GoString() string

type SecretBackendRotateChannel ¶

type SecretBackendRotateChannel <-chan []SecretBackendRotateChange

SecretBackendRotateChannel is a change channel as described in the CoreWatcher docs.

type SecretBackendRotateWatcher ¶

type SecretBackendRotateWatcher interface {
	CoreWatcher
	Changes() SecretBackendRotateChannel
}

SecretBackendRotateWatcher conveniently ties a SecretBackendRotateChannel to the worker.Worker that represents its validity.

type SecretRevisionChange ¶

type SecretRevisionChange struct {
	URI      *secrets.URI
	Revision int
}

SecretRevisionChange describes changes to a secret.

func (s SecretRevisionChange) GoString() string

type SecretRevisionChannel ¶

type SecretRevisionChannel <-chan []SecretRevisionChange

SecretRevisionChannel is a channel used to notify of changes to a secret.

type SecretTriggerChange ¶

type SecretTriggerChange struct {
	URI             *secrets.URI
	Revision        int
	NextTriggerTime time.Time
}

SecretTriggerChange describes changes to a secret trigger. eg rotation or expiry.

func (s SecretTriggerChange) GoString() string

type SecretTriggerChannel ¶

type SecretTriggerChannel <-chan []SecretTriggerChange

SecretTriggerChannel is a change channel as described in the CoreWatcher docs.

type SecretTriggerWatcher ¶

type SecretTriggerWatcher interface {
	CoreWatcher
	Changes() SecretTriggerChannel
}

SecretTriggerWatcher conveniently ties a SecretTriggerChannel to the worker.Worker that represents its validity.

type SecretsRevisionWatcher ¶

type SecretsRevisionWatcher interface {
	CoreWatcher
	Changes() SecretRevisionChannel
}

SecretsRevisionWatcher conveniently ties an SecretRevisionChannel to the worker.Worker that represents its validity.

type StringsChannel ¶

type StringsChannel <-chan []string

StringsChannel is a change channel as described in the CoreWatcher docs.

It sends a single value indicating a baseline set of values, and subsequent values representing additions, changes, and/or removals of those values. The precise semantics may depend upon the individual watcher.

type StringsConfig ¶

type StringsConfig struct {
	Handler StringsHandler
}

StringsConfig holds the direct dependencies of a StringsWorker.

func (config StringsConfig) Validate() error

type StringsHandler ¶

type StringsHandler interface {

	// SetUp is called once when creating a StringsWorker. It must return a
	// StringsWatcher or an error. The StringsHandler takes responsibility for
	// stopping any returned watcher and handling any errors.
	SetUp() (StringsWatcher, error)

	// Handle is called with every value received from the StringsWatcher
	// returned by SetUp. If it returns an error, the StringsWorker will be
	// stopped.
	//
	// If Handle runs any blocking operations it must pass through, or select
	// on, the supplied abort channel; this channel will be closed when the
	// StringsWorker is killed. An aborted Handle should not return an error.
	Handle(abort <-chan struct{}, changes []string) error

	// TearDown is called once when stopping a StringsWorker, whether or not
	// SetUp succeeded. It need not concern itself with the StringsWatcher, but
	// must clean up any other resources created in SetUp or Handle.
	TearDown() error
}

StringsHandler defines the operation of a StringsWorker.

type StringsWatcher ¶

type StringsWatcher interface {
	CoreWatcher
	Changes() StringsChannel
}

StringsWatcher conveniently ties a StringsChannel to the worker.Worker that represents its validity.

type StringsWorker ¶

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

StringsWorker is a worker that wraps a StringsWatcher.

func NewStringsWorker(config StringsConfig) (*StringsWorker, error)

func (sw *StringsWorker) Kill()

func (sw *StringsWorker) Report() map[string]interface{}

func (sw *StringsWorker) Wait() error

type UnitSettings ¶

type UnitSettings struct {
	Version int64
}

UnitSettings specifies the version of some unit's settings in some relation.