Analysis/FlowSensitive/Logger.h

0001 //===-- Logger.h ------------------------------------------------*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008
0009 #ifndef LLVM_CLANG_ANALYSIS_FLOWSENSITIVE_LOGGER_H
0010 #define LLVM_CLANG_ANALYSIS_FLOWSENSITIVE_LOGGER_H
0011
0012 #include "clang/Analysis/CFG.h"
0013 #include "llvm/Support/raw_ostream.h"
0014 #include <memory>
0015
0016 namespace clang::dataflow {
0017 // Forward declarations so we can use Logger anywhere in the framework.
0018 class AdornedCFG;
0019 class TypeErasedDataflowAnalysis;
0020 struct TypeErasedDataflowAnalysisState;
0021
0022 /// A logger is notified as the analysis progresses.
0023 /// It can produce a report of the analysis's findings and how it came to them.
0024 ///
0025 /// The framework reports key structural events (e.g. traversal of blocks).
0026 /// The specific analysis can add extra details to be presented in context.
0027 class Logger {
0028 public:
0029   /// Returns a dummy logger that does nothing.
0030   static Logger &null();
0031   /// A logger that simply writes messages to the specified ostream in real
0032   /// time.
0033   static std::unique_ptr<Logger> textual(llvm::raw_ostream &);
0034   /// A logger that builds an HTML UI to inspect the analysis results.
0035   /// Each function's analysis is written to a stream obtained from the factory.
0036   static std::unique_ptr<Logger>
0037       html(std::function<std::unique_ptr<llvm::raw_ostream>()>);
0038
0039   virtual ~Logger() = default;
0040
0041   /// Called by the framework as we start analyzing a new function or statement.
0042   /// Forms a pair with endAnalysis().
0043   virtual void beginAnalysis(const AdornedCFG &, TypeErasedDataflowAnalysis &) {
0044   }
0045   virtual void endAnalysis() {}
0046
0047   // At any time during the analysis, we're computing the state for some target
0048   // program point.
0049
0050   /// Called when we start (re-)processing a block in the CFG.
0051   /// The target program point is the entry to the specified block.
0052   /// Calls to log() describe transferBranch(), join() etc.
0053   /// `PostVisit` specifies whether we're processing the block for the
0054   /// post-visit callback.
0055   virtual void enterBlock(const CFGBlock &, bool PostVisit) {}
0056   /// Called when we start processing an element in the current CFG block.
0057   /// The target program point is after the specified element.
0058   /// Calls to log() describe the transfer() function.
0059   virtual void enterElement(const CFGElement &) {}
0060
0061   /// Records the analysis state computed for the current program point.
0062   virtual void recordState(TypeErasedDataflowAnalysisState &) {}
0063   /// Records that the analysis state for the current block is now final.
0064   virtual void blockConverged() {}
0065
0066   /// Called by the framework or user code to report some event.
0067   /// The event is associated with the current context (program point).
0068   /// The Emit function produces the log message. It may or may not be called,
0069   /// depending on if the logger is interested; it should have no side effects.
0070   void log(llvm::function_ref<void(llvm::raw_ostream &)> Emit) {
0071     if (!ShouldLogText)
0072       return;
0073     std::string S;
0074     llvm::raw_string_ostream OS(S);
0075     Emit(OS);
0076     logText(S);
0077   }
0078
0079 protected:
0080   /// ShouldLogText should be false for trivial loggers that ignore logText().
0081   /// This allows log() to skip evaluating its Emit function.
0082   Logger(bool ShouldLogText = true) : ShouldLogText(ShouldLogText) {}
0083
0084 private:
0085   bool ShouldLogText;
0086   virtual void logText(llvm::StringRef) {}
0087 };
0088
0089 } // namespace clang::dataflow
0090
0091 #endif