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
81