DebugUtils.h

Go to the documentation of this file.

#ifndef LARCOREALG_COREUTILS_DEBUGUTILS_H
#define LARCOREALG_COREUTILS_DEBUGUTILS_H

// LArSoft includes
#include "larcorealg/CoreUtils/MetaUtils.h"

// framework and support libraries
#include "cetlib_except/demangle.h"

// C/C++ standard libraries
#include <bitset>
#include <cstddef> // std::ptrdiff_t
#include <cstdlib> // std::free()
#include <ostream>
#include <string>
#include <typeinfo>
#include <utility> // std::pair<>
#include <utility> // std::forward()
#include <vector>

// non-standard libraries
#include <execinfo.h> // backtrace()...
// #include <experimental/filesystem> // std::experimental::filesystem::path

namespace lar::debug {

  template <typename T>
  inline std::string demangle(T const* = nullptr);

  //----------------------------------------------------------------------------
  struct CallInfo_t {
  private:
    using range_t = std::pair<size_t, size_t>;

  public:
    CallInfo_t(std::string const& s) { ParseString(s); }
    CallInfo_t(const char* s) { ParseString(std::string(s)); }

    operator bool() const { return !libraryName.empty() || !mangledFunctionName.empty(); }
    bool operator!() const { return libraryName.empty() && mangledFunctionName.empty(); }

    bool ParseString(std::string const& s);

    std::string const& function() const
    {
      return functionName.empty() ? mangledFunctionName : functionName;
    }

    std::string shortLibrary() const
    {
      size_t sep = libraryName.rfind('/');
      return (sep == std::string::npos) ? libraryName : libraryName.substr(sep + 1);
      //  return std::experimental::filesystem::path(libraryName).filename();
    }

    std::string original;            
    std::string libraryName;         
    std::string functionName;        
    std::string mangledFunctionName; 
    void* address = nullptr;         
    std::ptrdiff_t offset = 0;       

  private:
    static bool emptyRange(range_t const& r) { return r.first >= r.second; }

    static std::string extract(std::string const& s, range_t const& r)
    {
      return emptyRange(r) ? "" : s.substr(r.first, r.second - r.first);
    }

    void demangleFunction() { functionName = cet::demangle_symbol(mangledFunctionName); }

    void setAll(std::string const& s,
                range_t addressStr,
                range_t libraryStr,
                range_t functionStr,
                range_t offsetStr);

  }; // CallInfo_t

  //----------------------------------------------------------------------------
  class CallInfoPrinter {
  public:
    struct opt {
      enum option_t {
        address,      
        demangled,    
        library,      
        shortLibrary, 
        offset,       
        NOptions      
      };              // option_t

      std::bitset<NOptions> options; 

      opt& set(option_t o, bool set = true)
      {
        options.set(o, set);
        return *this;
      }

      bool has(option_t o) const { return options.test(o); }

    }; // opt

    opt options; 

    CallInfoPrinter() { setDefaultOptions(); }

    CallInfoPrinter(opt opts) : options(opts) {}

    void setOptions(opt opts) { options = opts; }

    template <typename Stream>
    void print(Stream&& out, CallInfo_t const& info) const;

    template <typename Stream>
    void operator()(Stream&& out, CallInfo_t const& info) const
    {
      print(std::forward<Stream>(out), info);
    }

    void setDefaultOptions() { options = defaultOptions(); }

    static opt defaultOptions()
    {
      opt options;
      options.set(opt::demangled);
      options.set(opt::library);
      options.set(opt::shortLibrary);
      options.set(opt::address);
      return options;
    }

  }; // CallInfoPrinter

  //----------------------------------------------------------------------------
  template <typename Stream>
  inline Stream& operator<<(Stream&& out, CallInfo_t const& info);

  //----------------------------------------------------------------------------
  struct BacktracePrintOptions {

    unsigned int maxLines = 5;  
    unsigned int skipLines = 1; 
    bool countOthers = true;    
    std::string indent;         
    std::string firstIndent;    

    CallInfoPrinter::opt callInfoOptions = CallInfoPrinter::defaultOptions();

    void setUniformIndent(std::string uniformIndent) { indent = firstIndent = uniformIndent; }

  }; // struct BacktracePrintOptions

  template <typename Stream>
  void printBacktrace(Stream&& out, BacktracePrintOptions options);

  template <typename Stream>
  void printBacktrace(Stream&& out)
  {
    printBacktrace(std::forward<Stream>(out), BacktracePrintOptions());
  }

  template <typename Stream>
  void printBacktrace(Stream&& out,
                      unsigned int maxLines,
                      std::string indent = "  ",
                      CallInfoPrinter::opt const* callInfoOptions = nullptr);

  //----------------------------------------------------------------------------
  template <typename T, bool Enable /* = true */>
  struct static_assert_on;

  //----------------------------------------------------------------------------

} // namespace lar::debug

//------------------------------------------------------------------------------
//--- template implementation
//------------------------------------------------------------------------------
namespace lar::debug {

  //----------------------------------------------------------------------------
  template <typename T>
  inline std::string demangle(T const* /* = nullptr */)
  {
    return cet::demangle_symbol(typeid(std::decay_t<T>).name());
  }

  //----------------------------------------------------------------------------
  template <typename Stream>
  void CallInfoPrinter::print(Stream&& out, CallInfo_t const& info) const
  {
    if (!info) {
      out << info.original << " (?)";
      return;
    }

    if (info.mangledFunctionName.empty()) {
      if (options.has(opt::library)) {
        out << "in " << (options.has(opt::shortLibrary) ? info.shortLibrary() : info.libraryName);
      }
      else
        out << "unknown";
    }
    else {
      //  auto flags = out.flags(); // not available in message facility streams
      out << info.function();
      auto offset = info.offset;
      if (offset && options.has(opt::offset)) {
        out << " [";
        if (offset > 0)
          out << '+';
        else {
          out << '-';
          offset = -offset;
        }
        out << std::showbase << std::hex << offset << "]";
      } // if has offset
      //  out << std::ios::setiosflags(flags);
      if (!info.libraryName.empty() && options.has(opt::library)) {
        out << " in " << (options.has(opt::shortLibrary) ? info.shortLibrary() : info.libraryName);
      }
    }
    if (info.address && options.has(opt::address)) out << " at " << ((void*)info.address);
    out << std::flush;
  } // CallInfoPrinter::print()

  //----------------------------------------------------------------------------
  template <typename Stream>
  inline Stream& operator<<(Stream&& out, CallInfo_t const& info)
  {
    CallInfoPrinter print;
    print(std::forward<Stream>(out), info);
    return out;
  }

  //----------------------------------------------------------------------------
  template <typename Stream>
  void printBacktrace(Stream&& out, BacktracePrintOptions options)
  {
    unsigned int nSkip = std::max(options.skipLines, 0U);
    std::vector<void*> buffer(nSkip + std::max(options.maxLines, 200U), nullptr);

    unsigned int const nItems = (unsigned int)backtrace(buffer.data(), buffer.size());

    // convert the calls in the buffer into a vector of strings
    char** symbols = backtrace_symbols(buffer.data(), buffer.size());
    if (!symbols) {
      out << options.firstIndent << "<failed to get the call stack>\n" << std::flush;
      return;
    }
    std::vector<CallInfo_t> callStack;
    for (size_t i = 0; i < buffer.size(); ++i)
      callStack.push_back((const char*)symbols[i]);
    std::free(symbols);

    size_t lastItem = nSkip + options.maxLines;
    if (lastItem > nItems) lastItem = nItems;
    if (lastItem >= buffer.size()) --lastItem;

    CallInfoPrinter print(options.callInfoOptions);
    for (size_t i = nSkip; i < lastItem; ++i) {
      out << (i == 0 ? options.firstIndent : options.indent);
      print(std::forward<Stream>(out), callStack[i]);
      out << "\n";
    }
    if ((lastItem < nItems) && options.countOthers) {
      out << options.indent << " ... and other " << (nItems - lastItem);
      if (nItems == buffer.size()) out << " (or more)";
      out << " levels\n";
    }
    out << std::flush;

  } // printBacktrace()

  //----------------------------------------------------------------------------
  template <typename Stream>
  void printBacktrace(Stream&& out,
                      unsigned int maxLines,
                      std::string indent /* = "  " */,
                      CallInfoPrinter::opt const* callInfoOptions /* = nullptr */
  )
  {
    BacktracePrintOptions options;
    options.maxLines = maxLines;
    options.indent = options.firstIndent = indent;
    if (callInfoOptions) options.callInfoOptions = *callInfoOptions;
    printBacktrace(std::forward<Stream>(out), options);
  }

  //----------------------------------------------------------------------------
  namespace details {

    template <typename T>
    struct THE_TYPE_IS {
      // if the assertion condition didn't depend on a template parameters,
      // the assertion failure error would *always* be triggered
      static_assert(::util::always_false_v<T>,
                    "static_assert_on<T>: check the error message (\"THE_TYPE_IS<>\") for "
                    "expansion of type `T`.");
    }; // THE_TYPE_IS<>

  } // namespace details

  template <typename T, bool Enable = true>
  struct static_assert_on {
    static_assert_on() = default;
    static_assert_on(T) {}
    details::THE_TYPE_IS<T> _;
  }; // static_assert_on<>

  template <typename T>
  struct static_assert_on<T, false> {};

  //----------------------------------------------------------------------------

} // namespace lar::debug

#endif // LARCOREALG_COREUTILS_DEBUGUTILS_H