llvm/XRay/Trace.h

0001 //===- Trace.h - XRay Trace Abstraction -----------------------------------===//
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 // Defines the XRay Trace class representing records in an XRay trace file.
0010 //
0011 //===----------------------------------------------------------------------===//
0012 #ifndef LLVM_XRAY_TRACE_H
0013 #define LLVM_XRAY_TRACE_H
0014
0015 #include <cstdint>
0016 #include <vector>
0017
0018 #include "llvm/ADT/StringRef.h"
0019 #include "llvm/Support/DataExtractor.h"
0020 #include "llvm/Support/Error.h"
0021 #include "llvm/XRay/XRayRecord.h"
0022
0023 namespace llvm {
0024 namespace xray {
0025
0026 /// A Trace object represents the records that have been loaded from XRay
0027 /// log files generated by instrumented binaries. We encapsulate the logic of
0028 /// reading the traces in factory functions that populate the Trace object
0029 /// appropriately.
0030 ///
0031 /// Trace objects provide an accessor to an XRayFileHeader which says more about
0032 /// details of the file from which the XRay trace was loaded from.
0033 ///
0034 /// Usage:
0035 ///
0036 ///   if (auto TraceOrErr = loadTraceFile("xray-log.something.xray")) {
0037 ///     auto& T = *TraceOrErr;
0038 ///     // T.getFileHeader() will provide information from the trace header.
0039 ///     for (const XRayRecord &R : T) {
0040 ///       // ... do something with R here.
0041 ///     }
0042 ///   } else {
0043 ///     // Handle the error here.
0044 ///   }
0045 ///
0046 class Trace {
0047   XRayFileHeader FileHeader;
0048   using RecordVector = std::vector<XRayRecord>;
0049   RecordVector Records;
0050
0051   typedef std::vector<XRayRecord>::const_iterator citerator;
0052
0053   friend Expected<Trace> loadTrace(const DataExtractor &, bool);
0054
0055 public:
0056   using size_type = RecordVector::size_type;
0057   using value_type = RecordVector::value_type;
0058   using const_iterator = RecordVector::const_iterator;
0059
0060   /// Provides access to the loaded XRay trace file header.
0061   const XRayFileHeader &getFileHeader() const { return FileHeader; }
0062
0063   const_iterator begin() const { return Records.begin(); }
0064   const_iterator end() const { return Records.end(); }
0065   bool empty() const { return Records.empty(); }
0066   size_type size() const { return Records.size(); }
0067 };
0068
0069 /// This function will attempt to load XRay trace records from the provided
0070 /// |Filename|.
0071 Expected<Trace> loadTraceFile(StringRef Filename, bool Sort = false);
0072
0073 /// This function will attempt to load XRay trace records from the provided
0074 /// DataExtractor.
0075 Expected<Trace> loadTrace(const DataExtractor &Extractor, bool Sort = false);
0076
0077 } // namespace xray
0078 } // namespace llvm
0079
0080 #endif // LLVM_XRAY_TRACE_H