Documentation

Overview

    Package watch contains a generic watchable interface, and a fake for testing code that uses the watch interface.

    Index

    Constants

    View Source
    const (
    	Added    EventType = "ADDED"
    	Modified EventType = "MODIFIED"
    	Deleted  EventType = "DELETED"
    	Error    EventType = "ERROR"
    
    	DefaultChanSize int32 = 100
    )

    Variables

    View Source
    var ErrWatchClosed = errors.New("watch closed before Until timeout")

      ErrWatchClosed is returned when the watch channel is closed before timeout in Until.

      Functions

      This section is empty.

      Types

      type Broadcaster

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

        Broadcaster distributes event notifications among any number of watchers. Every event is delivered to every watcher.

        func NewBroadcaster

        func NewBroadcaster(queueLength int, fullChannelBehavior FullChannelBehavior) *Broadcaster

          NewBroadcaster creates a new Broadcaster. queueLength is the maximum number of events to queue per watcher. It is guaranteed that events will be distributed in the order in which they occur, but the order in which a single event is distributed among all of the watchers is unspecified.

          func (*Broadcaster) Action

          func (m *Broadcaster) Action(action EventType, obj runtime.Object)

            Action distributes the given event among all watchers.

            func (*Broadcaster) Shutdown

            func (m *Broadcaster) Shutdown()

              Shutdown disconnects all watchers (but any queued events will still be distributed). You must not call Action or Watch* after calling Shutdown. This call blocks until all events have been distributed through the outbound channels. Note that since they can be buffered, this means that the watchers might not have received the data yet as it can remain sitting in the buffered channel.

              func (*Broadcaster) Watch

              func (m *Broadcaster) Watch() Interface

                Watch adds a new watcher to the list and returns an Interface for it. Note: new watchers will only receive new events. They won't get an entire history of previous events.

                func (*Broadcaster) WatchWithPrefix

                func (m *Broadcaster) WatchWithPrefix(queuedEvents []Event) Interface

                  WatchWithPrefix adds a new watcher to the list and returns an Interface for it. It sends queuedEvents down the new watch before beginning to send ordinary events from Broadcaster. The returned watch will have a queue length that is at least large enough to accommodate all of the items in queuedEvents.

                  type ConditionFunc

                  type ConditionFunc func(event Event) (bool, error)

                    ConditionFunc returns true if the condition has been reached, false if it has not been reached yet, or an error if the condition cannot be checked and should terminate. In general, it is better to define level driven conditions over edge driven conditions (pod has ready=true, vs pod modified and ready changed from false to true).

                    type Decoder

                    type Decoder interface {
                    	// Decode should return the type of event, the decoded object, or an error.
                    	// An error will cause StreamWatcher to call Close(). Decode should block until
                    	// it has data or an error occurs.
                    	Decode() (action EventType, object runtime.Object, err error)
                    
                    	// Close should close the underlying io.Reader, signalling to the source of
                    	// the stream that it is no longer being watched. Close() must cause any
                    	// outstanding call to Decode() to return with an error of some sort.
                    	Close()
                    }

                      Decoder allows StreamWatcher to watch any stream for which a Decoder can be written.

                      type Event

                      type Event struct {
                      	Type EventType
                      
                      	// Object is:
                      	//  * If Type is Added or Modified: the new state of the object.
                      	//  * If Type is Deleted: the state of the object immediately before deletion.
                      	//  * If Type is Error: *api.Status is recommended; other types may make sense
                      	//    depending on context.
                      	Object runtime.Object
                      }

                        Event represents a single event to a watched resource.

                        func Until

                        func Until(timeout time.Duration, watcher Interface, conditions ...ConditionFunc) (*Event, error)

                          Until reads items from the watch until each provided condition succeeds, and then returns the last watch encountered. The first condition that returns an error terminates the watch (and the event is also returned). If no event has been received, the returned event will be nil. Conditions are satisfied sequentially so as to provide a useful primitive for higher level composition. A zero timeout means to wait forever.

                          type EventType

                          type EventType string

                            EventType defines the possible types of events.

                            type FakeWatcher

                            type FakeWatcher struct {
                            	Stopped bool
                            	sync.Mutex
                            	// contains filtered or unexported fields
                            }

                              FakeWatcher lets you test anything that consumes a watch.Interface; threadsafe.

                              func NewFake

                              func NewFake() *FakeWatcher

                              func NewFakeWithChanSize

                              func NewFakeWithChanSize(size int, blocking bool) *FakeWatcher

                              func (*FakeWatcher) Action

                              func (f *FakeWatcher) Action(action EventType, obj runtime.Object)

                                Action sends an event of the requested type, for table-based testing.

                                func (*FakeWatcher) Add

                                func (f *FakeWatcher) Add(obj runtime.Object)

                                  Add sends an add event.

                                  func (*FakeWatcher) Delete

                                  func (f *FakeWatcher) Delete(lastValue runtime.Object)

                                    Delete sends a delete event.

                                    func (*FakeWatcher) Error

                                    func (f *FakeWatcher) Error(errValue runtime.Object)

                                      Error sends an Error event.

                                      func (*FakeWatcher) IsStopped

                                      func (f *FakeWatcher) IsStopped() bool

                                      func (*FakeWatcher) Modify

                                      func (f *FakeWatcher) Modify(obj runtime.Object)

                                        Modify sends a modify event.

                                        func (*FakeWatcher) Reset

                                        func (f *FakeWatcher) Reset()

                                          Reset prepares the watcher to be reused.

                                          func (*FakeWatcher) ResultChan

                                          func (f *FakeWatcher) ResultChan() <-chan Event

                                          func (*FakeWatcher) Stop

                                          func (f *FakeWatcher) Stop()

                                            Stop implements Interface.Stop().

                                            type FilterFunc

                                            type FilterFunc func(in Event) (out Event, keep bool)

                                              FilterFunc should take an event, possibly modify it in some way, and return the modified event. If the event should be ignored, then return keep=false.

                                              type FullChannelBehavior

                                              type FullChannelBehavior int

                                                FullChannelBehavior controls how the Broadcaster reacts if a watcher's watch channel is full.

                                                const (
                                                	WaitIfChannelFull FullChannelBehavior = iota
                                                	DropIfChannelFull
                                                )

                                                type Interface

                                                type Interface interface {
                                                	// Stops watching. Will close the channel returned by ResultChan(). Releases
                                                	// any resources used by the watch.
                                                	Stop()
                                                
                                                	// Returns a chan which will receive all the events. If an error occurs
                                                	// or Stop() is called, this channel will be closed, in which case the
                                                	// watch should be completely cleaned up.
                                                	ResultChan() <-chan Event
                                                }

                                                  Interface can be implemented by anything that knows how to watch and report changes.

                                                  func Filter

                                                  func Filter(w Interface, f FilterFunc) Interface

                                                    Filter passes all events through f before allowing them to pass on. Putting a filter on a watch, as an unavoidable side-effect due to the way go channels work, effectively causes the watch's event channel to have its queue length increased by one.

                                                    WARNING: filter has a fatal flaw, in that it can't properly update the Type field (Add/Modified/Deleted) to reflect items beginning to pass the filter when they previously didn't.

                                                    func NewEmptyWatch

                                                    func NewEmptyWatch() Interface

                                                      NewEmptyWatch returns a watch interface that returns no results and is closed. May be used in certain error conditions where no information is available but an error is not warranted.

                                                      type RaceFreeFakeWatcher

                                                      type RaceFreeFakeWatcher struct {
                                                      	Stopped bool
                                                      	sync.Mutex
                                                      	// contains filtered or unexported fields
                                                      }

                                                        RaceFreeFakeWatcher lets you test anything that consumes a watch.Interface; threadsafe.

                                                        func NewRaceFreeFake

                                                        func NewRaceFreeFake() *RaceFreeFakeWatcher

                                                        func (*RaceFreeFakeWatcher) Action

                                                        func (f *RaceFreeFakeWatcher) Action(action EventType, obj runtime.Object)

                                                          Action sends an event of the requested type, for table-based testing.

                                                          func (*RaceFreeFakeWatcher) Add

                                                          func (f *RaceFreeFakeWatcher) Add(obj runtime.Object)

                                                            Add sends an add event.

                                                            func (*RaceFreeFakeWatcher) Delete

                                                            func (f *RaceFreeFakeWatcher) Delete(lastValue runtime.Object)

                                                              Delete sends a delete event.

                                                              func (*RaceFreeFakeWatcher) Error

                                                              func (f *RaceFreeFakeWatcher) Error(errValue runtime.Object)

                                                                Error sends an Error event.

                                                                func (*RaceFreeFakeWatcher) IsStopped

                                                                func (f *RaceFreeFakeWatcher) IsStopped() bool

                                                                func (*RaceFreeFakeWatcher) Modify

                                                                func (f *RaceFreeFakeWatcher) Modify(obj runtime.Object)

                                                                  Modify sends a modify event.

                                                                  func (*RaceFreeFakeWatcher) Reset

                                                                  func (f *RaceFreeFakeWatcher) Reset()

                                                                    Reset prepares the watcher to be reused.

                                                                    func (*RaceFreeFakeWatcher) ResultChan

                                                                    func (f *RaceFreeFakeWatcher) ResultChan() <-chan Event

                                                                    func (*RaceFreeFakeWatcher) Stop

                                                                    func (f *RaceFreeFakeWatcher) Stop()

                                                                      Stop implements Interface.Stop().

                                                                      type Recorder

                                                                      type Recorder struct {
                                                                      	Interface
                                                                      	// contains filtered or unexported fields
                                                                      }

                                                                        Recorder records all events that are sent from the watch until it is closed.

                                                                        func NewRecorder

                                                                        func NewRecorder(w Interface) *Recorder

                                                                          NewRecorder wraps an Interface and records any changes sent across it.

                                                                          func (*Recorder) Events

                                                                          func (r *Recorder) Events() []Event

                                                                            Events returns a copy of the events sent across this recorder.

                                                                            type StreamWatcher

                                                                            type StreamWatcher struct {
                                                                            	sync.Mutex
                                                                            	// contains filtered or unexported fields
                                                                            }

                                                                              StreamWatcher turns any stream for which you can write a Decoder interface into a watch.Interface.

                                                                              func NewStreamWatcher

                                                                              func NewStreamWatcher(d Decoder) *StreamWatcher

                                                                                NewStreamWatcher creates a StreamWatcher from the given decoder.

                                                                                func (*StreamWatcher) ResultChan

                                                                                func (sw *StreamWatcher) ResultChan() <-chan Event

                                                                                  ResultChan implements Interface.

                                                                                  func (*StreamWatcher) Stop

                                                                                  func (sw *StreamWatcher) Stop()

                                                                                    Stop implements Interface.