1 /* Copyright 2016 The TensorFlow Authors. All Rights Reserved. 2 3 Licensed under the Apache License, Version 2.0 (the "License"); 4 you may not use this file except in compliance with the License. 5 You may obtain a copy of the License at 6 7 http://www.apache.org/licenses/LICENSE-2.0 8 9 Unless required by applicable law or agreed to in writing, software 10 distributed under the License is distributed on an "AS IS" BASIS, 11 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 See the License for the specific language governing permissions and 13 limitations under the License. 14 ==============================================================================*/ 15 16 package org.tensorflow; 17 18 /** 19 * A builder for {@link Operation}s. 20 * 21 * <p>For example, the following uses the builder to create an operation that produces the constant 22 * "3" as its output: 23 * 24 * <pre>{@code 25 * // env is an ExecutionEnvironment, such as a Graph instance. 26 * try (Tensor c1 = Tensor.create(3.0f)) { 27 * env.opBuilder("Const", "MyConst") 28 * .setAttr("dtype", c1.dataType()) 29 * .setAttr("value", c1) 30 * .build(); 31 * } 32 * }</pre> 33 */ 34 public interface OperationBuilder { 35 36 /** 37 * Build the {@link Operation}. 38 * 39 * <p>The following action will also be performed depending on the current execution environment. 40 * 41 * <ul> 42 * <li>In eager mode, the result of the operation will be computed immediately. 43 * <li>In graph mode, the operation will be added as a node to the graph to be executed later, 44 * when running a {@link Session}. 45 * </ul> 46 * 47 * <p>The OperationBuilder is not usable after build() returns. 48 */ build()49 public Operation build(); 50 51 /** 52 * Add the output of another operation as the next input of the operation being built. 53 * 54 * @param input {@link Output} supposed to be the input of the operation being built. 55 * @return the OperationBuilder instance for chaining. 56 */ addInput(Output<?> input)57 public OperationBuilder addInput(Output<?> input); 58 59 /** 60 * Add the outputs of another operation as the next inputs of the operation being built. 61 * 62 * @param inputs list of {@link Output} supposed to be the inputs of the operation being built. 63 * @return the OperationBuilder instance for chaining. 64 */ addInputList(Output<?>[] inputs)65 public OperationBuilder addInputList(Output<?>[] inputs); 66 67 /** 68 * Ensure that the operation does not execute before the control operation does. 69 * 70 * <p>A control input is an Operation that must be executed before running the operation currently 71 * being built. 72 * 73 * <p>For example, an Assert operation may be added as a control input for this operation. The 74 * Assert now behaves as a pre-condition that will always verify itself before running the 75 * operation. 76 * 77 * @param control operation that must be executed before running this operation. 78 * @return the OperationBuilder instance for chaining. 79 */ addControlInput(Operation control)80 public OperationBuilder addControlInput(Operation control); 81 82 /** 83 * Set the device requested for computing the operation being built. 84 * 85 * @param device the requested device, as a string 86 * @return the OperationBuilder instance for chaining. 87 */ setDevice(String device)88 public OperationBuilder setDevice(String device); 89 90 /** 91 * Set the string values of an attribute of the operation being built. 92 * 93 * @param name attribute name 94 * @param value attribute values 95 * @return the OperationBuilder instance for chaining. 96 */ setAttr(String name, String[] value)97 public OperationBuilder setAttr(String name, String[] value); 98 99 /** 100 * Set the string value of an attribute of the operation being built. 101 * 102 * @param name attribute name 103 * @param value attribute value 104 * @return the OperationBuilder instance for chaining. 105 */ setAttr(String name, String value)106 public OperationBuilder setAttr(String name, String value); 107 108 /** 109 * Set the byte values of an attribute of the operation being built. 110 * 111 * @param name attribute name 112 * @param value attribute values 113 * @return the OperationBuilder instance for chaining. 114 */ setAttr(String name, byte[] value)115 public OperationBuilder setAttr(String name, byte[] value); 116 117 /** 118 * Set the long value of an attribute of the operation being built. 119 * 120 * @param name attribute name 121 * @param value attribute value 122 * @return the OperationBuilder instance for chaining. 123 */ setAttr(String name, long value)124 public OperationBuilder setAttr(String name, long value); 125 126 /** 127 * Set the long values of an attribute of the operation being built. 128 * 129 * @param name attribute name 130 * @param value attribute values 131 * @return the OperationBuilder instance for chaining. 132 */ setAttr(String name, long[] value)133 public OperationBuilder setAttr(String name, long[] value); 134 135 /** 136 * Set the float value of an attribute of the operation being built. 137 * 138 * @param name attribute name 139 * @param value attribute value 140 * @return the OperationBuilder instance for chaining. 141 */ setAttr(String name, float value)142 public OperationBuilder setAttr(String name, float value); 143 144 /** 145 * Set the float values of an attribute of the operation being built. 146 * 147 * @param name attribute name 148 * @param value attribute values 149 * @return the OperationBuilder instance for chaining. 150 */ setAttr(String name, float[] value)151 public OperationBuilder setAttr(String name, float[] value); 152 153 /** 154 * Set the boolean value of an attribute of the operation being built. 155 * 156 * @param name attribute name 157 * @param value attribute value 158 * @return the OperationBuilder instance for chaining. 159 */ setAttr(String name, boolean value)160 public OperationBuilder setAttr(String name, boolean value); 161 162 /** 163 * Set the boolean values of an attribute of the operation being built. 164 * 165 * @param name attribute name 166 * @param value attribute values 167 * @return the OperationBuilder instance for chaining. 168 */ setAttr(String name, boolean[] value)169 public OperationBuilder setAttr(String name, boolean[] value); 170 171 /** 172 * Set the type value of an attribute of the operation being built. 173 * 174 * @param name attribute name 175 * @param value attribute value 176 * @return the OperationBuilder instance for chaining. 177 */ setAttr(String name, DataType value)178 public OperationBuilder setAttr(String name, DataType value); 179 180 /** 181 * Set the type values of an attribute of the operation being built. 182 * 183 * @param name attribute name 184 * @param value attribute values 185 * @return the OperationBuilder instance for chaining. 186 */ setAttr(String name, DataType[] value)187 public OperationBuilder setAttr(String name, DataType[] value); 188 189 /** 190 * Set the tensor value of an attribute of the operation being built. 191 * 192 * @param name attribute name 193 * @param value attribute value 194 * @return the OperationBuilder instance for chaining. 195 */ setAttr(String name, Tensor<?> value)196 public OperationBuilder setAttr(String name, Tensor<?> value); 197 198 /** 199 * Set the tensor values of an attribute of the operation being built. 200 * 201 * @param name attribute name 202 * @param value attribute values 203 * @return the OperationBuilder instance for chaining. 204 */ setAttr(String name, Tensor<?>[] value)205 public OperationBuilder setAttr(String name, Tensor<?>[] value); 206 207 /** 208 * Set the shape value of an attribute of the operation being built. 209 * 210 * @param name attribute name 211 * @param value attribute value 212 * @return the OperationBuilder instance for chaining. 213 */ setAttr(String name, Shape value)214 public OperationBuilder setAttr(String name, Shape value); 215 216 /** 217 * Set the shape values of an attribute of the operation being built. 218 * 219 * @param name attribute name 220 * @param value attribute values 221 * @return the OperationBuilder instance for chaining. 222 */ setAttr(String name, Shape[] value)223 public OperationBuilder setAttr(String name, Shape[] value); 224 } 225