github.com/altoros/juju-vmware@v0.0.0-20150312064031-f19ae857ccca/worker/uniter/relation/hooksource.go (about)

     1  // Copyright 2012-2014 Canonical Ltd.
     2  // Licensed under the AGPLv3, see LICENCE file for details.
     3  
     4  package relation
     5  
     6  import (
     7  	"github.com/juju/errors"
     8  
     9  	"github.com/juju/juju/state/multiwatcher"
    10  	"github.com/juju/juju/worker/uniter/hook"
    11  )
    12  
    13  // HookSource defines a generator of hook.Info events. A HookSource's client
    14  // must be careful to:
    15  //  * use it from a single goroutine.
    16  //  * collect asynchronous events from Changes(), and synchronously pass
    17  //    them to Update() whenever possible.
    18  //  * only use fresh values returned from Empty() and Next(); i.e. only those
    19  //    which have been generated since the last call to Pop() or Update().
    20  //  * Stop() it when finished.
    21  type HookSource interface {
    22  
    23  	// Changes returns a channel sending events which must be delivered --
    24  	// synchronously, and in order -- to the HookSource's Update method .
    25  	Changes() <-chan multiwatcher.RelationUnitsChange
    26  
    27  	// Stop causes the HookSource to clean up its resources and stop sending
    28  	// changes.
    29  	Stop() error
    30  
    31  	// Update applies the supplied change to the HookSource's schedule, and
    32  	// invalidates the results of previous calls to Next() and Empty(). It
    33  	// should only be called with change events received from the Changes()
    34  	// channel.
    35  	Update(change multiwatcher.RelationUnitsChange) error
    36  
    37  	// Empty returns false if any hooks are scheduled.
    38  	Empty() bool
    39  
    40  	// Next returns the first scheduled hook. It will panic if no hooks are
    41  	// scheduled.
    42  	Next() hook.Info
    43  
    44  	// Pop removes the first scheduled hook, and invalidates the results of
    45  	// previous calls to Next() and Empty(). It will panic if no hooks are
    46  	// scheduled.
    47  	Pop()
    48  }
    49  
    50  // NoUpdates implements a subset of HookSource that delivers no changes, errors
    51  // on update, and ignores stop requests (because there's nothing running in the
    52  // first place). It's useful for implementing static HookSources.
    53  type NoUpdates struct{}
    54  
    55  func (_ *NoUpdates) Stop() error                                      { return nil }
    56  func (_ *NoUpdates) Changes() <-chan multiwatcher.RelationUnitsChange { return nil }
    57  func (_ *NoUpdates) Update(_ multiwatcher.RelationUnitsChange) error {
    58  	return errors.Errorf("HookSource does not accept updates")
    59  }
    60  
    61  // RelationUnitsWatcher produces RelationUnitsChange events until stopped, or
    62  // until it encounters an error. It must not close its Changes channel without
    63  // signalling an error via Stop and Err.
    64  type RelationUnitsWatcher interface {
    65  	Err() error
    66  	Stop() error
    67  	Changes() <-chan multiwatcher.RelationUnitsChange
    68  }