schedulercache interface.go

interface.go

package schedulercache

import (
	"k8s.io/kubernetes/pkg/api"
	"k8s.io/kubernetes/pkg/labels"
)

// Cache collects pods' information and provides node-level aggregated information.
// It's intended for generic scheduler to do efficient lookup.
// Cache's operations are pod centric. It incrementally updates itself based on pod event.
// Pod events are sent via network. We don't have guaranteed delivery of all events.
// Thus, we organized the state machine flow of a pod's events as followed.
//
// State Machine of a pod's events in scheduler's cache:
//
//                                                +-------+
//                                                |       |
//                                                |       | Update
//           Assume                Add            +       |
// Initial +--------> Assumed +------------+---> Added <--+
//                       +                 |       +
//                       |                 |       |
//                       |             Add |       | Remove
//                       |                 |       |
//                       |                 +       |
//                       +-------------> Expired   +----> Deleted
//                          expire
//
// Note that an assumed pod would be expired. Because if we haven't received Add event
// notifying us that it's scheduled, there might be some problems and we shouldn't assume
// the pod scheduled anymore.
//
// Note that "Initial", "Expired", and "Deleted" pods do not actually exist in cache.
// Based on existing use cases, we are making following assumptions:
// - No same pod would be assumed twice
// - If a pod wasn't added before, it wouldn't be removed or updated.
// - Both "Expired" and "Deleted" are valid end states. An expired pod could never
//   be added if it missed all events due to network disconnection.
type Cache interface {
	// AssumePodIfBindSucceed assumes a pod to be scheduled only if the bind action succeeded. 
	// If so, The pod's information is aggregated into designated node.
	// Note that between bind and assume, there might be race that other events like Add, Remove 
	// would jump in. Thus we need to combine the two as a whole.
	// We are passing the bind function and let the cache to take care of concurrency.
	// The implementation might decide the policy to expire pod before being confirmed (receiving Add event).
	// After expiration, its information would be subtracted.
	AssumePodIfBindSucceed(pod *api.Pod, bind func() bool) error

	// AddPod will confirms a pod if it's assumed, or adds back if it's expired.
	// If added back, the pod's information would be added again.
	AddPod(pod *api.Pod) error

	// UpdatePod removes oldPod's information and adds newPod's information.
	UpdatePod(oldPod, newPod *api.Pod) error

	// RemovePod removes a pod. The pod's information would be subtracted from assigned node.
	RemovePod(pod *api.Pod) error

	// GetNodeNameToInfoMap returns a map of node names to node info. The node info contains aggregated information
	// of pods scheduled (including assumed to be) on this node.
	GetNodeNameToInfoMap() map[string]*NodeInfo

	// PodLister lists all pods added (including assumed) in this cache
	PodLister
}

type PodLister interface {
	List(labels.Selector) ([]*api.Pod, error)
}