clang  8.0.0svn
Execution.h
Go to the documentation of this file.
1 //===--- Execution.h - Executing clang frontend actions -*- C++ ---------*-===//
2 //
3 // The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 //
10 // This file defines framework for executing clang frontend actions.
11 //
12 // The framework can be extended to support different execution plans including
13 // standalone execution on the given TUs or parallel execution on all TUs in
14 // the codebase.
15 //
16 // In order to enable multiprocessing execution, tool actions are expected to
17 // output result into the ToolResults provided by the executor. The
18 // `ToolResults` is an interface that abstracts how results are stored e.g.
19 // in-memory for standalone execution or on-disk for large-scale execution.
20 //
21 // New executors can be registered as ToolExecutorPlugins via the
22 // `ToolExecutorPluginRegistry`. CLI tools can use
23 // `createExecutorFromCommandLineArgs` to create a specific registered executor
24 // according to the command-line arguments.
25 //
26 //===----------------------------------------------------------------------===//
27 
28 #ifndef LLVM_CLANG_TOOLING_EXECUTION_H
29 #define LLVM_CLANG_TOOLING_EXECUTION_H
30 
32 #include "clang/Tooling/Tooling.h"
33 #include "llvm/Support/Error.h"
34 #include "llvm/Support/Registry.h"
35 #include "llvm/Support/StringSaver.h"
36 
37 namespace clang {
38 namespace tooling {
39 
40 extern llvm::cl::opt<std::string> ExecutorName;
41 
42 /// An abstraction for the result of a tool execution. For example, the
43 /// underlying result can be in-memory or on-disk.
44 ///
45 /// Results should be string key-value pairs. For example, a refactoring tool
46 /// can use source location as key and a replacement in YAML format as value.
47 class ToolResults {
48 public:
49  virtual ~ToolResults() = default;
50  virtual void addResult(StringRef Key, StringRef Value) = 0;
51  virtual std::vector<std::pair<llvm::StringRef, llvm::StringRef>>
52  AllKVResults() = 0;
53  virtual void forEachResult(
54  llvm::function_ref<void(StringRef Key, StringRef Value)> Callback) = 0;
55 };
56 
57 /// Stores the key-value results in memory. It maintains the lifetime of
58 /// the result. Clang tools using this class are expected to generate a small
59 /// set of different results, or a large set of duplicated results.
61 public:
62  InMemoryToolResults() : Strings(Arena) {}
63  void addResult(StringRef Key, StringRef Value) override;
64  std::vector<std::pair<llvm::StringRef, llvm::StringRef>>
65  AllKVResults() override;
66  void forEachResult(llvm::function_ref<void(StringRef Key, StringRef Value)>
67  Callback) override;
68 
69 private:
70  llvm::BumpPtrAllocator Arena;
71  llvm::UniqueStringSaver Strings;
72 
73  std::vector<std::pair<llvm::StringRef, llvm::StringRef>> KVResults;
74 };
75 
76 /// The context of an execution, including the information about
77 /// compilation and results.
79 public:
80  virtual ~ExecutionContext() {}
81 
82  /// Initializes a context. This does not take ownership of `Results`.
83  explicit ExecutionContext(ToolResults *Results) : Results(Results) {}
84 
85  /// Adds a KV pair to the result container of this execution.
86  void reportResult(StringRef Key, StringRef Value);
87 
88  // Returns the source control system's revision number if applicable.
89  // Otherwise returns an empty string.
90  virtual std::string getRevision() { return ""; }
91 
92  // Returns the corpus being analyzed, e.g. "llvm" for the LLVM codebase, if
93  // applicable.
94  virtual std::string getCorpus() { return ""; }
95 
96  // Returns the currently processed compilation unit if available.
97  virtual std::string getCurrentCompilationUnit() { return ""; }
98 
99 private:
100  ToolResults *Results;
101 };
102 
103 /// Interface for executing clang frontend actions.
104 ///
105 /// This can be extended to support running tool actions in different
106 /// execution mode, e.g. on a specific set of TUs or many TUs in parallel.
107 ///
108 /// New executors can be registered as ToolExecutorPlugins via the
109 /// `ToolExecutorPluginRegistry`. CLI tools can use
110 /// `createExecutorFromCommandLineArgs` to create a specific registered
111 /// executor according to the command-line arguments.
113 public:
114  virtual ~ToolExecutor() {}
115 
116  /// Returns the name of a specific executor.
117  virtual StringRef getExecutorName() const = 0;
118 
119  /// Should return true iff executor runs all actions in a single process.
120  /// Clients can use this signal to find out if they can collect results
121  /// in-memory (e.g. to avoid serialization costs of using ToolResults).
122  /// The single-process executors can still run multiple threads, but all
123  /// executions are guaranteed to share the same memory.
124  virtual bool isSingleProcess() const = 0;
125 
126  /// Executes each action with a corresponding arguments adjuster.
127  virtual llvm::Error
128  execute(llvm::ArrayRef<
129  std::pair<std::unique_ptr<FrontendActionFactory>, ArgumentsAdjuster>>
130  Actions) = 0;
131 
132  /// Convenient functions for the above `execute`.
133  llvm::Error execute(std::unique_ptr<FrontendActionFactory> Action);
134  /// Executes an action with an argument adjuster.
135  llvm::Error execute(std::unique_ptr<FrontendActionFactory> Action,
136  ArgumentsAdjuster Adjuster);
137 
138  /// Returns a reference to the execution context.
139  ///
140  /// This should be passed to tool callbacks, and tool callbacks should report
141  /// results via the returned context.
142  virtual ExecutionContext *getExecutionContext() = 0;
143 
144  /// Returns a reference to the result container.
145  ///
146  /// NOTE: This should only be used after the execution finishes. Tool
147  /// callbacks should report results via `ExecutionContext` instead.
148  virtual ToolResults *getToolResults() = 0;
149 
150  /// Map a virtual file to be used while running the tool.
151  ///
152  /// \param FilePath The path at which the content will be mapped.
153  /// \param Content A buffer of the file's content.
154  virtual void mapVirtualFile(StringRef FilePath, StringRef Content) = 0;
155 };
156 
157 /// Interface for factories that create specific executors. This is also
158 /// used as a plugin to be registered into ToolExecutorPluginRegistry.
160 public:
161  virtual ~ToolExecutorPlugin() {}
162 
163  /// Create an `ToolExecutor`.
164  ///
165  /// `OptionsParser` can be consumed (e.g. moved) if the creation succeeds.
167  create(CommonOptionsParser &OptionsParser) = 0;
168 };
169 
170 /// This creates a ToolExecutor that is in the global registry based on
171 /// commandline arguments.
172 ///
173 /// This picks the right executor based on the `--executor` option. This parses
174 /// the commandline arguments with `CommonOptionsParser`, so caller does not
175 /// need to parse again.
176 ///
177 /// By default, this creates a `StandaloneToolExecutor` ("standalone") if
178 /// `--executor` is not provided.
180 createExecutorFromCommandLineArgs(int &argc, const char **argv,
181  llvm::cl::OptionCategory &Category,
182  const char *Overview = nullptr);
183 
184 namespace internal {
186 createExecutorFromCommandLineArgsImpl(int &argc, const char **argv,
187  llvm::cl::OptionCategory &Category,
188  const char *Overview = nullptr);
189 } // end namespace internal
190 
191 } // end namespace tooling
192 } // end namespace clang
193 
194 #endif // LLVM_CLANG_TOOLING_EXECUTION_H
virtual std::string getRevision()
Definition: Execution.h:90
llvm::Expected< std::unique_ptr< ToolExecutor > > createExecutorFromCommandLineArgsImpl(int &argc, const char **argv, llvm::cl::OptionCategory &Category, const char *Overview=nullptr)
Definition: Execution.cpp:59
ExecutionContext(ToolResults *Results)
Initializes a context. This does not take ownership of Results.
Definition: Execution.h:83
The context of an execution, including the information about compilation and results.
Definition: Execution.h:78
llvm::cl::opt< std::string > ExecutorName
int Category
Definition: Format.cpp:1632
virtual ~ToolResults()=default
virtual void addResult(StringRef Key, StringRef Value)=0
Interface for executing clang frontend actions.
Definition: Execution.h:112
std::function< CommandLineArguments(const CommandLineArguments &, StringRef Filename)> ArgumentsAdjuster
A prototype of a command line adjuster.
Stores the key-value results in memory.
Definition: Execution.h:60
virtual std::string getCurrentCompilationUnit()
Definition: Execution.h:97
virtual void forEachResult(llvm::function_ref< void(StringRef Key, StringRef Value)> Callback)=0
virtual std::vector< std::pair< llvm::StringRef, llvm::StringRef > > AllKVResults()=0
A parser for options common to all command-line Clang tools.
Dataflow Directional Tag Classes.
An abstraction for the result of a tool execution.
Definition: Execution.h:47
std::unique_ptr< DiagnosticConsumer > create(StringRef OutputFile, DiagnosticOptions *Diags, bool MergeChildRecords=false)
Returns a DiagnosticConsumer that serializes diagnostics to a bitcode file.
llvm::Expected< std::unique_ptr< ToolExecutor > > createExecutorFromCommandLineArgs(int &argc, const char **argv, llvm::cl::OptionCategory &Category, const char *Overview=nullptr)
This creates a ToolExecutor that is in the global registry based on commandline arguments.
Definition: Execution.cpp:91
Interface for factories that create specific executors.
Definition: Execution.h:159
virtual std::string getCorpus()
Definition: Execution.h:94