cache

package
v0.17.12 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 16, 2020 License: Apache-2.0 Imports: 35 Imported by: 49,680

Documentation

Overview

Package cache is a client-side caching mechanism. It is useful for reducing the number of server calls you'd otherwise need to make. Reflector watches a server and updates a Store. Two stores are provided; one that simply caches objects (for example, to allow a scheduler to list currently available nodes), and one that additionally acts as a FIFO queue (for example, to allow a scheduler to process incoming pods).

Example 
// source simulates an apiserver object endpoint.
source := fcache.NewFakeControllerSource()

// This will hold the downstream state, as we know it.
downstream := NewStore(DeletionHandlingMetaNamespaceKeyFunc)

// This will hold incoming changes. Note how we pass downstream in as a
// KeyLister, that way resync operations will result in the correct set
// of update/delete deltas.
fifo := NewDeltaFIFO(MetaNamespaceKeyFunc, downstream)

// Let's do threadsafe output to get predictable test results.
deletionCounter := make(chan string, 1000)

cfg := &Config{
	Queue:            fifo,
	ListerWatcher:    source,
	ObjectType:       &v1.Pod{},
	FullResyncPeriod: time.Millisecond * 100,
	RetryOnError:     false,

	// Let's implement a simple controller that just deletes
	// everything that comes in.
	Process: func(obj interface{}) error {
		// Obj is from the Pop method of the Queue we make above.
		newest := obj.(Deltas).Newest()

		if newest.Type != Deleted {
			// Update our downstream store.
			err := downstream.Add(newest.Object)
			if err != nil {
				return err
			}

			// Delete this object.
			source.Delete(newest.Object.(runtime.Object))
		} else {
			// Update our downstream store.
			err := downstream.Delete(newest.Object)
			if err != nil {
				return err
			}

			// fifo's KeyOf is easiest, because it handles
			// DeletedFinalStateUnknown markers.
			key, err := fifo.KeyOf(newest.Object)
			if err != nil {
				return err
			}

			// Report this deletion.
			deletionCounter <- key
		}
		return nil
	},
}

// Create the controller and run it until we close stop.
stop := make(chan struct{})
defer close(stop)
go New(cfg).Run(stop)

// Let's add a few objects to the source.
testIDs := []string{"a-hello", "b-controller", "c-framework"}
for _, name := range testIDs {
	// Note that these pods are not valid-- the fake source doesn't
	// call validation or anything.
	source.Add(&v1.Pod{ObjectMeta: metav1.ObjectMeta{Name: name}})
}

// Let's wait for the controller to process the things we just added.
outputSet := sets.String{}
for i := 0; i < len(testIDs); i++ {
	outputSet.Insert(<-deletionCounter)
}

for _, key := range outputSet.List() {
	fmt.Println(key)
}

Output:

a-hello
b-controller
c-framework

Index

Examples

Constants

View Source 
const (
	// NamespaceIndex is the lookup name for the most comment index function, which is to index by the namespace field.
	NamespaceIndex string = "namespace"
)

Variables

View Source 
var ErrFIFOClosed = errors.New("DeltaFIFO: manipulating with closed queue")

ErrFIFOClosed used when FIFO is closed

View Source 
var (
	// ErrZeroLengthDeltasObject is returned in a KeyError if a Deltas
	// object with zero length is encountered (should be impossible,
	// but included for completeness).
	ErrZeroLengthDeltasObject = errors.New("0 length Deltas object; can't get key")
)

Functions

func DeletionHandlingMetaNamespaceKeyFunc 

func DeletionHandlingMetaNamespaceKeyFunc(obj interface{}) (string, error)

DeletionHandlingMetaNamespaceKeyFunc checks for DeletedFinalStateUnknown objects before calling MetaNamespaceKeyFunc.

func ListAll 

func ListAll(store Store, selector labels.Selector, appendFn AppendFunc) error

ListAll calls appendFn with each value retrieved from store which matches the selector.

func ListAllByNamespace 

func ListAllByNamespace(indexer Indexer, namespace string, selector labels.Selector, appendFn AppendFunc) error

ListAllByNamespace used to list items belongs to namespace from Indexer.

func MetaNamespaceIndexFunc 

func MetaNamespaceIndexFunc(obj interface{}) ([]string, error)

MetaNamespaceIndexFunc is a default index function that indexes based on an object's namespace

func MetaNamespaceKeyFunc 

func MetaNamespaceKeyFunc(obj interface{}) (string, error)

MetaNamespaceKeyFunc is a convenient default KeyFunc which knows how to make keys for API objects which implement meta.Interface. The key uses the format <namespace>/<name> unless <namespace> is empty, then it's just <name>.

TODO: replace key-as-string with a key-as-struct so that this packing/unpacking won't be necessary.

func NewIndexerInformer 

func NewIndexerInformer(
	lw ListerWatcher,
	objType runtime.Object,
	resyncPeriod time.Duration,
	h ResourceEventHandler,
	indexers Indexers,
) (Indexer, Controller)

NewIndexerInformer returns a Indexer and a controller for populating the index while also providing event notifications. You should only used the returned Index for Get/List operations; Add/Modify/Deletes will cause the event notifications to be faulty.

Parameters:

  • lw is list and watch functions for the source of the resource you want to be informed of.
  • objType is an object of the type that you expect to receive.
  • resyncPeriod: if non-zero, will re-list this often (you will get OnUpdate calls, even if nothing changed). Otherwise, re-list will be delayed as long as possible (until the upstream source closes the watch or times out, or you stop the controller).
  • h is the object you want notifications sent to.
  • indexers is the indexer for the received object type.

func NewInformer 

func NewInformer(
	lw ListerWatcher,
	objType runtime.Object,
	resyncPeriod time.Duration,
	h ResourceEventHandler,
) (Store, Controller)

NewInformer returns a Store and a controller for populating the store while also providing event notifications. You should only used the returned Store for Get/List operations; Add/Modify/Deletes will cause the event notifications to be faulty.

Parameters:

  • lw is list and watch functions for the source of the resource you want to be informed of.
  • objType is an object of the type that you expect to receive.
  • resyncPeriod: if non-zero, will re-list this often (you will get OnUpdate calls, even if nothing changed). Otherwise, re-list will be delayed as long as possible (until the upstream source closes the watch or times out, or you stop the controller).
  • h is the object you want notifications sent to.
Example 
// source simulates an apiserver object endpoint.
source := fcache.NewFakeControllerSource()

// Let's do threadsafe output to get predictable test results.
deletionCounter := make(chan string, 1000)

// Make a controller that immediately deletes anything added to it, and
// logs anything deleted.
_, controller := NewInformer(
	source,
	&v1.Pod{},
	time.Millisecond*100,
	ResourceEventHandlerFuncs{
		AddFunc: func(obj interface{}) {
			source.Delete(obj.(runtime.Object))
		},
		DeleteFunc: func(obj interface{}) {
			key, err := DeletionHandlingMetaNamespaceKeyFunc(obj)
			if err != nil {
				key = "oops something went wrong with the key"
			}

			// Report this deletion.
			deletionCounter <- key
		},
	},
)

// Run the controller and run it until we close stop.
stop := make(chan struct{})
defer close(stop)
go controller.Run(stop)

// Let's add a few objects to the source.
testIDs := []string{"a-hello", "b-controller", "c-framework"}
for _, name := range testIDs {
	// Note that these pods are not valid-- the fake source doesn't
	// call validation or anything.
	source.Add(&v1.Pod{ObjectMeta: metav1.ObjectMeta{Name: name}})
}

// Let's wait for the controller to process the things we just added.
outputSet := sets.String{}
for i := 0; i < len(testIDs); i++ {
	outputSet.Insert(<-deletionCounter)
}

for _, key := range outputSet.List() {
	fmt.Println(key)
}

Output:

a-hello
b-controller
c-framework

func NewNamespaceKeyedIndexerAndReflector 

func NewNamespaceKeyedIndexerAndReflector(lw ListerWatcher, expectedType interface{}, resyncPeriod time.Duration) (indexer Indexer, reflector *Reflector)

NewNamespaceKeyedIndexerAndReflector creates an Indexer and a Reflector The indexer is configured to key on namespace

func Pop 

func Pop(queue Queue) interface{}

Pop is helper function for popping from Queue. WARNING: Do NOT use this function in non-test code to avoid races unless you really really really really know what you are doing.

func SetReflectorMetricsProvider 

func SetReflectorMetricsProvider(metricsProvider MetricsProvider)

SetReflectorMetricsProvider sets the metrics provider

func SplitMetaNamespaceKey 

func SplitMetaNamespaceKey(key string) (namespace, name string, err error)

SplitMetaNamespaceKey returns the namespace and name that MetaNamespaceKeyFunc encoded into key.

TODO: replace key-as-string with a key-as-struct so that this packing/unpacking won't be necessary.

func WaitForCacheSync 

func WaitForCacheSync(stopCh <-chan struct{}, cacheSyncs ...InformerSynced) bool

WaitForCacheSync waits for caches to populate. It returns true if it was successful, false if the controller should shutdown callers should prefer WaitForNamedCacheSync()

func WaitForNamedCacheSync added in v0.16.4 

func WaitForNamedCacheSync(controllerName string, stopCh <-chan struct{}, cacheSyncs ...InformerSynced) bool

WaitForNamedCacheSync is a wrapper around WaitForCacheSync that generates log messages indicating that the caller identified by name is waiting for syncs, followed by either a successful or failed sync.

Types

type AppendFunc 

type AppendFunc func(interface{})

AppendFunc is used to add a matching item to whatever list the caller is using

type Config 

type Config struct {
	// The queue for your objects - has to be a DeltaFIFO due to
	// assumptions in the implementation. Your Process() function
	// should accept the output of this Queue's Pop() method.
	Queue

	// Something that can list and watch your objects.
	ListerWatcher

	// Something that can process your objects.
	Process ProcessFunc

	// The type of your objects.
	ObjectType runtime.Object

	// Reprocess everything at least this often.
	// Note that if it takes longer for you to clear the queue than this
	// period, you will end up processing items in the order determined
	// by FIFO.Replace(). Currently, this is random. If this is a
	// problem, we can change that replacement policy to append new
	// things to the end of the queue instead of replacing the entire
	// queue.
	FullResyncPeriod time.Duration

	// ShouldResync, if specified, is invoked when the controller's reflector determines the next
	// periodic sync should occur. If this returns true, it means the reflector should proceed with
	// the resync.
	ShouldResync ShouldResyncFunc

	// If true, when Process() returns an error, re-enqueue the object.
	// TODO: add interface to let you inject a delay/backoff or drop
	//       the object completely if desired. Pass the object in
	//       question to this interface as a parameter.
	RetryOnError bool
}

Config contains all the settings for a Controller.

type Controller 

type Controller interface {
	Run(stopCh <-chan struct{})
	HasSynced() bool
	LastSyncResourceVersion() string
}

Controller is a generic controller framework.

func New 

func New(c *Config) Controller

New makes a new Controller from the given Config.

type CounterMetric 

type CounterMetric interface {
	Inc()
}

CounterMetric represents a single numerical value that only ever goes up.

type DeletedFinalStateUnknown 

type DeletedFinalStateUnknown struct {
	Key string
	Obj interface{}
}

DeletedFinalStateUnknown is placed into a DeltaFIFO in the case where an object was deleted but the watch deletion event was missed. In this case we don't know the final "resting" state of the object, so there's a chance the included `Obj` is stale.

type Delta 

type Delta struct {
	Type   DeltaType
	Object interface{}
}

Delta is the type stored by a DeltaFIFO. It tells you what change happened, and the object's state after* that change.

[*] Unless the change is a deletion, and then you'll get the final 

state of the object before it was deleted.

type DeltaFIFO 

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

DeltaFIFO is like FIFO, but allows you to process deletes.

DeltaFIFO is a producer-consumer queue, where a Reflector is intended to be the producer, and the consumer is whatever calls the Pop() method.

DeltaFIFO solves this use case:

  • You want to process every object change (delta) at most once.
  • When you process an object, you want to see everything that's happened to it since you last processed it.
  • You want to process the deletion of objects.
  • You might want to periodically reprocess objects.

DeltaFIFO's Pop(), Get(), and GetByKey() methods return interface{} to satisfy the Store/Queue interfaces, but it will always return an object of type Deltas.

A note on threading: If you call Pop() in parallel from multiple threads, you could end up with multiple threads processing slightly different versions of the same object.

A note on the KeyLister used by the DeltaFIFO: It's main purpose is to list keys that are "known", for the purpose of figuring out which items have been deleted when Replace() or Delete() are called. The deleted object will be included in the DeleteFinalStateUnknown markers. These objects could be stale.

func NewDeltaFIFO 

func NewDeltaFIFO(keyFunc KeyFunc, knownObjects KeyListerGetter) *DeltaFIFO

NewDeltaFIFO returns a Store which can be used process changes to items.

keyFunc is used to figure out what key an object should have. (It's exposed in the returned DeltaFIFO's KeyOf() method, with bonus features.)

'keyLister' is expected to return a list of keys that the consumer of this queue "knows about". It is used to decide which items are missing when Replace() is called; 'Deleted' deltas are produced for these items. It may be nil if you don't need to detect all deletions. TODO: consider merging keyLister with this object, tracking a list of 

"known" keys when Pop() is called. Have to think about how that
affects error retrying.

NOTE: It is possible to misuse this and cause a race when using an 

external known object source.
Whether there is a potential race depends on how the comsumer
modifies knownObjects. In Pop(), process function is called under
lock, so it is safe to update data structures in it that need to be
in sync with the queue (e.g. knownObjects).

Example:
In case of sharedIndexInformer being a consumer
(https://github.com/kubernetes/kubernetes/blob/0cdd940f/staging/
src/k8s.io/client-go/tools/cache/shared_informer.go#L192),
there is no race as knownObjects (s.indexer) is modified safely
under DeltaFIFO's lock. The only exceptions are GetStore() and
GetIndexer() methods, which expose ways to modify the underlying
storage. Currently these two methods are used for creating Lister
and internal tests.

Also see the comment on DeltaFIFO.

func (*DeltaFIFO) Add 

func (f *DeltaFIFO) Add(obj interface{}) error

Add inserts an item, and puts it in the queue. The item is only enqueued if it doesn't already exist in the set.

func (*DeltaFIFO) AddIfNotPresent 

func (f *DeltaFIFO) AddIfNotPresent(obj interface{}) error

AddIfNotPresent inserts an item, and puts it in the queue. If the item is already present in the set, it is neither enqueued nor added to the set.

This is useful in a single producer/consumer scenario so that the consumer can safely retry items without contending with the producer and potentially enqueueing stale items.

Important: obj must be a Deltas (the output of the Pop() function). Yes, this is different from the Add/Update/Delete functions.

func (*DeltaFIFO) Close 

func (f *DeltaFIFO) Close()

Close the queue.

func (*DeltaFIFO) Delete 

func (f *DeltaFIFO) Delete(obj interface{}) error

Delete is just like Add, but makes an Deleted Delta. If the item does not already exist, it will be ignored. (It may have already been deleted by a Replace (re-list), for example.

func (*DeltaFIFO) Get 

func (f *DeltaFIFO) Get(obj interface{}) (item interface{}, exists bool, err error)

Get returns the complete list of deltas for the requested item, or sets exists=false. You should treat the items returned inside the deltas as immutable.

func (*DeltaFIFO) GetByKey 

func (f *DeltaFIFO) GetByKey(key string) (item interface{}, exists bool, err error)

GetByKey returns the complete list of deltas for the requested item, setting exists=false if that list is empty. You should treat the items returned inside the deltas as immutable.

func (*DeltaFIFO) HasSynced 

func (f *DeltaFIFO) HasSynced() bool

HasSynced returns true if an Add/Update/Delete/AddIfNotPresent are called first, or an Update called first but the first batch of items inserted by Replace() has been popped

func (*DeltaFIFO) IsClosed 

func (f *DeltaFIFO) IsClosed() bool

IsClosed checks if the queue is closed

func (*DeltaFIFO) KeyOf 

func (f *DeltaFIFO) KeyOf(obj interface{}) (string, error)

KeyOf exposes f's keyFunc, but also detects the key of a Deltas object or DeletedFinalStateUnknown objects.

func (*DeltaFIFO) List 

func (f *DeltaFIFO) List() []interface{}

List returns a list of all the items; it returns the object from the most recent Delta. You should treat the items returned inside the deltas as immutable.

func (*DeltaFIFO) ListKeys 

func (f *DeltaFIFO) ListKeys() []string

ListKeys returns a list of all the keys of the objects currently in the FIFO.

func (*DeltaFIFO) Pop 

func (f *DeltaFIFO) Pop(process PopProcessFunc) (interface{}, error)

Pop blocks until an item is added to the queue, and then returns it. If multiple items are ready, they are returned in the order in which they were added/updated. The item is removed from the queue (and the store) before it is returned, so if you don't successfully process it, you need to add it back with AddIfNotPresent(). process function is called under lock, so it is safe update data structures in it that need to be in sync with the queue (e.g. knownKeys). The PopProcessFunc may return an instance of ErrRequeue with a nested error to indicate the current item should be requeued (equivalent to calling AddIfNotPresent under the lock).

Pop returns a 'Deltas', which has a complete list of all the things that happened to the object (deltas) while it was sitting in the queue.

func (*DeltaFIFO) Replace 

func (f *DeltaFIFO) Replace(list []interface{}, resourceVersion string) error

Replace will delete the contents of 'f', using instead the given map. 'f' takes ownership of the map, you should not reference the map again after calling this function. f's queue is reset, too; upon return, it will contain the items in the map, in no particular order.

func (*DeltaFIFO) Resync 

func (f *DeltaFIFO) Resync() error

Resync will send a sync event for each item

func (*DeltaFIFO) Update 

func (f *DeltaFIFO) Update(obj interface{}) error

Update is just like Add, but makes an Updated Delta.

type DeltaType 

type DeltaType string

DeltaType is the type of a change (addition, deletion, etc) 

const (
	Added   DeltaType = "Added"
	Updated DeltaType = "Updated"
	Deleted DeltaType = "Deleted"
	// The other types are obvious. You'll get Sync deltas when:
	//  * A watch expires/errors out and a new list/watch cycle is started.
	//  * You've turned on periodic syncs.
	// (Anything that trigger's DeltaFIFO's Replace() method.)
	Sync DeltaType = "Sync"
)

Change type definition

type Deltas 

type Deltas []Delta

Deltas is a list of one or more 'Delta's to an individual object. The oldest delta is at index 0, the newest delta is the last one.

func (Deltas) Newest 

func (d Deltas) Newest() *Delta

Newest is a convenience function that returns the newest delta, or nil if there are no deltas.

func (Deltas) Oldest 

func (d Deltas) Oldest() *Delta

Oldest is a convenience function that returns the oldest delta, or nil if there are no deltas.

type ErrRequeue 

type ErrRequeue struct {
	// Err is returned by the Pop function
	Err error
}

ErrRequeue may be returned by a PopProcessFunc to safely requeue the current item. The value of Err will be returned from Pop.

func (ErrRequeue) Error 

func (e ErrRequeue) Error() string

type ExpirationCache 

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

ExpirationCache implements the store interface

  1. All entries are automatically time stamped on insert a. The key is computed based off the original item/keyFunc b. The value inserted under that key is the timestamped item
  2. Expiration happens lazily on read based on the expiration policy a. No item can be inserted into the store while we're expiring *any* item in the cache.
  3. Time-stamps are stripped off unexpired entries before return

Note that the ExpirationCache is inherently slower than a normal threadSafeStore because it takes a write lock every time it checks if an item has expired.

func (*ExpirationCache) Add 

func (c *ExpirationCache) Add(obj interface{}) error

Add timestamps an item and inserts it into the cache, overwriting entries that might exist under the same key.

func (*ExpirationCache) Delete 

func (c *ExpirationCache) Delete(obj interface{}) error

Delete removes an item from the cache.

func (*ExpirationCache) Get 

func (c *ExpirationCache) Get(obj interface{}) (interface{}, bool, error)

Get returns unexpired items. It purges the cache of expired items in the process.

func (*ExpirationCache) GetByKey 

func (c *ExpirationCache) GetByKey(key string) (interface{}, bool, error)

GetByKey returns the item stored under the key, or sets exists=false.

func (*ExpirationCache) List 

func (c *ExpirationCache) List() []interface{}

List retrieves a list of unexpired items. It purges the cache of expired items in the process.

func (*ExpirationCache) ListKeys 

func (c *ExpirationCache) ListKeys() []string

ListKeys returns a list of all keys in the expiration cache.

func (*ExpirationCache) Replace 

func (c *ExpirationCache) Replace(list []interface{}, resourceVersion string) error

Replace will convert all items in the given list to TimestampedEntries before attempting the replace operation. The replace operation will delete the contents of the ExpirationCache `c`.

func (*ExpirationCache) Resync 

func (c *ExpirationCache) Resync() error

Resync will touch all objects to put them into the processing queue

func (*ExpirationCache) Update 

func (c *ExpirationCache) Update(obj interface{}) error

Update has not been implemented yet for lack of a use case, so this method simply calls `Add`. This effectively refreshes the timestamp.

type ExpirationPolicy 

type ExpirationPolicy interface {
	IsExpired(obj *TimestampedEntry) bool
}

ExpirationPolicy dictates when an object expires. Currently only abstracted out so unittests don't rely on the system clock.

type ExplicitKey 

type ExplicitKey string

ExplicitKey can be passed to MetaNamespaceKeyFunc if you have the key for the object but not the object itself.

type FIFO 

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

FIFO receives adds and updates from a Reflector, and puts them in a queue for FIFO order processing. If multiple adds/updates of a single item happen while an item is in the queue before it has been processed, it will only be processed once, and when it is processed, the most recent version will be processed. This can't be done with a channel.

FIFO solves this use case:

  • You want to process every object (exactly) once.
  • You want to process the most recent version of the object when you process it.
  • You do not want to process deleted objects, they should be removed from the queue.
  • You do not want to periodically reprocess objects.

Compare with DeltaFIFO for other use cases.

func NewFIFO 

func NewFIFO(keyFunc KeyFunc) *FIFO

NewFIFO returns a Store which can be used to queue up items to process.

func (*FIFO) Add 

func (f *FIFO) Add(obj interface{}) error

Add inserts an item, and puts it in the queue. The item is only enqueued if it doesn't already exist in the set.

func (*FIFO) AddIfNotPresent 

func (f *FIFO) AddIfNotPresent(obj interface{}) error

AddIfNotPresent inserts an item, and puts it in the queue. If the item is already present in the set, it is neither enqueued nor added to the set.

This is useful in a single producer/consumer scenario so that the consumer can safely retry items without contending with the producer and potentially enqueueing stale items.

func (*FIFO) Close 

func (f *FIFO) Close()

Close the queue.

func (*FIFO) Delete 

func (f *FIFO) Delete(obj interface{}) error

Delete removes an item. It doesn't add it to the queue, because this implementation assumes the consumer only cares about the objects, not the order in which they were created/added.

func (*FIFO) Get 

func (f *FIFO) Get(obj interface{}) (item interface{}, exists bool, err error)

Get returns the requested item, or sets exists=false.

func (*FIFO) GetByKey 

func (f *FIFO) GetByKey(key string) (item interface{}, exists bool, err error)

GetByKey returns the requested item, or sets exists=false.

func (*FIFO) HasSynced 

func (f *FIFO) HasSynced() bool

HasSynced returns true if an Add/Update/Delete/AddIfNotPresent are called first, or an Update called first but the first batch of items inserted by Replace() has been popped

func (*FIFO) IsClosed 

func (f *FIFO) IsClosed() bool

IsClosed checks if the queue is closed

func (*FIFO) List 

func (f *FIFO) List() []interface{}

List returns a list of all the items.

func (*FIFO) ListKeys 

func (f *FIFO) ListKeys() []string

ListKeys returns a list of all the keys of the objects currently in the FIFO.

func (*FIFO) Pop 

func (f *FIFO) Pop(process PopProcessFunc) (interface{}, error)

Pop waits until an item is ready and processes it. If multiple items are ready, they are returned in the order in which they were added/updated. The item is removed from the queue (and the store) before it is processed, so if you don't successfully process it, it should be added back with AddIfNotPresent(). process function is called under lock, so it is safe update data structures in it that need to be in sync with the queue.

func (*FIFO) Replace 

func (f *FIFO) Replace(list []interface{}, resourceVersion string) error

Replace will delete the contents of 'f', using instead the given map. 'f' takes ownership of the map, you should not reference the map again after calling this function. f's queue is reset, too; upon return, it will contain the items in the map, in no particular order.

func (*FIFO) Resync 

func (f *FIFO) Resync() error

Resync will touch all objects to put them into the processing queue

func (*FIFO) Update 

func (f *FIFO) Update(obj interface{}) error

Update is the same as Add in this implementation.

type FakeCustomStore 

type FakeCustomStore struct {
	AddFunc      func(obj interface{}) error
	UpdateFunc   func(obj interface{}) error
	DeleteFunc   func(obj interface{}) error
	ListFunc     func() []interface{}
	ListKeysFunc func() []string
	GetFunc      func(obj interface{}) (item interface{}, exists bool, err error)
	GetByKeyFunc func(key string) (item interface{}, exists bool, err error)
	ReplaceFunc  func(list []interface{}, resourceVersion string) error
	ResyncFunc   func() error
}

FakeCustomStore lets you define custom functions for store operations.

func (*FakeCustomStore) Add 

func (f *FakeCustomStore) Add(obj interface{}) error

Add calls the custom Add function if defined

func (*FakeCustomStore) Delete 

func (f *FakeCustomStore) Delete(obj interface{}) error

Delete calls the custom Delete function if defined

func (*FakeCustomStore) Get 

func (f *FakeCustomStore) Get(obj interface{}) (item interface{}, exists bool, err error)

Get calls the custom Get function if defined

func (*FakeCustomStore) GetByKey 

func (f *FakeCustomStore) GetByKey(key string) (item interface{}, exists bool, err error)

GetByKey calls the custom GetByKey function if defined

func (*FakeCustomStore) List 

func (f *FakeCustomStore) List() []interface{}

List calls the custom List function if defined

func (*FakeCustomStore) ListKeys 

func (f *FakeCustomStore) ListKeys() []string

ListKeys calls the custom ListKeys function if defined

func (*FakeCustomStore) Replace 

func (f *FakeCustomStore) Replace(list []interface{}, resourceVersion string) error

Replace calls the custom Replace function if defined

func (*FakeCustomStore) Resync 

func (f *FakeCustomStore) Resync() error

Resync calls the custom Resync function if defined

func (*FakeCustomStore) Update 

func (f *FakeCustomStore) Update(obj interface{}) error

Update calls the custom Update function if defined

type FakeExpirationPolicy 

type FakeExpirationPolicy struct {
	NeverExpire     sets.String
	RetrieveKeyFunc KeyFunc
}

FakeExpirationPolicy keeps the list for keys which never expires.

func (*FakeExpirationPolicy) IsExpired 

func (p *FakeExpirationPolicy) IsExpired(obj *TimestampedEntry) bool

IsExpired used to check if object is expired.

type FilteringResourceEventHandler 

type FilteringResourceEventHandler struct {
	FilterFunc func(obj interface{}) bool
	Handler    ResourceEventHandler
}

FilteringResourceEventHandler applies the provided filter to all events coming in, ensuring the appropriate nested handler method is invoked. An object that starts passing the filter after an update is considered an add, and an object that stops passing the filter after an update is considered a delete.

func (FilteringResourceEventHandler) OnAdd 

func (r FilteringResourceEventHandler) OnAdd(obj interface{})

OnAdd calls the nested handler only if the filter succeeds

func (FilteringResourceEventHandler) OnDelete 

func (r FilteringResourceEventHandler) OnDelete(obj interface{})

OnDelete calls the nested handler only if the filter succeeds

func (FilteringResourceEventHandler) OnUpdate 

func (r FilteringResourceEventHandler) OnUpdate(oldObj, newObj interface{})

OnUpdate ensures the proper handler is called depending on whether the filter matches

type GaugeMetric 

type GaugeMetric interface {
	Set(float64)
}

GaugeMetric represents a single numerical value that can arbitrarily go up and down.

type GenericLister 

type GenericLister interface {
	// List will return all objects across namespaces
	List(selector labels.Selector) (ret []runtime.Object, err error)
	// Get will attempt to retrieve assuming that name==key
	Get(name string) (runtime.Object, error)
	// ByNamespace will give you a GenericNamespaceLister for one namespace
	ByNamespace(namespace string) GenericNamespaceLister
}

GenericLister is a lister skin on a generic Indexer

func NewGenericLister 

func NewGenericLister(indexer Indexer, resource schema.GroupResource) GenericLister

NewGenericLister creates a new instance for the genericLister.

type GenericNamespaceLister 

type GenericNamespaceLister interface {
	// List will return all objects in this namespace
	List(selector labels.Selector) (ret []runtime.Object, err error)
	// Get will attempt to retrieve by namespace and name
	Get(name string) (runtime.Object, error)
}

GenericNamespaceLister is a lister skin on a generic Indexer

type Getter 

type Getter interface {
	Get() *restclient.Request
}

Getter interface knows how to access Get method from RESTClient.

type Heap 

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

Heap is a thread-safe producer/consumer queue that implements a heap data structure. It can be used to implement priority queues and similar data structures.

func NewHeap 

func NewHeap(keyFn KeyFunc, lessFn LessFunc) *Heap

NewHeap returns a Heap which can be used to queue up items to process.

func (*Heap) Add 

func (h *Heap) Add(obj interface{}) error

Add inserts an item, and puts it in the queue. The item is updated if it already exists.

func (*Heap) AddIfNotPresent 

func (h *Heap) AddIfNotPresent(obj interface{}) error

AddIfNotPresent inserts an item, and puts it in the queue. If an item with the key is present in the map, no changes is made to the item.

This is useful in a single producer/consumer scenario so that the consumer can safely retry items without contending with the producer and potentially enqueueing stale items.

func (*Heap) BulkAdd 

func (h *Heap) BulkAdd(list []interface{}) error

BulkAdd adds all the items in the list to the queue and then signals the condition variable. It is useful when the caller would like to add all of the items to the queue before consumer starts processing them.

func (*Heap) Close 

func (h *Heap) Close()

Close the Heap and signals condition variables that may be waiting to pop items from the heap.

func (*Heap) Delete 

func (h *Heap) Delete(obj interface{}) error

Delete removes an item.

func (*Heap) Get 

func (h *Heap) Get(obj interface{}) (interface{}, bool, error)

Get returns the requested item, or sets exists=false.

func (*Heap) GetByKey 

func (h *Heap) GetByKey(key string) (interface{}, bool, error)

GetByKey returns the requested item, or sets exists=false.

func (*Heap) IsClosed 

func (h *Heap) IsClosed() bool

IsClosed returns true if the queue is closed.

func (*Heap) List 

func (h *Heap) List() []interface{}

List returns a list of all the items.

func (*Heap) ListKeys 

func (h *Heap) ListKeys() []string

ListKeys returns a list of all the keys of the objects currently in the Heap.

func (*Heap) Pop 

func (h *Heap) Pop() (interface{}, error)

Pop waits until an item is ready. If multiple items are ready, they are returned in the order given by Heap.data.lessFunc.

func (*Heap) Update 

func (h *Heap) Update(obj interface{}) error

Update is the same as Add in this implementation. When the item does not exist, it is added.

type Index 

type Index map[string]sets.String

Index maps the indexed value to a set of keys in the store that match on that value

type IndexFunc 

type IndexFunc func(obj interface{}) ([]string, error)

IndexFunc knows how to compute the set of indexed values for an object.

type Indexer 

type Indexer interface {
	Store
	// Index returns the stored objects whose set of indexed values
	// intersects the set of indexed values of the given object, for
	// the named index
	Index(indexName string, obj interface{}) ([]interface{}, error)
	// IndexKeys returns the storage keys of the stored objects whose
	// set of indexed values for the named index includes the given
	// indexed value
	IndexKeys(indexName, indexedValue string) ([]string, error)
	// ListIndexFuncValues returns all the indexed values of the given index
	ListIndexFuncValues(indexName string) []string
	// ByIndex returns the stored objects whose set of indexed values
	// for the named index includes the given indexed value
	ByIndex(indexName, indexedValue string) ([]interface{}, error)
	// GetIndexer return the indexers
	GetIndexers() Indexers

	// AddIndexers adds more indexers to this store.  If you call this after you already have data
	// in the store, the results are undefined.
	AddIndexers(newIndexers Indexers) error
}

Indexer is a storage interface that lets you list objects using multiple indexing functions. There are three kinds of strings here. One is a storage key, as defined in the Store interface. Another kind is a name of an index. The third kind of string is an "indexed value", which is produced by an IndexFunc and can be a field value or any other string computed from the object.

func NewIndexer 

func NewIndexer(keyFunc KeyFunc, indexers Indexers) Indexer

NewIndexer returns an Indexer implemented simply with a map and a lock.

type Indexers 

type Indexers map[string]IndexFunc

Indexers maps a name to a IndexFunc

type Indices 

type Indices map[string]Index

Indices maps a name to an Index

type InformerSynced 

type InformerSynced func() bool

InformerSynced is a function that can be used to determine if an informer has synced. This is useful for determining if caches have synced.

type KeyError 

type KeyError struct {
	Obj interface{}
	Err error
}

KeyError will be returned any time a KeyFunc gives an error; it includes the object at fault.

func (KeyError) Error 

func (k KeyError) Error() string

Error gives a human-readable description of the error.

type KeyFunc 

type KeyFunc func(obj interface{}) (string, error)

KeyFunc knows how to make a key from an object. Implementations should be deterministic.

func IndexFuncToKeyFuncAdapter 

func IndexFuncToKeyFuncAdapter(indexFunc IndexFunc) KeyFunc

IndexFuncToKeyFuncAdapter adapts an indexFunc to a keyFunc. This is only useful if your index function returns unique values for every object. This conversion can create errors when more than one key is found. You should prefer to make proper key and index functions.

type KeyGetter 

type KeyGetter interface {
	GetByKey(key string) (interface{}, bool, error)
}

A KeyGetter is anything that knows how to get the value stored under a given key.

type KeyLister 

type KeyLister interface {
	ListKeys() []string
}

A KeyLister is anything that knows how to list its keys.

type KeyListerGetter 

type KeyListerGetter interface {
	KeyLister
	KeyGetter
}

A KeyListerGetter is anything that knows how to list its keys and look up by key.

type LessFunc 

type LessFunc func(interface{}, interface{}) bool

LessFunc is used to compare two objects in the heap.

type ListFunc 

type ListFunc func(options metav1.ListOptions) (runtime.Object, error)

ListFunc knows how to list resources

type ListWatch 

type ListWatch struct {
	ListFunc  ListFunc
	WatchFunc WatchFunc
	// DisableChunking requests no chunking for this list watcher.
	DisableChunking bool
}

ListWatch knows how to list and watch a set of apiserver resources. It satisfies the ListerWatcher interface. It is a convenience function for users of NewReflector, etc. ListFunc and WatchFunc must not be nil

func NewFilteredListWatchFromClient 

func NewFilteredListWatchFromClient(c Getter, resource string, namespace string, optionsModifier func(options *metav1.ListOptions)) *ListWatch

NewFilteredListWatchFromClient creates a new ListWatch from the specified client, resource, namespace, and option modifier. Option modifier is a function takes a ListOptions and modifies the consumed ListOptions. Provide customized modifier function to apply modification to ListOptions with a field selector, a label selector, or any other desired options.

func NewListWatchFromClient 

func NewListWatchFromClient(c Getter, resource string, namespace string, fieldSelector fields.Selector) *ListWatch

NewListWatchFromClient creates a new ListWatch from the specified client, resource, namespace and field selector.

func (*ListWatch) List 

func (lw *ListWatch) List(options metav1.ListOptions) (runtime.Object, error)

List a set of apiserver resources

func (*ListWatch) Watch 

func (lw *ListWatch) Watch(options metav1.ListOptions) (watch.Interface, error)

Watch a set of apiserver resources

type Lister 

type Lister interface {
	// List should return a list type object; the Items field will be extracted, and the
	// ResourceVersion field will be used to start the watch in the right place.
	List(options metav1.ListOptions) (runtime.Object, error)
}

Lister is any object that knows how to perform an initial list.

type ListerWatcher 

type ListerWatcher interface {
	Lister
	Watcher
}

ListerWatcher is any object that knows how to perform an initial list and start a watch on a resource.

type MetricsProvider 

type MetricsProvider interface {
	NewListsMetric(name string) CounterMetric
	NewListDurationMetric(name string) SummaryMetric
	NewItemsInListMetric(name string) SummaryMetric

	NewWatchesMetric(name string) CounterMetric
	NewShortWatchesMetric(name string) CounterMetric
	NewWatchDurationMetric(name string) SummaryMetric
	NewItemsInWatchMetric(name string) SummaryMetric

	NewLastResourceVersionMetric(name string) GaugeMetric
}

MetricsProvider generates various metrics used by the reflector.

type MutationCache 

type MutationCache interface {
	GetByKey(key string) (interface{}, bool, error)
	ByIndex(indexName, indexKey string) ([]interface{}, error)
	Mutation(interface{})
}

MutationCache is able to take the result of update operations and stores them in an LRU that can be used to provide a more current view of a requested object. It requires interpreting resourceVersions for comparisons. Implementations must be thread-safe. TODO find a way to layer this into an informer/lister

func NewIntegerResourceVersionMutationCache 

func NewIntegerResourceVersionMutationCache(backingCache Store, indexer Indexer, ttl time.Duration, includeAdds bool) MutationCache

NewIntegerResourceVersionMutationCache returns a MutationCache that understands how to deal with objects that have a resource version that:

  • is an integer
  • increases when updated
  • is comparable across the same resource in a namespace

Most backends will have these semantics. Indexer may be nil. ttl controls how long an item remains in the mutation cache before it is removed.

If includeAdds is true, objects in the mutation cache will be returned even if they don't exist in the underlying store. This is only safe if your use of the cache can handle mutation entries remaining in the cache for up to ttl when mutations and deletes occur very closely in time.

type MutationDetector added in v0.16.4 

type MutationDetector interface {
	AddObject(obj interface{})
	Run(stopCh <-chan struct{})
}

MutationDetector is able to monitor if the object be modified outside.

func NewCacheMutationDetector 

func NewCacheMutationDetector(name string) MutationDetector

NewCacheMutationDetector creates a new instance for the defaultCacheMutationDetector.

type PopProcessFunc 

type PopProcessFunc func(interface{}) error

PopProcessFunc is passed to Pop() method of Queue interface. It is supposed to process the element popped from the queue.

type ProcessFunc 

type ProcessFunc func(obj interface{}) error

ProcessFunc processes a single object.

type Queue 

type Queue interface {
	Store

	// Pop blocks until it has something to process.
	// It returns the object that was process and the result of processing.
	// The PopProcessFunc may return an ErrRequeue{...} to indicate the item
	// should be requeued before releasing the lock on the queue.
	Pop(PopProcessFunc) (interface{}, error)

	// AddIfNotPresent adds a value previously
	// returned by Pop back into the queue as long
	// as nothing else (presumably more recent)
	// has since been added.
	AddIfNotPresent(interface{}) error

	// HasSynced returns true if the first batch of items has been popped
	HasSynced() bool

	// Close queue
	Close()
}

Queue is exactly like a Store, but has a Pop() method too.

type Reflector 

type Reflector struct {
	ShouldResync func() bool

	// WatchListPageSize is the requested chunk size of initial and resync watch lists.
	// Defaults to pager.PageSize.
	WatchListPageSize int64
	// contains filtered or unexported fields
}

Reflector watches a specified resource and causes all changes to be reflected in the given store.

func NewNamedReflector 

func NewNamedReflector(name string, lw ListerWatcher, expectedType interface{}, store Store, resyncPeriod time.Duration) *Reflector

NewNamedReflector same as NewReflector, but with a specified name for logging

func NewReflector 

func NewReflector(lw ListerWatcher, expectedType interface{}, store Store, resyncPeriod time.Duration) *Reflector

NewReflector creates a new Reflector object which will keep the given store up to date with the server's contents for the given resource. Reflector promises to only put things in the store that have the type of expectedType, unless expectedType is nil. If resyncPeriod is non-zero, then lists will be executed after every resyncPeriod, so that you can use reflectors to periodically process everything as well as incrementally processing the things that change.

func (*Reflector) LastSyncResourceVersion 

func (r *Reflector) LastSyncResourceVersion() string

LastSyncResourceVersion is the resource version observed when last sync with the underlying store The value returned is not synchronized with access to the underlying store and is not thread-safe

func (*Reflector) ListAndWatch 

func (r *Reflector) ListAndWatch(stopCh <-chan struct{}) error

ListAndWatch first lists all items and get the resource version at the moment of call, and then use the resource version to watch. It returns error if ListAndWatch didn't even try to initialize watch.

func (*Reflector) Run 

func (r *Reflector) Run(stopCh <-chan struct{})

Run starts a watch and handles watch events. Will restart the watch if it is closed. Run will exit when stopCh is closed.

type ResourceEventHandler 

type ResourceEventHandler interface {
	OnAdd(obj interface{})
	OnUpdate(oldObj, newObj interface{})
	OnDelete(obj interface{})
}

ResourceEventHandler can handle notifications for events that happen to a resource. The events are informational only, so you can't return an error.

  • OnAdd is called when an object is added.
  • OnUpdate is called when an object is modified. Note that oldObj is the last known state of the object-- it is possible that several changes were combined together, so you can't use this to see every single change. OnUpdate is also called when a re-list happens, and it will get called even if nothing changed. This is useful for periodically evaluating or syncing something.
  • OnDelete will get the final state of the item if it is known, otherwise it will get an object of type DeletedFinalStateUnknown. This can happen if the watch is closed and misses the delete event and we don't notice the deletion until the subsequent re-list.

type ResourceEventHandlerFuncs 

type ResourceEventHandlerFuncs struct {
	AddFunc    func(obj interface{})
	UpdateFunc func(oldObj, newObj interface{})
	DeleteFunc func(obj interface{})
}

ResourceEventHandlerFuncs is an adaptor to let you easily specify as many or as few of the notification functions as you want while still implementing ResourceEventHandler.

func (ResourceEventHandlerFuncs) OnAdd 

func (r ResourceEventHandlerFuncs) OnAdd(obj interface{})

OnAdd calls AddFunc if it's not nil.

func (ResourceEventHandlerFuncs) OnDelete 

func (r ResourceEventHandlerFuncs) OnDelete(obj interface{})

OnDelete calls DeleteFunc if it's not nil.

func (ResourceEventHandlerFuncs) OnUpdate 

func (r ResourceEventHandlerFuncs) OnUpdate(oldObj, newObj interface{})

OnUpdate calls UpdateFunc if it's not nil.

type ResourceVersionComparator 

type ResourceVersionComparator interface {
	CompareResourceVersion(lhs, rhs runtime.Object) int
}

ResourceVersionComparator is able to compare object versions.

type SharedIndexInformer 

type SharedIndexInformer interface {
	SharedInformer
	// AddIndexers add indexers to the informer before it starts.
	AddIndexers(indexers Indexers) error
	GetIndexer() Indexer
}

SharedIndexInformer provides add and get Indexers ability based on SharedInformer.

func NewSharedIndexInformer 

func NewSharedIndexInformer(lw ListerWatcher, objType runtime.Object, defaultEventHandlerResyncPeriod time.Duration, indexers Indexers) SharedIndexInformer

NewSharedIndexInformer creates a new instance for the listwatcher.

type SharedInformer 

type SharedInformer interface {
	// AddEventHandler adds an event handler to the shared informer using the shared informer's resync
	// period.  Events to a single handler are delivered sequentially, but there is no coordination
	// between different handlers.
	AddEventHandler(handler ResourceEventHandler)
	// AddEventHandlerWithResyncPeriod adds an event handler to the
	// shared informer using the specified resync period.  The resync
	// operation consists of delivering to the handler a create
	// notification for every object in the informer's local cache; it
	// does not add any interactions with the authoritative storage.
	AddEventHandlerWithResyncPeriod(handler ResourceEventHandler, resyncPeriod time.Duration)
	// GetStore returns the informer's local cache as a Store.
	GetStore() Store
	// GetController gives back a synthetic interface that "votes" to start the informer
	GetController() Controller
	// Run starts and runs the shared informer, returning after it stops.
	// The informer will be stopped when stopCh is closed.
	Run(stopCh <-chan struct{})
	// HasSynced returns true if the shared informer's store has been
	// informed by at least one full LIST of the authoritative state
	// of the informer's object collection.  This is unrelated to "resync".
	HasSynced() bool
	// LastSyncResourceVersion is the resource version observed when last synced with the underlying
	// store. The value returned is not synchronized with access to the underlying store and is not
	// thread-safe.
	LastSyncResourceVersion() string
}

SharedInformer provides eventually consistent linkage of its clients to the authoritative state of a given collection of objects. An object is identified by its API group, kind/resource, namespace, and name; the `ObjectMeta.UID` is not part of an object's ID as far as this contract is concerned. One SharedInformer provides linkage to objects of a particular API group and kind/resource. The linked object collection of a SharedInformer may be further restricted to one namespace and/or by label selector and/or field selector.

The authoritative state of an object is what apiservers provide access to, and an object goes through a strict sequence of states. An object state is either "absent" or present with a ResourceVersion and other appropriate content.

A SharedInformer gets object states from apiservers using a sequence of LIST and WATCH operations. Through this sequence the apiservers provide a sequence of "collection states" to the informer, where each collection state defines the state of every object of the collection. No promise --- beyond what is implied by other remarks here --- is made about how one informer's sequence of collection states relates to a different informer's sequence of collection states.

A SharedInformer maintains a local cache, exposed by GetStore() and by GetIndexer() in the case of an indexed informer, of the state of each relevant object. This cache is eventually consistent with the authoritative state. This means that, unless prevented by persistent communication problems, if ever a particular object ID X is authoritatively associated with a state S then for every SharedInformer I whose collection includes (X, S) eventually either (1) I's cache associates X with S or a later state of X, (2) I is stopped, or (3) the authoritative state service for X terminates. To be formally complete, we say that the absent state meets any restriction by label selector or field selector.

The local cache starts out empty, and gets populated and updated during `Run()`.

As a simple example, if a collection of objects is henceforeth unchanging, a SharedInformer is created that links to that collection, and that SharedInformer is `Run()` then that SharedInformer's cache eventually holds an exact copy of that collection (unless it is stopped too soon, the authoritative state service ends, or communication problems between the two persistently thwart achievement).

As another simple example, if the local cache ever holds a non-absent state for some object ID and the object is eventually removed from the authoritative state then eventually the object is removed from the local cache (unless the SharedInformer is stopped too soon, the authoritative state service ends, or communication problems persistently thwart the desired result).

The keys in the Store are of the form namespace/name for namespaced objects, and are simply the name for non-namespaced objects. Clients can use `MetaNamespaceKeyFunc(obj)` to extract the key for a given object, and `SplitMetaNamespaceKey(key)` to split a key into its constituent parts.

A client is identified here by a ResourceEventHandler. For every update to the SharedInformer's local cache and for every client added before `Run()`, eventually either the SharedInformer is stopped or the client is notified of the update. A client added after `Run()` starts gets a startup batch of notifications of additions of the object existing in the cache at the time that client was added; also, for every update to the SharedInformer's local cache after that client was added, eventually either the SharedInformer is stopped or that client is notified of that update. Client notifications happen after the corresponding cache update and, in the case of a SharedIndexInformer, after the corresponding index updates. It is possible that additional cache and index updates happen before such a prescribed notification. For a given SharedInformer and client, the notifications are delivered sequentially. For a given SharedInformer, client, and object ID, the notifications are delivered in order.

A client must process each notification promptly; a SharedInformer is not engineered to deal well with a large backlog of notifications to deliver. Lengthy processing should be passed off to something else, for example through a `client-go/util/workqueue`.

Each query to an informer's local cache --- whether a single-object lookup, a list operation, or a use of one of its indices --- is answered entirely from one of the collection states received by that informer.

A delete notification exposes the last locally known non-absent state, except that its ResourceVersion is replaced with a ResourceVersion in which the object is actually absent.

func NewSharedInformer 

func NewSharedInformer(lw ListerWatcher, objType runtime.Object, resyncPeriod time.Duration) SharedInformer

NewSharedInformer creates a new instance for the listwatcher.

type ShouldResyncFunc 

type ShouldResyncFunc func() bool

ShouldResyncFunc is a type of function that indicates if a reflector should perform a resync or not. It can be used by a shared informer to support multiple event handlers with custom resync periods.

type Store 

type Store interface {
	Add(obj interface{}) error
	Update(obj interface{}) error
	Delete(obj interface{}) error
	List() []interface{}
	ListKeys() []string
	Get(obj interface{}) (item interface{}, exists bool, err error)
	GetByKey(key string) (item interface{}, exists bool, err error)

	// Replace will delete the contents of the store, using instead the
	// given list. Store takes ownership of the list, you should not reference
	// it after calling this function.
	Replace([]interface{}, string) error
	Resync() error
}

Store is a generic object storage interface. Reflector knows how to watch a server and update a store. A generic store is provided, which allows Reflector to be used as a local caching system, and an LRU store, which allows Reflector to work like a queue of items yet to be processed.

Store makes no assumptions about stored object identity; it is the responsibility of a Store implementation to provide a mechanism to correctly key objects and to define the contract for obtaining objects by some arbitrary key type.

func NewExpirationStore 

func NewExpirationStore(keyFunc KeyFunc, expirationPolicy ExpirationPolicy) Store

NewExpirationStore creates and returns a ExpirationCache for a given policy

func NewFakeExpirationStore 

func NewFakeExpirationStore(keyFunc KeyFunc, deletedKeys chan<- string, expirationPolicy ExpirationPolicy, cacheClock clock.Clock) Store

NewFakeExpirationStore creates a new instance for the ExpirationCache.

func NewStore 

func NewStore(keyFunc KeyFunc) Store

NewStore returns a Store implemented simply with a map and a lock.

func NewTTLStore 

func NewTTLStore(keyFunc KeyFunc, ttl time.Duration) Store

NewTTLStore creates and returns a ExpirationCache with a TTLPolicy

type SummaryMetric 

type SummaryMetric interface {
	Observe(float64)
}

SummaryMetric captures individual observations.

type TTLPolicy 

type TTLPolicy struct {
	//	 >0: Expire entries with an age > ttl
	//	<=0: Don't expire any entry
	TTL time.Duration

	// Clock used to calculate ttl expiration
	Clock clock.Clock
}

TTLPolicy implements a ttl based ExpirationPolicy.

func (*TTLPolicy) IsExpired 

func (p *TTLPolicy) IsExpired(obj *TimestampedEntry) bool

IsExpired returns true if the given object is older than the ttl, or it can't determine its age.

type ThreadSafeStore 

type ThreadSafeStore interface {
	Add(key string, obj interface{})
	Update(key string, obj interface{})
	Delete(key string)
	Get(key string) (item interface{}, exists bool)
	List() []interface{}
	ListKeys() []string
	Replace(map[string]interface{}, string)
	Index(indexName string, obj interface{}) ([]interface{}, error)
	IndexKeys(indexName, indexKey string) ([]string, error)
	ListIndexFuncValues(name string) []string
	ByIndex(indexName, indexKey string) ([]interface{}, error)
	GetIndexers() Indexers

	// AddIndexers adds more indexers to this store.  If you call this after you already have data
	// in the store, the results are undefined.
	AddIndexers(newIndexers Indexers) error
	Resync() error
}

ThreadSafeStore is an interface that allows concurrent access to a storage backend. TL;DR caveats: you must not modify anything returned by Get or List as it will break the indexing feature in addition to not being thread safe.

The guarantees of thread safety provided by List/Get are only valid if the caller treats returned items as read-only. For example, a pointer inserted in the store through `Add` will be returned as is by `Get`. Multiple clients might invoke `Get` on the same key and modify the pointer in a non-thread-safe way. Also note that modifying objects stored by the indexers (if any) will *not* automatically lead to a re-index. So it's not a good idea to directly modify the objects returned by Get/List, in general.

func NewThreadSafeStore 

func NewThreadSafeStore(indexers Indexers, indices Indices) ThreadSafeStore

NewThreadSafeStore creates a new instance of ThreadSafeStore.

type TimestampedEntry 

type TimestampedEntry struct {
	Obj       interface{}
	Timestamp time.Time
	// contains filtered or unexported fields
}

TimestampedEntry is the only type allowed in a ExpirationCache. Keep in mind that it is not safe to share timestamps between computers. Behavior may be inconsistent if you get a timestamp from the API Server and use it on the client machine as part of your ExpirationCache.

type UndeltaStore 

type UndeltaStore struct {
	Store
	PushFunc func([]interface{})
}

UndeltaStore listens to incremental updates and sends complete state on every change. It implements the Store interface so that it can receive a stream of mirrored objects from Reflector. Whenever it receives any complete (Store.Replace) or incremental change (Store.Add, Store.Update, Store.Delete), it sends the complete state by calling PushFunc. It is thread-safe. It guarantees that every change (Add, Update, Replace, Delete) results in one call to PushFunc, but sometimes PushFunc may be called twice with the same values. PushFunc should be thread safe.

func NewUndeltaStore 

func NewUndeltaStore(pushFunc func([]interface{}), keyFunc KeyFunc) *UndeltaStore

NewUndeltaStore returns an UndeltaStore implemented with a Store.

func (*UndeltaStore) Add 

func (u *UndeltaStore) Add(obj interface{}) error

Add inserts an object into the store and sends complete state by calling PushFunc. Note about thread safety. The Store implementation (cache.cache) uses a lock for all methods. In the functions below, the lock gets released and reacquired betweend the {Add,Delete,etc} and the List. So, the following can happen, resulting in two identical calls to PushFunc. time thread 1 thread 2 0 UndeltaStore.Add(a) 1 UndeltaStore.Add(b) 2 Store.Add(a) 3 Store.Add(b) 4 Store.List() -> [a,b] 5 Store.List() -> [a,b]

func (*UndeltaStore) Delete 

func (u *UndeltaStore) Delete(obj interface{}) error

Delete removes an item from the cache and sends complete state by calling PushFunc.

func (*UndeltaStore) Replace 

func (u *UndeltaStore) Replace(list []interface{}, resourceVersion string) error

Replace will delete the contents of current store, using instead the given list. 'u' takes ownership of the list, you should not reference the list again after calling this function. The new contents complete state will be sent by calling PushFunc after replacement.

func (*UndeltaStore) Update 

func (u *UndeltaStore) Update(obj interface{}) error

Update sets an item in the cache to its updated state and sends complete state by calling PushFunc.

type WatchFunc 

type WatchFunc func(options metav1.ListOptions) (watch.Interface, error)

WatchFunc knows how to watch resources

type Watcher 

type Watcher interface {
	// Watch should begin a watch at the specified version.
	Watch(options metav1.ListOptions) (watch.Interface, error)
}

Watcher is any object that knows how to start a watch on a resource.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.