sigs.k8s.io/kueue@v0.6.2/pkg/queue/cluster_queue_interface.go (about)

     1  /*
     2  Copyright 2022 The Kubernetes Authors.
     3  
     4  Licensed under the Apache License, Version 2.0 (the "License");
     5  you may not use this file except in compliance with the License.
     6  You may obtain a copy of the License at
     7  
     8      http://www.apache.org/licenses/LICENSE-2.0
     9  
    10  Unless required by applicable law or agreed to in writing, software
    11  distributed under the License is distributed on an "AS IS" BASIS,
    12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13  See the License for the specific language governing permissions and
    14  limitations under the License.
    15  */
    16  
    17  package queue
    18  
    19  import (
    20  	"context"
    21  	"fmt"
    22  
    23  	"sigs.k8s.io/controller-runtime/pkg/client"
    24  
    25  	kueue "sigs.k8s.io/kueue/apis/kueue/v1beta1"
    26  	"sigs.k8s.io/kueue/pkg/workload"
    27  )
    28  
    29  type RequeueReason string
    30  
    31  const (
    32  	RequeueReasonFailedAfterNomination RequeueReason = "FailedAfterNomination"
    33  	RequeueReasonNamespaceMismatch     RequeueReason = "NamespaceMismatch"
    34  	RequeueReasonGeneric               RequeueReason = ""
    35  	RequeueReasonPendingPreemption     RequeueReason = "PendingPreemption"
    36  )
    37  
    38  // ClusterQueue is an interface for a cluster queue to store workloads waiting
    39  // to be scheduled.
    40  type ClusterQueue interface {
    41  	// Update updates the properties of this ClusterQueue.
    42  	Update(*kueue.ClusterQueue) error
    43  	// Cohort returns the Cohort of this ClusterQueue.
    44  	Cohort() string
    45  
    46  	// AddFromLocalQueue pushes all workloads belonging to this queue to
    47  	// the ClusterQueue. If at least one workload is added, returns true,
    48  	// otherwise returns false.
    49  	AddFromLocalQueue(*LocalQueue) bool
    50  	// DeleteFromLocalQueue removes all workloads belonging to this queue from
    51  	// the ClusterQueue.
    52  	DeleteFromLocalQueue(*LocalQueue)
    53  
    54  	// PushOrUpdate pushes the workload to ClusterQueue.
    55  	// If the workload is already present, updates with the new one.
    56  	PushOrUpdate(*workload.Info)
    57  	// Delete removes the workload from ClusterQueue.
    58  	Delete(*kueue.Workload)
    59  	// Pop removes the head of the queue and returns it. It returns nil if the
    60  	// queue is empty.
    61  	Pop() *workload.Info
    62  
    63  	// RequeueIfNotPresent inserts a workload that was not
    64  	// admitted back into the ClusterQueue. If the boolean is true,
    65  	// the workloads should be put back in the queue immediately,
    66  	// because we couldn't determine if the workload was admissible
    67  	// in the last cycle. If the boolean is false, the implementation might
    68  	// choose to keep it in temporary placeholder stage where it doesn't
    69  	// compete with other workloads, until cluster events free up quota.
    70  	// The workload should not be reinserted if it's already in the ClusterQueue.
    71  	// Returns true if the workload was inserted.
    72  	RequeueIfNotPresent(*workload.Info, RequeueReason) bool
    73  	// QueueInadmissibleWorkloads moves all workloads put in temporary placeholder stage
    74  	// to the ClusterQueue. If at least one workload is moved,
    75  	// returns true, otherwise returns false.
    76  	QueueInadmissibleWorkloads(ctx context.Context, client client.Client) bool
    77  
    78  	// Pending returns the total number of pending workloads.
    79  	Pending() int
    80  
    81  	// PendingActive returns the number of active pending workloads,
    82  	// workloads that are in the admission queue.
    83  	PendingActive() int
    84  	// PendingInadmissible returns the number of inadmissible pending workloads,
    85  	// workloads that were already tried and are waiting for cluster conditions
    86  	// to change to potentially become admissible.
    87  	PendingInadmissible() int
    88  
    89  	// Dump produces a dump of the current workloads in the heap of
    90  	// this ClusterQueue. It returns false if the queue is empty,
    91  	// otherwise returns true.
    92  	Dump() ([]string, bool)
    93  	DumpInadmissible() ([]string, bool)
    94  	// Snapshot returns a copy of the current workloads in the heap of
    95  	// this ClusterQueue.
    96  	Snapshot() []*workload.Info
    97  	// Info returns workload.Info for the workload key.
    98  	// Users of this method should not modify the returned object.
    99  	Info(string) *workload.Info
   100  
   101  	// Returns true if the queue is active
   102  	Active() bool
   103  }
   104  
   105  var registry = map[kueue.QueueingStrategy]func(cq *kueue.ClusterQueue, wo workload.Ordering) (ClusterQueue, error){
   106  	kueue.StrictFIFO:     newClusterQueueStrictFIFO,
   107  	kueue.BestEffortFIFO: newClusterQueueBestEffortFIFO,
   108  }
   109  
   110  func newClusterQueue(cq *kueue.ClusterQueue, wo workload.Ordering) (ClusterQueue, error) {
   111  	strategy := cq.Spec.QueueingStrategy
   112  	f, exist := registry[strategy]
   113  	if !exist {
   114  		return nil, fmt.Errorf("invalid QueueingStrategy %q", cq.Spec.QueueingStrategy)
   115  	}
   116  	return f(cq, wo)
   117  }