001 /**
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019 package org.apache.hadoop.yarn.api.records;
020
021 import org.apache.hadoop.classification.InterfaceAudience.Public;
022 import org.apache.hadoop.classification.InterfaceStability.Evolving;
023
024 /**
025 * Enumeration of various types of dependencies among multiple
026 * {@link ReservationRequests} within one {@link ReservationDefinition} (from
027 * least constraining to most constraining).
028 */
029 @Public
030 @Evolving
031 public enum ReservationRequestInterpreter {
032 /**
033 * Requires that exactly ONE among the {@link ReservationRequest} submitted as
034 * of a {@link ReservationDefinition} is satisfied to satisfy the overall
035 * {@link ReservationDefinition}.
036 *
037 * WHEN TO USE THIS: This is useful when the user have multiple equivalent
038 * ways to run an application, and wants to expose to the ReservationAgent
039 * such flexibility. For example an application could use one <32GB,16core>
040 * container for 10min, or 16 <2GB,1core> containers for 15min, the
041 * ReservationAgent will decide which one of the two it is best for the system
042 * to place.
043 *
044 */
045 R_ANY,
046
047 /**
048 * Requires that ALL of the {@link ReservationRequest} submitted as part of a
049 * {@link ReservationDefinition} are satisfied for the overall
050 * {@link ReservationDefinition} to be satisfied. No constraints are imposed
051 * on the temporal ordering of the allocation used to satisfy the
052 * ResourceRequeusts.
053 *
054 * WHEN TO USE THIS: This is useful to capture a scenario in which the user
055 * cares for multiple ReservationDefinition to be all accepted, or none. For
056 * example, a user might want a reservation R1: with 10 x <8GB,4core> for
057 * 10min, and a reservation R2: with 2 <1GB,1core> for 1h, and only if both
058 * are satisfied the workflow run in this reservation succeeds. The key
059 * differentiator from ALL and ORDER, ORDER_NO_GAP, is that ALL imposes no
060 * restrictions on the relative allocations used to place R1 and R2 above.
061 *
062 */
063 R_ALL,
064
065 /**
066 * Requires that ALL of the {@link ReservationRequest} submitted as part of a
067 * {@link ReservationDefinition} are satisfied for the overall
068 * {@link ReservationDefinition} to be satisfied. Moreover, it imposes a
069 * strict temporal ordering on the allocation used to satisfy the
070 * {@link ReservationRequest}s. The allocations satisfying the
071 * {@link ReservationRequest} in position k must strictly precede the
072 * allocations for the {@link ReservationRequest} at position k+1. No
073 * constraints are imposed on temporal gaps between subsequent allocations
074 * (the last instant of the previous allocation can be an arbitrary long
075 * period of time before the first instant of the subsequent allocation).
076 *
077 * WHEN TO USE THIS: Like ALL this requires all ReservationDefinitions to be
078 * placed, but it also imposes a time ordering on the allocations used. This
079 * is important if the ReservationDefinition(s) are used to describe a
080 * workflow with inherent inter-stage dependencies. For example, a first job
081 * runs in a ReservaitonDefinition R1 (10 x <1GB,1core> for 20min), and its
082 * output is consumed by a second job described by a ReservationDefinition R2
083 * (5 x <1GB,1core>) for 50min). R2 allocation cannot overlap R1, as R2 models
084 * a job depending on the output of the job modeled by R1.
085 */
086 R_ORDER,
087
088 /**
089 * Requires that ALL of the {@link ReservationRequest} submitted as part of a
090 * {@link ReservationDefinition} are satisfied for the overall
091 * {@link ReservationDefinition} to be satisfied. Moreover, it imposes a
092 * strict temporal ordering on the allocation used to satisfy the
093 * {@link ReservationRequest}s. It imposes a strict temporal ordering on the
094 * allocation used to satisfy the {@link ReservationRequest}s. The allocations
095 * satisfying the {@link ReservationRequest} in position k must strictly
096 * precede the allocations for the {@link ReservationRequest} at position k+1.
097 * Moreover it imposes a "zero-size gap" between subsequent allocations, i.e.,
098 * the last instant in time of the allocations associated with the
099 * {@link ReservationRequest} at position k must be exactly preceding the
100 * first instant in time of the {@link ReservationRequest} at position k+1.
101 * Time ranges are interpreted as [a,b) inclusive left, exclusive right.
102 *
103 * WHEN TO USE THIS: This is a stricter version of R_ORDER, which allows no
104 * gaps between the allocations that satisfy R1 and R2. The use of this is
105 * twofold: 1) prevent long gaps between subsequent stages that produce very
106 * large intermediate output (e.g., the output of R1 is too large to be kept
107 * around for long before the job running in R2 consumes it, and disposes of
108 * it), 2) if the job being modeled has a time-varying resource need, one can
109 * combine multiple ResourceDefinition each approximating a portion of the job
110 * execution (think of using multiple rectangular bounding boxes to described
111 * an arbitrarily shaped area). By asking for no-gaps we guarantee
112 * "continuity" of resources given to this job. This still allow for some
113 * flexibility, as the entire "train" of allocations can be moved rigidly back
114 * or forth within the start-deadline time range (if there is slack).
115 *
116 */
117 R_ORDER_NO_GAP
118
119 }