1 /* Copyright 2017 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 #ifndef TENSORFLOW_COMPILER_XLA_DEBUG_OPTIONS_FLAGS_H_
17 #define TENSORFLOW_COMPILER_XLA_DEBUG_OPTIONS_FLAGS_H_
18
19 #include <vector>
20
21 #include "absl/strings/string_view.h"
22 #include "tensorflow/compiler/xla/xla.pb.h"
23 #include "tensorflow/core/platform/logging.h"
24 #include "tensorflow/core/util/command_line_flags.h"
25
26 namespace xla {
27
28 // Appends flag definitions for debug options to flag_list.
29 void AppendDebugOptionsFlags(std::vector<tensorflow::Flag>* flag_list);
30
31 // Fetches a DebugOptions proto message from flags provided to the program.
32 // Flags must be registered with the flags parser using AppendDebugOptionsFlags
33 // first.
34 DebugOptions GetDebugOptionsFromFlags();
35
36 // Gets a DebugOptions proto that reflects the defaults as if no flags were set.
37 DebugOptions DefaultDebugOptionsIgnoringFlags();
38
39 // Consumes a unit of "compiler fuel" for the given pass, and returns false if
40 // we're out of fuel for that pass.
41 //
42 // Compiler fuel is a debugging tool useful for bisecting compiler passes. Each
43 // time a pass "does something", it consumes a unit of fuel, and once it's out
44 // of fuel, it stops doing any transformations. This way if you suspect a pass
45 // has a bug, you can bisect the amount of fuel it gets and find exactly which
46 // change causes the problem.
47 //
48 // The very first time a pass runs out of fuel, `just_ran_out` is set to true.
49 // This lets you take action (e.g. log a message). But see also the convenience
50 // overload below.
51 //
52 // By default all passes have infinite fuel. You can restrict how much fuel a
53 // pass has by specifying XLA_FLAGS=--xla_fuel=PASS1=NUM1,PASS2=NUM2,...
54 //
55 // If a user specifies --xla_fuel=PASS=NUM but ConsumeFuel(PASS) is not called
56 // before the program exits, we'll print a warning.
57 //
58 // We recommend as a convention you use a pass's name for the `pass` argument,
59 // but any value is accepted.
60 bool ConsumeFuel(absl::string_view pass, bool* just_ran_out = nullptr);
61
62 // Overload of ConsumeFuel that lets you pass in a functor which generates a log
63 // message when we first run out of fuel for a pass. This is useful because
64 // you're usually interested in what *would have* happened right when we ran out
65 // of fuel.
66 //
67 // Example usage:
68 //
69 // if (ConsumeFuel("pass-name", [&] { return "Not fooing bar."; })) {
70 // return;
71 // }
72 //
73 template <typename MsgGenerator>
ConsumeFuel(absl::string_view pass,const MsgGenerator & ran_out_of_fuel_msg)74 bool ConsumeFuel(absl::string_view pass,
75 const MsgGenerator& ran_out_of_fuel_msg) {
76 bool just_ran_out = false;
77 bool ret = ConsumeFuel(pass, &just_ran_out);
78 if (just_ran_out) {
79 LOG(ERROR) << "Out of fuel for \"" << pass
80 << "\": " << ran_out_of_fuel_msg();
81 }
82 return ret;
83 }
84
85 // By default compiler fuel is global; if you run two compiler threads, they
86 // will consume from the same fuel pool.
87 //
88 // Calling this function changes the behavior of fuel for the current thread:
89 // From this point onward, it will use a private fuel pool. The thread-local
90 // fuel pool is initialized to the values the global fuel pool had at process
91 // startup.
92 //
93 // You may call this function twice in the same thread to reset its fuel pool
94 // back to the initial state.
95 void ResetThreadLocalFuel();
96
97 } // namespace xla
98
99 #endif // TENSORFLOW_COMPILER_XLA_DEBUG_OPTIONS_FLAGS_H_
100