include/llvm/XRay/Trace.h

   1 //===- Trace.h - XRay Trace Abstraction -----------------------------------===//
   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 // Defines the XRay Trace class representing records in an XRay trace file.
  11 //
  12 //===----------------------------------------------------------------------===//
  13 #ifndef LLVM_XRAY_TRACE_H
  14 #define LLVM_XRAY_TRACE_H
  15
  16 #include <cstdint>
  17 #include <vector>
  18
  19 #include "llvm/ADT/StringRef.h"
  20 #include "llvm/Support/DataExtractor.h"
  21 #include "llvm/Support/Error.h"
  22 #include "llvm/XRay/XRayRecord.h"
  23
  24 namespace llvm {
  25 namespace xray {
  26
  27 /// A Trace object represents the records that have been loaded from XRay
  28 /// log files generated by instrumented binaries. We encapsulate the logic of
  29 /// reading the traces in factory functions that populate the Trace object
  30 /// appropriately.
  31 ///
  32 /// Trace objects provide an accessor to an XRayFileHeader which says more about
  33 /// details of the file from which the XRay trace was loaded from.
  34 ///
  35 /// Usage:
  36 ///
  37 ///   if (auto TraceOrErr = loadTraceFile("xray-log.something.xray")) {
  38 ///     auto& T = *TraceOrErr;
  39 ///     // T.getFileHeader() will provide information from the trace header.
  40 ///     for (const XRayRecord &R : T) {
  41 ///       // ... do something with R here.
  42 ///     }
  43 ///   } else {
  44 ///     // Handle the error here.
  45 ///   }
  46 ///
  47 class Trace {
  48   XRayFileHeader FileHeader;
  49   using RecordVector = std::vector<XRayRecord>;
  50   RecordVector Records;
  51
  52   typedef std::vector<XRayRecord>::const_iterator citerator;
  53
  54   friend Expected<Trace> loadTrace(const DataExtractor &, bool);
  55
  56 public:
  57   using size_type = RecordVector::size_type;
  58   using value_type = RecordVector::value_type;
  59   using const_iterator = RecordVector::const_iterator;
  60
  61   /// Provides access to the loaded XRay trace file header.
  62   const XRayFileHeader &getFileHeader() const { return FileHeader; }
  63
  64   const_iterator begin() const { return Records.begin(); }
  65   const_iterator end() const { return Records.end(); }
  66   bool empty() const { return Records.empty(); }
  67   size_type size() const { return Records.size(); }
  68 };
  69
  70 /// This function will attempt to load XRay trace records from the provided
  71 /// |Filename|.
  72 Expected<Trace> loadTraceFile(StringRef Filename, bool Sort = false);
  73
  74 /// This function will attempt to load XRay trace records from the provided
  75 /// DataExtractor.
  76 Expected<Trace> loadTrace(const DataExtractor &Extractor, bool Sort = false);
  77
  78 } // namespace xray
  79 } // namespace llvm
  80
  81 #endif // LLVM_XRAY_TRACE_H