1 //===-- llvm/Remarks/RemarkLinker.h -----------------------------*- C++/-*-===//
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 // This file provides an interface to link together multiple remark files.
10 //
11 //===----------------------------------------------------------------------===//
12 
13 #ifndef LLVM_REMARKS_REMARKLINKER_H
14 #define LLVM_REMARKS_REMARKLINKER_H
15 
16 #include "llvm/Remarks/Remark.h"
17 #include "llvm/Remarks/RemarkFormat.h"
18 #include "llvm/Remarks/RemarkStringTable.h"
19 #include "llvm/Support/Error.h"
20 #include <memory>
21 #include <optional>
22 #include <set>
23 
24 namespace llvm {
25 
26 namespace object {
27 class ObjectFile;
28 }
29 
30 namespace remarks {
31 
32 struct RemarkLinker {
33 private:
34   /// Compare through the pointers.
35   struct RemarkPtrCompare {
36     bool operator()(const std::unique_ptr<Remark> &LHS,
37                     const std::unique_ptr<Remark> &RHS) const {
38       assert(LHS && RHS && "Invalid pointers to compare.");
39       return *LHS < *RHS;
40     };
41   };
42 
43   /// The main string table for the remarks.
44   /// Note: all remarks should use the strings from this string table to avoid
45   /// dangling references.
46   StringTable StrTab;
47 
48   /// A set holding unique remarks.
49   /// FIXME: std::set is probably not the most appropriate data structure here.
50   /// Due to the limitation of having a move-only key, there isn't another
51   /// obvious choice for now.
52   std::set<std::unique_ptr<Remark>, RemarkPtrCompare> Remarks;
53 
54   /// A path to append before the external file path found in remark metadata.
55   std::optional<std::string> PrependPath;
56 
57   /// If true, keep all remarks, otherwise only keep remarks with valid debug
58   /// locations.
59   bool KeepAllRemarks = true;
60 
61   /// Keep this remark. If it's already in the set, discard it.
62   Remark &keep(std::unique_ptr<Remark> Remark);
63 
64   /// Returns true if \p R should be kept. If KeepAllRemarks is false, only
65   /// return true if \p R has a valid debug location.
66   bool shouldKeepRemark(const Remark &R) {
67     return KeepAllRemarks ? true : R.Loc.has_value();
68   }
69 
70 public:
71   /// Set a path to prepend to the external file path.
72   void setExternalFilePrependPath(StringRef PrependPath);
73 
74   /// Set KeepAllRemarks to \p B.
75   void setKeepAllRemarks(bool B) { KeepAllRemarks = B; }
76 
77   /// Link the remarks found in \p Buffer.
78   /// If \p RemarkFormat is not provided, try to deduce it from the metadata in
79   /// \p Buffer.
80   /// \p Buffer can be either a standalone remark container or just
81   /// metadata. This takes care of uniquing and merging the remarks.
82   Error link(StringRef Buffer,
83              std::optional<Format> RemarkFormat = std::nullopt);
84 
85   /// Link the remarks found in \p Obj by looking for the right section and
86   /// calling the method above.
87   Error link(const object::ObjectFile &Obj,
88              std::optional<Format> RemarkFormat = std::nullopt);
89 
90   /// Serialize the linked remarks to the stream \p OS, using the format \p
91   /// RemarkFormat.
92   /// This clears internal state such as the string table.
93   /// Note: this implies that the serialization mode is standalone.
94   Error serialize(raw_ostream &OS, Format RemarksFormat) const;
95 
96   /// Check whether there are any remarks linked.
97   bool empty() const { return Remarks.empty(); }
98 
99   /// Return a collection of the linked unique remarks to iterate on.
100   /// Ex:
101   /// for (const Remark &R : RL.remarks() { [...] }
102   using iterator = pointee_iterator<decltype(Remarks)::const_iterator>;
103 
104   iterator_range<iterator> remarks() const {
105     return {Remarks.begin(), Remarks.end()};
106   }
107 };
108 
109 /// Returns a buffer with the contents of the remarks section depending on the
110 /// format of the file. If the section doesn't exist, this returns an empty
111 /// optional.
112 Expected<std::optional<StringRef>>
113 getRemarksSectionContents(const object::ObjectFile &Obj);
114 
115 } // end namespace remarks
116 } // end namespace llvm
117 
118 #endif // LLVM_REMARKS_REMARKLINKER_H
119