File D:\maven-qcr-plugin-testsunitaires\qcr4java\jenkins-master\target\site\qc\core\src\main\java\hudson\model\queue\QueueTaskDispatcher.java.html

1 /*
2 * The MIT License
3 *
4 * Copyright (c) 2010, InfraDNA, Inc.
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to deal
8 * in the Software without restriction, including without limitation the rights
9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 * copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
22 * THE SOFTWARE.
23 */
24
25 package hudson.model.queue;
26
27 import hudson.Extension;
28 import hudson.ExtensionList;
29 import hudson.ExtensionPoint;
30 import hudson.model.Queue.Item;
31 import hudson.slaves.Cloud;
32 import jenkins.model.Jenkins;
33 import hudson.model.Node;
34 import hudson.model.Queue;
35 import hudson.model.Queue.BuildableItem;
36 import hudson.model.Queue.Task;
37
38 /**
39 * Vetos the execution of a task on a node
40 *
41 * <p>
42 * To register your dispatcher implementations, put @{@link Extension} on your subtypes.
43 *
44 * @author Kohsuke Kawaguchi
45 * @since 1.360
46 */
47 public abstract class QueueTaskDispatcher implements ExtensionPoint {
48 /**
49 * Called whenever {@link Queue} is considering to execute the given task on a given node.
50 *
51 * <p>
52 * Implementations can return null to indicate that the assignment is fine, or it can return
53 * a non-null instance to block the execution of the task on the given node.
54 *
55 * <p>
56 * Queue doesn't remember/cache the response from dispatchers, and instead it'll keep asking.
57 * The upside of this is that it's very easy to block execution for a limited time period (
58 * as you just need to return null when it's ready to execute.) The downside of this is that
59 * the decision needs to be made quickly.
60 *
61 * <p>
62 * Vetos are additive. When multiple {@link QueueTaskDispatcher}s are in the system,
63 * the task won't run on the given node if any one of them returns a non-null value.
64 * (This relationship is also the same with built-in check logic.)
65 *
66 * @deprecated since 1.413
67 * Use {@link #canTake(Node, BuildableItem)}
68 */
69 public CauseOfBlockage canTake(Node node, Task task) {
70 return null;
71 }
72
73 /**
74 * Called when {@link Queue} is deciding where to execute the given task.
75 *
76 * <p>
77 * Implementations can return null to indicate that the assignment is fine, or it can return
78 * a non-null instance to block the execution of the task on the given node.
79 *
80 * <p>
81 * Queue doesn't remember/cache the response from dispatchers, and instead it'll keep asking.
82 * The upside of this is that it's very easy to block execution for a limited time period (
83 * as you just need to return null when it's ready to execute.) The downside of this is that
84 * the decision needs to be made quickly.
85 *
86 * <p>
87 * This method is primarily designed to fine-tune where the execution should take place. If the execution
88 * shouldn't commence anywhere at all, implementation should use {@link #canRun(Item)} instead so
89 * that Jenkins understands the difference between "this node isn't the right place for this work"
90 * vs "the time isn't right for this work to execute." This affects the provisioning behaviour
91 * with elastic Jenkins deployments.
92 *
93 * <p>
94 * Vetos are additive. When multiple {@link QueueTaskDispatcher}s are in the system,
95 * the task won't run on the given node if any one of them returns a non-null value.
96 * (This relationship is also the same with built-in check logic.)
97 *
98 * @since 1.413
99 */
100 public CauseOfBlockage canTake(Node node, BuildableItem item) {
101 return canTake(node,item.task); // backward compatible behaviour
102 }
103
104 /**
105 * Called whenever {@link Queue} is considering if {@link Queue.Item} is ready to execute immediately
106 * (which doesn't necessarily mean that it gets executed right away &mdash; it's still subject to
107 * executor availability), or if it should be considered blocked.
108 *
109 * <p>
110 * Compared to {@link #canTake(Node, BuildableItem)}, this version tells Jenkins that the task is
111 * simply not ready to execute, even if there's available executor. This is more efficient
112 * than {@link #canTake(Node, BuildableItem)}, and it sends the right signal to Jenkins so that
113 * it won't use {@link Cloud} to try to provision new executors.
114 *
115 * <p>
116 * Vetos are additive. When multiple {@link QueueTaskDispatcher}s are in the system,
117 * the task is considered blocked if any one of them returns a non-null value.
118 * (This relationship is also the same with built-in check logic.)
119 *
120 * <p>
121 * If a {@link QueueTaskDispatcher} returns non-null from this method, the task is placed into
122 * the 'blocked' state, and generally speaking it stays in this state for a few seconds before
123 * its state gets re-evaluated. If a {@link QueueTaskDispatcher} wants the blockage condition
124 * to be re-evaluated earlier, call {@link Queue#scheduleMaintenance()} to initiate that process.
125 *
126 * @return
127 * null to indicate that the item is ready to proceed to the buildable state as far as this
128 * {@link QueueTaskDispatcher} is concerned. Otherwise return an object that indicates why
129 * the build is blocked.
130 * @since 1.427
131 */
132 public CauseOfBlockage canRun(Queue.Item item) {
133 return null;
134 }
135
136 /**
137 * All registered {@link QueueTaskDispatcher}s.
138 */
139 public static ExtensionList<QueueTaskDispatcher> all() {
140 return Jenkins.getInstance().getExtensionList(QueueTaskDispatcher.class);
141 }
142 }