github.com/mhilton/juju-juju@v0.0.0-20150901100907-a94dd2c73455/worker/uniter/filter/interface.go (about)

     1  // Copyright 2012-2014 Canonical Ltd.
     2  // Licensed under the AGPLv3, see LICENCE file for details.
     3  
     4  package filter
     5  
     6  import (
     7  	"github.com/juju/names"
     8  	"gopkg.in/juju/charm.v5"
     9  
    10  	"github.com/juju/juju/apiserver/params"
    11  )
    12  
    13  // Filter is responsible for delivering events relevant to a unit agent in a
    14  // form that can be consumed conveniently.
    15  type Filter interface {
    16  
    17  	// Stop shuts down the filter and returns any error encountered in the process.
    18  	Stop() error
    19  
    20  	// Dead returns a channel that will close when the filter has shut down.
    21  	Dead() <-chan struct{}
    22  
    23  	// Wait blocks until the filter has shut down, and returns any error
    24  	// encountered in the process.
    25  	Wait() error
    26  
    27  	// Kill causes the filter to start shutting down if it has not already done so.
    28  	Kill()
    29  
    30  	// UnitDying returns a channel which is closed when the Unit enters a Dying state.
    31  	UnitDying() <-chan struct{}
    32  
    33  	// UpgradeEvents returns a channel that will receive a new charm URL whenever an
    34  	// upgrade is indicated. Events should not be read until the baseline state
    35  	// has been specified by calling WantUpgradeEvent.
    36  	UpgradeEvents() <-chan *charm.URL
    37  
    38  	// ResolvedEvents returns a channel that may receive a ResolvedMode when the
    39  	// unit's Resolved value changes, or when an event is explicitly requested.
    40  	// A ResolvedNone state will never generate events, but ResolvedRetryHooks and
    41  	// ResolvedNoHooks will always be delivered as described.
    42  	ResolvedEvents() <-chan params.ResolvedMode
    43  
    44  	// MeterStatusEvents returns a channel that will receive a signal when the unit's
    45  	// meter status changes.
    46  	MeterStatusEvents() <-chan struct{}
    47  
    48  	// ConfigEvents returns a channel that will receive a signal whenever the service's
    49  	// configuration changes, or when an event is explicitly requested.
    50  	ConfigEvents() <-chan struct{}
    51  
    52  	// ActionEvents returns a channel that will receive a signal whenever the unit
    53  	// receives new Actions.
    54  	ActionEvents() <-chan string
    55  
    56  	// RelationsEvents returns a channel that will receive the ids of all the service's
    57  	// relations whose Life status has changed.
    58  	RelationsEvents() <-chan []int
    59  
    60  	// StorageEvents returns a channel that will receive the tags of all the unit's
    61  	// associated storage instances whose Life status has changed.
    62  	StorageEvents() <-chan []names.StorageTag
    63  
    64  	// WantUpgradeEvent controls whether the filter will generate upgrade
    65  	// events for unforced service charm changes.
    66  	WantUpgradeEvent(mustForce bool)
    67  
    68  	// SetCharm notifies the filter that the unit is running a new
    69  	// charm. It causes the unit's charm URL to be set in state, and the
    70  	// following changes to the filter's behaviour:
    71  	//
    72  	// * Upgrade events will only be generated for charms different to
    73  	//   that supplied;
    74  	// * A fresh relations event will be generated containing every relation
    75  	//   the service is participating in;
    76  	// * A fresh configuration event will be generated, and subsequent
    77  	//   events will only be sent in response to changes in the version
    78  	//   of the service's settings that is specific to that charm.
    79  	//
    80  	// SetCharm blocks until the charm URL is set in state, returning any
    81  	// error that occurred.
    82  	SetCharm(curl *charm.URL) error
    83  
    84  	// WantResolvedEvent indicates that the filter should send a resolved event
    85  	// if one is available.
    86  	WantResolvedEvent()
    87  
    88  	// ClearResolved notifies the filter that a resolved event has been handled
    89  	// and should not be reported again.
    90  	ClearResolved() error
    91  
    92  	// DiscardConfigEvent indicates that the filter should discard any pending
    93  	// config event.
    94  	DiscardConfigEvent()
    95  
    96  	// LeaderSettingsEvents returns a channel that will receive an event whenever
    97  	// there is a leader settings change. Events can be temporarily suspended by
    98  	// calling WantLeaderSettingsEvents(false), and then reenabled by calling
    99  	// WantLeaderSettingsEvents(true)
   100  	LeaderSettingsEvents() <-chan struct{}
   101  
   102  	// DiscardLeaderSettingsEvent can be called to discard any pending
   103  	// LeaderSettingsEvents. This is used by code that saw a LeaderSettings change,
   104  	// and has been prepping for a response. Just before they request the current
   105  	// LeaderSettings, they can discard any other pending changes, since they know
   106  	// they will be handling all changes that have occurred before right now.
   107  	DiscardLeaderSettingsEvent()
   108  
   109  	// WantLeaderSettingsEvents can be used to enable/disable events being sent on
   110  	// the LeaderSettingsEvents() channel. This is used when an agent notices that
   111  	// it is the leader, it wants to disable getting events for changes that it is
   112  	// generating. Calling this with sendEvents=false disables getting change
   113  	// events. Calling this with sendEvents=true will enable future changes, and
   114  	// queues up an immediate event so that the agent will refresh its information
   115  	// for any events it might have missed while it thought it was the leader.
   116  	WantLeaderSettingsEvents(sendEvents bool)
   117  }