include/llvm/XRay/Trace.h

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