1 | //===-- DataFileCache.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 | #ifndef LLDB_CORE_DATAFILECACHE_H |
10 | #define LLDB_CORE_DATAFILECACHE_H |
11 | |
12 | #include "lldb/Utility/FileSpec.h" |
13 | #include "lldb/Utility/Status.h" |
14 | #include "lldb/Utility/UUID.h" |
15 | #include "lldb/lldb-forward.h" |
16 | #include "llvm/ADT/DenseMap.h" |
17 | #include "llvm/Support/CachePruning.h" |
18 | #include "llvm/Support/Caching.h" |
19 | #include "llvm/Support/MemoryBuffer.h" |
20 | |
21 | #include <mutex> |
22 | #include <optional> |
23 | |
24 | namespace lldb_private { |
25 | |
26 | /// This class enables data to be cached into a directory using the llvm |
27 | /// caching code. Data can be stored and accessed using a unique string key. |
28 | /// The data will be stored in the directory that is specified in the |
29 | /// DataFileCache constructor. The data will be stored in files that start with |
30 | /// "llvmcache-<key>" where <key> is the key name specified when getting to |
31 | /// setting cached data. |
32 | /// |
33 | /// Sample code for how to use the cache: |
34 | /// |
35 | /// DataFileCache cache("/tmp/lldb-test-cache"); |
36 | /// StringRef key("Key1"); |
37 | /// auto mem_buffer_up = cache.GetCachedData(key); |
38 | /// if (mem_buffer_up) { |
39 | /// printf("cached data:\n%s", mem_buffer_up->getBufferStart()); |
40 | /// } else { |
41 | /// std::vector<uint8_t> data = { 'h', 'e', 'l', 'l', 'o', '\n' }; |
42 | /// cache.SetCachedData(key, data); |
43 | /// } |
44 | |
45 | class DataFileCache { |
46 | public: |
47 | /// Create a data file cache in the directory path that is specified, using |
48 | /// the specified policy. |
49 | /// |
50 | /// Data will be cached in files created in this directory when clients call |
51 | /// DataFileCache::SetCacheData. |
52 | DataFileCache(llvm::StringRef path, |
53 | llvm::CachePruningPolicy policy = |
54 | DataFileCache::GetLLDBIndexCachePolicy()); |
55 | |
56 | /// Gets the default LLDB index cache policy, which is controlled by the |
57 | /// "LLDBIndexCache" family of settings. |
58 | static llvm::CachePruningPolicy GetLLDBIndexCachePolicy(); |
59 | |
60 | /// Get cached data from the cache directory for the specified key. |
61 | /// |
62 | /// Keys must be unique for any given data. This function attempts to see if |
63 | /// the data is available for the specified key and will return a valid memory |
64 | /// buffer is data is available. |
65 | /// |
66 | /// \param key |
67 | /// The unique string key that identifies data being cached. |
68 | /// |
69 | /// \return |
70 | /// A valid unique pointer to a memory buffer if the data is available, or |
71 | /// a unique pointer that contains NULL if the data is not available. |
72 | std::unique_ptr<llvm::MemoryBuffer> GetCachedData(llvm::StringRef key); |
73 | |
74 | /// Set cached data for the specified key. |
75 | /// |
76 | /// Setting the cached data will save a file in the cache directory to contain |
77 | /// the specified data. |
78 | /// |
79 | /// \param key |
80 | /// The unique string key that identifies data being cached. |
81 | /// |
82 | /// \return |
83 | /// True if the data was successfully cached, false otherwise. |
84 | bool SetCachedData(llvm::StringRef key, llvm::ArrayRef<uint8_t> data); |
85 | |
86 | /// Remove the cache file associated with the key. |
87 | Status RemoveCacheFile(llvm::StringRef key); |
88 | |
89 | private: |
90 | /// Return the cache file that is associated with the key. |
91 | FileSpec GetCacheFilePath(llvm::StringRef key); |
92 | |
93 | llvm::FileCache m_cache_callback; |
94 | FileSpec m_cache_dir; |
95 | std::mutex m_mutex; |
96 | std::unique_ptr<llvm::MemoryBuffer> m_mem_buff_up; |
97 | bool m_take_ownership = false; |
98 | }; |
99 | |
100 | /// A signature for a given file on disk. |
101 | /// |
102 | /// Any files that are cached in the LLDB index cached need some data that |
103 | /// uniquely identifies a file on disk and this information should be written |
104 | /// into each cache file so we can validate if the cache file still matches |
105 | /// the file we are trying to load cached data for. Objects can fill out this |
106 | /// signature and then encode and decode them to validate the signatures |
107 | /// match. If they do not match, the cache file on disk should be removed as |
108 | /// it is out of date. |
109 | struct CacheSignature { |
110 | /// UUID of object file or module. |
111 | std::optional<UUID> m_uuid; |
112 | /// Modification time of file on disk. |
113 | std::optional<std::time_t> m_mod_time; |
114 | /// If this describes a .o file with a BSD archive, the BSD archive's |
115 | /// modification time will be in m_mod_time, and the .o file's modification |
116 | /// time will be in this m_obj_mod_time. |
117 | std::optional<std::time_t> m_obj_mod_time; |
118 | |
119 | CacheSignature() = default; |
120 | |
121 | /// Create a signature from a module. |
122 | CacheSignature(lldb_private::Module *module); |
123 | |
124 | /// Create a signature from an object file. |
125 | CacheSignature(lldb_private::ObjectFile *objfile); |
126 | |
127 | void Clear() { |
128 | m_uuid = std::nullopt; |
129 | m_mod_time = std::nullopt; |
130 | m_obj_mod_time = std::nullopt; |
131 | } |
132 | |
133 | /// Return true only if the CacheSignature is valid. |
134 | /// |
135 | /// Cache signatures are considered valid only if there is a UUID in the file |
136 | /// that can uniquely identify the file. Some build systems play with |
137 | /// modification times of file so we can not trust them without using valid |
138 | /// unique idenifier like the UUID being valid. |
139 | bool IsValid() const { return m_uuid.has_value(); } |
140 | |
141 | /// Check if two signatures are the same. |
142 | bool operator==(const CacheSignature &rhs) const { |
143 | return m_uuid == rhs.m_uuid && m_mod_time == rhs.m_mod_time && |
144 | m_obj_mod_time == rhs.m_obj_mod_time; |
145 | } |
146 | |
147 | /// Check if two signatures differ. |
148 | bool operator!=(const CacheSignature &rhs) const { return !(*this == rhs); } |
149 | /// Encode this object into a data encoder object. |
150 | /// |
151 | /// This allows this object to be serialized to disk. The CacheSignature |
152 | /// object must have at least one member variable that has a value in order to |
153 | /// be serialized so that we can match this data to when the cached file is |
154 | /// loaded at a later time. |
155 | /// |
156 | /// \param encoder |
157 | /// A data encoder object that serialized bytes will be encoded into. |
158 | /// |
159 | /// \return |
160 | /// True if a signature was encoded, and false if there were no member |
161 | /// variables that had value. False indicates this data should not be |
162 | /// cached to disk because we were unable to encode a valid signature. |
163 | bool Encode(DataEncoder &encoder) const; |
164 | |
165 | /// Decode a serialized version of this object from data. |
166 | /// |
167 | /// \param data |
168 | /// The decoder object that references the serialized data. |
169 | /// |
170 | /// \param offset_ptr |
171 | /// A pointer that contains the offset from which the data will be decoded |
172 | /// from that gets updated as data gets decoded. |
173 | /// |
174 | /// \return |
175 | /// True if the signature was successfully decoded, false otherwise. |
176 | bool (const DataExtractor &data, lldb::offset_t *offset_ptr); |
177 | }; |
178 | |
179 | /// Many cache files require string tables to store data efficiently. This |
180 | /// class helps create string tables. |
181 | class ConstStringTable { |
182 | public: |
183 | ConstStringTable() = default; |
184 | /// Add a string into the string table. |
185 | /// |
186 | /// Add a string to the string table will only add the same string one time |
187 | /// and will return the offset in the string table buffer to that string. |
188 | /// String tables are easy to build with ConstString objects since most LLDB |
189 | /// classes for symbol or debug info use them already and they provide |
190 | /// permanent storage for the string. |
191 | /// |
192 | /// \param s |
193 | /// The string to insert into the string table. |
194 | /// |
195 | /// \return |
196 | /// The byte offset from the start of the string table for the inserted |
197 | /// string. Duplicate strings that get inserted will return the same |
198 | /// byte offset. |
199 | uint32_t Add(ConstString s); |
200 | |
201 | bool Encode(DataEncoder &encoder); |
202 | |
203 | private: |
204 | std::vector<ConstString> m_strings; |
205 | llvm::DenseMap<ConstString, uint32_t> m_string_to_offset; |
206 | /// Skip one byte to start the string table off with an empty string. |
207 | uint32_t m_next_offset = 1; |
208 | }; |
209 | |
210 | /// Many cache files require string tables to store data efficiently. This |
211 | /// class helps give out strings from a string table that was read from a |
212 | /// cache file. |
213 | class StringTableReader { |
214 | public: |
215 | StringTableReader() = default; |
216 | |
217 | llvm::StringRef Get(uint32_t offset) const; |
218 | |
219 | bool (const DataExtractor &data, lldb::offset_t *offset_ptr); |
220 | |
221 | protected: |
222 | /// All of the strings in the string table are contained in m_data. |
223 | llvm::StringRef m_data; |
224 | }; |
225 | |
226 | } // namespace lldb_private |
227 | |
228 | #endif // LLDB_CORE_DATAFILECACHE_H |
229 | |