cache

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 minions), and one that additionally acts as a FIFO queue (for example, to allow a scheduler to process incoming pods).

Index

• func MetaNamespaceIndexFunc(obj interface{}) (string, error)
• func MetaNamespaceKeyFunc(obj interface{}) (string, error)
• func NewNamespaceKeyedIndexerAndReflector(lw ListerWatcher, expectedType interface{}, resyncPeriod time.Duration) (indexer Indexer, reflector *Reflector)
• type Enumerator
• type FIFO
  • func NewFIFO(keyFunc KeyFunc) *FIFO
  • func (f *FIFO) Add(obj interface{}) error
  • func (f *FIFO) AddIfNotPresent(obj interface{}) error
  • func (f *FIFO) Delete(obj interface{}) error
  • func (f *FIFO) Get(obj interface{}) (item interface{}, exists bool, err error)
  • func (f *FIFO) GetByKey(key string) (item interface{}, exists bool, err error)
  • func (f *FIFO) List() []interface{}
  • func (f *FIFO) Pop() interface{}
  • func (f *FIFO) Replace(list []interface{}) error
  • func (f *FIFO) Update(obj interface{}) error
• type GetFunc
• type Index
• type IndexFunc
• type Indexer
  • func NewIndexer(keyFunc KeyFunc, indexers Indexers) Indexer
• type Indexers
• type Indices
• type KeyFunc
• type ListFunc
• type ListWatch
  • func NewListWatchFromClient(client *client.Client, resource string, namespace string, ...) *ListWatch
  • func (lw *ListWatch) List() (runtime.Object, error)
  • func (lw *ListWatch) Watch(resourceVersion string) (watch.Interface, error)
• type ListerWatcher
• type Poller
  • func NewPoller(getFunc GetFunc, period time.Duration, store Store) *Poller
  • func (p *Poller) Run()
  • func (p *Poller) RunUntil(stopCh <-chan struct{})
• type Reflector
  • func NewReflector(lw ListerWatcher, expectedType interface{}, store Store, ...) *Reflector
  • func (r *Reflector) Run()
  • func (r *Reflector) RunUntil(stopCh <-chan struct{})
• type Store
  • func NewStore(keyFunc KeyFunc) Store
• type StoreToNodeLister
  • func (s *StoreToNodeLister) GetNodeInfo(id string) (*api.Node, error)
  • func (s *StoreToNodeLister) List() (machines api.NodeList, err error)
• type StoreToPodLister
  • func (s *StoreToPodLister) List(selector labels.Selector) (pods []api.Pod, err error)
• type StoreToServiceLister
  • func (s *StoreToServiceLister) GetPodServices(pod api.Pod) (services []api.Service, err error)
  • func (s *StoreToServiceLister) List() (services api.ServiceList, err error)
• type UndeltaStore
  • func NewUndeltaStore(pushFunc func([]interface{}), keyFunc KeyFunc) *UndeltaStore
  • func (u *UndeltaStore) Add(obj interface{}) error
  • func (u *UndeltaStore) Delete(obj interface{}) error
  • func (u *UndeltaStore) Get(obj interface{}) (item interface{}, exists bool, err error)
  • func (u *UndeltaStore) GetByKey(key string) (item interface{}, exists bool, err error)
  • func (u *UndeltaStore) List() []interface{}
  • func (u *UndeltaStore) Replace(list []interface{}) error
  • func (u *UndeltaStore) Update(obj interface{}) error
• type WatchFunc

Functions

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>

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

Types

type Enumerator

type Enumerator interface {
	Len() int
	Get(index int) (object interface{})
}

Enumerator should be able to return the list of objects to be synced with one object at a time.

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.

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) 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) List

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

List returns a list of all the items.

func (*FIFO) Pop

func (f *FIFO) Pop() interface{}

Pop waits until an item is ready and 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 succesfully process it, you need to add it back with Add().

func (*FIFO) Replace

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

Replace will delete the contents of 'f', using instead the given map. 'f' takes ownersip 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) Update

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

Update is the same as Add in this implementation.

type GetFunc

type GetFunc func() (Enumerator, error)

GetFunc should return an enumerator that you wish the Poller to proccess.

type Index

type Index map[string]util.StringSet

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 provide an indexed value for an object.

type Indexer

type Indexer interface {
	Store
	// Retrieve list of objects that match on the named indexing function
	Index(indexName string, obj interface{}) ([]interface{}, error)
}

Indexer is a storage interface that lets you list objects using multiple indexing functions

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 KeyFunc

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

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

type ListFunc

type ListFunc func() (runtime.Object, error)

ListFunc knows how to list resources

type ListWatch

type ListWatch struct {
	ListFunc  ListFunc
	WatchFunc WatchFunc
}

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 NewListWatchFromClient

func NewListWatchFromClient(client *client.Client, resource string, namespace string, fieldSelector labels.Selector) *ListWatch

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

func (*ListWatch) List

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

List a set of apiserver resources

func (*ListWatch) Watch

func (lw *ListWatch) Watch(resourceVersion string) (watch.Interface, error)

Watch a set of apiserver resources

type ListerWatcher

type ListerWatcher 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() (runtime.Object, error)
	// Watch should begin a watch at the specified version.
	Watch(resourceVersion string) (watch.Interface, error)
}

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

type Poller

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

Poller is like Reflector, but it periodically polls instead of watching. This is intended to be a workaround for api objects that don't yet support watching.

func NewPoller

func NewPoller(getFunc GetFunc, period time.Duration, store Store) *Poller

NewPoller constructs a new poller. Note that polling probably doesn't make much sense to use along with the FIFO queue. The returned Poller will call getFunc and sync the objects in 'store' with the returned Enumerator, waiting 'period' between each call. It probably only makes sense to use a poller if you're treating the store as read-only.

func (*Poller) Run

func (p *Poller) Run()

Run begins polling. It starts a goroutine and returns immediately.

func (*Poller) RunUntil

func (p *Poller) RunUntil(stopCh <-chan struct{})

RunUntil begins polling. It starts a goroutine and returns immediately. It will stop when the stopCh is closed.

type Reflector

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

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

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. 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) Run

func (r *Reflector) Run()

Run starts a watch and handles watch events. Will restart the watch if it is closed. Run starts a goroutine and returns immediately.

func (*Reflector) RunUntil

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

RunUntil starts a watch and handles watch events. Will restart the watch if it is closed. RunUntil starts a goroutine and returns immediately. It will exit when stopCh is closed.

type Store

type Store interface {
	Add(obj interface{}) error
	Update(obj interface{}) error
	Delete(obj interface{}) error
	List() []interface{}
	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{}) 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 NewStore

func NewStore(keyFunc KeyFunc) Store

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

type StoreToNodeLister

type StoreToNodeLister struct {
	Store
}

StoreToNodeLister makes a Store have the List method of the client.NodeInterface The Store must contain (only) Nodes.

func (*StoreToNodeLister) GetNodeInfo

func (s *StoreToNodeLister) GetNodeInfo(id string) (*api.Node, error)

TODO Move this back to scheduler as a helper function that takes a Store, rather than a method of StoreToNodeLister. GetNodeInfo returns cached data for the minion 'id'.

func (*StoreToNodeLister) List

func (s *StoreToNodeLister) List() (machines api.NodeList, err error)

type StoreToPodLister

type StoreToPodLister struct {
	Store
}

StoreToPodLister makes a Store have the List method of the client.PodInterface The Store must contain (only) Pods.

Example: s := cache.NewStore() lw := cache.ListWatch{Client: c, FieldSelector: sel, Resource: "pods"} r := cache.NewReflector(lw, &api.Pod{}, s).Run() l := StoreToPodLister{s} l.List()

func (*StoreToPodLister) List

func (s *StoreToPodLister) List(selector labels.Selector) (pods []api.Pod, err error)

TODO Get rid of the selector because that is confusing because the user might not realize that there has already been some selection at the caching stage. Also, consistency will facilitate code generation. However, the pkg/client is inconsistent too.

type StoreToServiceLister

type StoreToServiceLister struct {
	Store
}

StoreToServiceLister makes a Store that has the List method of the client.ServiceInterface The Store must contain (only) Services.

func (*StoreToServiceLister) GetPodServices

func (s *StoreToServiceLister) GetPodServices(pod api.Pod) (services []api.Service, err error)

TODO: Move this back to scheduler as a helper function that takes a Store, rather than a method of StoreToServiceLister.

func (*StoreToServiceLister) List

func (s *StoreToServiceLister) List() (services api.ServiceList, err error)

type UndeltaStore

type UndeltaStore struct {
	ActualStore 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

func (*UndeltaStore) Delete

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

func (*UndeltaStore) Get

func (u *UndeltaStore) Get(obj interface{}) (item interface{}, exists bool, err error)

func (*UndeltaStore) GetByKey

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

func (*UndeltaStore) List

func (u *UndeltaStore) List() []interface{}

func (*UndeltaStore) Replace

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

func (*UndeltaStore) Update

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

type WatchFunc

type WatchFunc func(resourceVersion string) (watch.Interface, error)

WatchFunc knows how to watch resources