1//===- clang/Basic/FileEntry.h - File references ----------------*- 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/// \file
10/// Defines interfaces for clang::FileEntry and clang::FileEntryRef.
11///
12//===----------------------------------------------------------------------===//
13
14#ifndef LLVM_CLANG_BASIC_FILEENTRY_H
15#define LLVM_CLANG_BASIC_FILEENTRY_H
16
17#include "clang/Basic/CustomizableOptional.h"
18#include "clang/Basic/DirectoryEntry.h"
19#include "clang/Basic/LLVM.h"
20#include "llvm/ADT/DenseMapInfo.h"
21#include "llvm/ADT/Hashing.h"
22#include "llvm/ADT/PointerUnion.h"
23#include "llvm/ADT/StringMap.h"
24#include "llvm/ADT/StringRef.h"
25#include "llvm/Support/ErrorOr.h"
26#include "llvm/Support/FileSystem/UniqueID.h"
27
28#include <optional>
29#include <utility>
30
31namespace llvm {
32
33class MemoryBuffer;
34
35namespace vfs {
36
37class File;
38
39} // namespace vfs
40} // namespace llvm
41
42namespace clang {
43
44class FileEntryRef;
45
46namespace optional_detail {
47
48/// Forward declare a template specialization for OptionalStorage.
49template <> class OptionalStorage<clang::FileEntryRef>;
50
51} // namespace optional_detail
52
53class FileEntry;
54
55/// A reference to a \c FileEntry that includes the name of the file as it was
56/// accessed by the FileManager's client.
57class FileEntryRef {
58public:
59 /// The name of this FileEntry. If a VFS uses 'use-external-name', this is
60 /// the redirected name. See getRequestedName().
61 StringRef getName() const { return getBaseMapEntry().first(); }
62
63 /// The name of this FileEntry, as originally requested without applying any
64 /// remappings for VFS 'use-external-name'.
65 ///
66 /// FIXME: this should be the semantics of getName(). See comment in
67 /// FileManager::getFileRef().
68 StringRef getNameAsRequested() const { return ME->first(); }
69
70 const FileEntry &getFileEntry() const {
71 return *getBaseMapEntry().second->V.get<FileEntry *>();
72 }
73 DirectoryEntryRef getDir() const { return ME->second->Dir; }
74
75 inline off_t getSize() const;
76 inline unsigned getUID() const;
77 inline const llvm::sys::fs::UniqueID &getUniqueID() const;
78 inline time_t getModificationTime() const;
79 inline bool isNamedPipe() const;
80 inline void closeFile() const;
81
82 /// Check if the underlying FileEntry is the same, intentially ignoring
83 /// whether the file was referenced with the same spelling of the filename.
84 friend bool operator==(const FileEntryRef &LHS, const FileEntryRef &RHS) {
85 return &LHS.getFileEntry() == &RHS.getFileEntry();
86 }
87 friend bool operator==(const FileEntry *LHS, const FileEntryRef &RHS) {
88 return LHS == &RHS.getFileEntry();
89 }
90 friend bool operator==(const FileEntryRef &LHS, const FileEntry *RHS) {
91 return &LHS.getFileEntry() == RHS;
92 }
93 friend bool operator!=(const FileEntryRef &LHS, const FileEntryRef &RHS) {
94 return !(LHS == RHS);
95 }
96 friend bool operator!=(const FileEntry *LHS, const FileEntryRef &RHS) {
97 return !(LHS == RHS);
98 }
99 friend bool operator!=(const FileEntryRef &LHS, const FileEntry *RHS) {
100 return !(LHS == RHS);
101 }
102
103 /// Hash code is based on the FileEntry, not the specific named reference,
104 /// just like operator==.
105 friend llvm::hash_code hash_value(FileEntryRef Ref) {
106 return llvm::hash_value(&Ref.getFileEntry());
107 }
108
109 struct MapValue;
110
111 /// Type used in the StringMap.
112 using MapEntry = llvm::StringMapEntry<llvm::ErrorOr<MapValue>>;
113
114 /// Type stored in the StringMap.
115 struct MapValue {
116 /// The pointer at another MapEntry is used when the FileManager should
117 /// silently forward from one name to another, which occurs in Redirecting
118 /// VFSs that use external names. In that case, the \c FileEntryRef
119 /// returned by the \c FileManager will have the external name, and not the
120 /// name that was used to lookup the file.
121 llvm::PointerUnion<FileEntry *, const MapEntry *> V;
122
123 /// Directory the file was found in.
124 DirectoryEntryRef Dir;
125
126 MapValue() = delete;
127 MapValue(FileEntry &FE, DirectoryEntryRef Dir) : V(&FE), Dir(Dir) {}
128 MapValue(MapEntry &ME, DirectoryEntryRef Dir) : V(&ME), Dir(Dir) {}
129 };
130
131 /// Check if RHS referenced the file in exactly the same way.
132 bool isSameRef(const FileEntryRef &RHS) const { return ME == RHS.ME; }
133
134 /// Allow FileEntryRef to degrade into 'const FileEntry*' to facilitate
135 /// incremental adoption.
136 ///
137 /// The goal is to avoid code churn due to dances like the following:
138 /// \code
139 /// // Old code.
140 /// lvalue = rvalue;
141 ///
142 /// // Temporary code from an incremental patch.
143 /// lvalue = &rvalue.getFileEntry();
144 ///
145 /// // Final code.
146 /// lvalue = rvalue;
147 /// \endcode
148 ///
149 /// FIXME: Once FileEntryRef is "everywhere" and FileEntry::LastRef and
150 /// FileEntry::getName have been deleted, delete this implicit conversion.
151 operator const FileEntry *() const { return &getFileEntry(); }
152
153 FileEntryRef() = delete;
154 explicit FileEntryRef(const MapEntry &ME) : ME(&ME) {
155 assert(ME.second && "Expected payload");
156 assert(ME.second->V && "Expected non-null");
157 }
158
159 /// Expose the underlying MapEntry to simplify packing in a PointerIntPair or
160 /// PointerUnion and allow construction in Optional.
161 const clang::FileEntryRef::MapEntry &getMapEntry() const { return *ME; }
162
163 /// Retrieve the base MapEntry after redirects.
164 const MapEntry &getBaseMapEntry() const {
165 const MapEntry *Base = ME;
166 while (const auto *Next = Base->second->V.dyn_cast<const MapEntry *>())
167 Base = Next;
168 return *Base;
169 }
170
171private:
172 friend class FileMgr::MapEntryOptionalStorage<FileEntryRef>;
173 struct optional_none_tag {};
174
175 // Private constructor for use by OptionalStorage.
176 FileEntryRef(optional_none_tag) : ME(nullptr) {}
177 bool hasOptionalValue() const { return ME; }
178
179 friend struct llvm::DenseMapInfo<FileEntryRef>;
180 struct dense_map_empty_tag {};
181 struct dense_map_tombstone_tag {};
182
183 // Private constructors for use by DenseMapInfo.
184 FileEntryRef(dense_map_empty_tag)
185 : ME(llvm::DenseMapInfo<const MapEntry *>::getEmptyKey()) {}
186 FileEntryRef(dense_map_tombstone_tag)
187 : ME(llvm::DenseMapInfo<const MapEntry *>::getTombstoneKey()) {}
188 bool isSpecialDenseMapKey() const {
189 return isSameRef(FileEntryRef(dense_map_empty_tag())) ||
190 isSameRef(FileEntryRef(dense_map_tombstone_tag()));
191 }
192
193 const MapEntry *ME;
194};
195
196static_assert(sizeof(FileEntryRef) == sizeof(const FileEntry *),
197 "FileEntryRef must avoid size overhead");
198
199static_assert(std::is_trivially_copyable<FileEntryRef>::value,
200 "FileEntryRef must be trivially copyable");
201
202using OptionalFileEntryRef = CustomizableOptional<FileEntryRef>;
203
204namespace optional_detail {
205
206/// Customize OptionalStorage<FileEntryRef> to use FileEntryRef and its
207/// optional_none_tag to keep it the size of a single pointer.
208template <>
209class OptionalStorage<clang::FileEntryRef>
210 : public clang::FileMgr::MapEntryOptionalStorage<clang::FileEntryRef> {
211 using StorageImpl =
212 clang::FileMgr::MapEntryOptionalStorage<clang::FileEntryRef>;
213
214public:
215 OptionalStorage() = default;
216
217 template <class... ArgTypes>
218 explicit OptionalStorage(std::in_place_t, ArgTypes &&...Args)
219 : StorageImpl(std::in_place_t{}, std::forward<ArgTypes>(Args)...) {}
220
221 OptionalStorage &operator=(clang::FileEntryRef Ref) {
222 StorageImpl::operator=(Ref);
223 return *this;
224 }
225};
226
227static_assert(sizeof(OptionalFileEntryRef) == sizeof(FileEntryRef),
228 "OptionalFileEntryRef must avoid size overhead");
229
230static_assert(std::is_trivially_copyable<OptionalFileEntryRef>::value,
231 "OptionalFileEntryRef should be trivially copyable");
232
233} // end namespace optional_detail
234} // namespace clang
235
236namespace llvm {
237
238template <> struct PointerLikeTypeTraits<clang::FileEntryRef> {
239 static inline void *getAsVoidPointer(clang::FileEntryRef File) {
240 return const_cast<clang::FileEntryRef::MapEntry *>(&File.getMapEntry());
241 }
242
243 static inline clang::FileEntryRef getFromVoidPointer(void *Ptr) {
244 return clang::FileEntryRef(
245 *reinterpret_cast<const clang::FileEntryRef::MapEntry *>(Ptr));
246 }
247
248 static constexpr int NumLowBitsAvailable = PointerLikeTypeTraits<
249 const clang::FileEntryRef::MapEntry *>::NumLowBitsAvailable;
250};
251
252/// Specialisation of DenseMapInfo for FileEntryRef.
253template <> struct DenseMapInfo<clang::FileEntryRef> {
254 static inline clang::FileEntryRef getEmptyKey() {
255 return clang::FileEntryRef(clang::FileEntryRef::dense_map_empty_tag());
256 }
257
258 static inline clang::FileEntryRef getTombstoneKey() {
259 return clang::FileEntryRef(clang::FileEntryRef::dense_map_tombstone_tag());
260 }
261
262 static unsigned getHashValue(clang::FileEntryRef Val) {
263 return hash_value(Val);
264 }
265
266 static bool isEqual(clang::FileEntryRef LHS, clang::FileEntryRef RHS) {
267 // Catch the easy cases: both empty, both tombstone, or the same ref.
268 if (LHS.isSameRef(RHS))
269 return true;
270
271 // Confirm LHS and RHS are valid.
272 if (LHS.isSpecialDenseMapKey() || RHS.isSpecialDenseMapKey())
273 return false;
274
275 // It's safe to use operator==.
276 return LHS == RHS;
277 }
278};
279
280} // end namespace llvm
281
282namespace clang {
283
284/// Wrapper around OptionalFileEntryRef that degrades to 'const FileEntry*',
285/// facilitating incremental patches to propagate FileEntryRef.
286///
287/// This class can be used as return value or field where it's convenient for
288/// an OptionalFileEntryRef to degrade to a 'const FileEntry*'. The purpose
289/// is to avoid code churn due to dances like the following:
290/// \code
291/// // Old code.
292/// lvalue = rvalue;
293///
294/// // Temporary code from an incremental patch.
295/// OptionalFileEntryRef MaybeF = rvalue;
296/// lvalue = MaybeF ? &MaybeF.getFileEntry() : nullptr;
297///
298/// // Final code.
299/// lvalue = rvalue;
300/// \endcode
301///
302/// FIXME: Once FileEntryRef is "everywhere" and FileEntry::LastRef and
303/// FileEntry::getName have been deleted, delete this class and replace
304/// instances with OptionalFileEntryRef.
305class OptionalFileEntryRefDegradesToFileEntryPtr : public OptionalFileEntryRef {
306public:
307 OptionalFileEntryRefDegradesToFileEntryPtr() = default;
308 OptionalFileEntryRefDegradesToFileEntryPtr(
309 OptionalFileEntryRefDegradesToFileEntryPtr &&) = default;
310 OptionalFileEntryRefDegradesToFileEntryPtr(
311 const OptionalFileEntryRefDegradesToFileEntryPtr &) = default;
312 OptionalFileEntryRefDegradesToFileEntryPtr &
313 operator=(OptionalFileEntryRefDegradesToFileEntryPtr &&) = default;
314 OptionalFileEntryRefDegradesToFileEntryPtr &
315 operator=(const OptionalFileEntryRefDegradesToFileEntryPtr &) = default;
316
317 OptionalFileEntryRefDegradesToFileEntryPtr(std::nullopt_t) {}
318 OptionalFileEntryRefDegradesToFileEntryPtr(FileEntryRef Ref)
319 : OptionalFileEntryRef(Ref) {}
320 OptionalFileEntryRefDegradesToFileEntryPtr(OptionalFileEntryRef MaybeRef)
321 : OptionalFileEntryRef(MaybeRef) {}
322
323 OptionalFileEntryRefDegradesToFileEntryPtr &operator=(std::nullopt_t) {
324 OptionalFileEntryRef::operator=(std::nullopt);
325 return *this;
326 }
327 OptionalFileEntryRefDegradesToFileEntryPtr &operator=(FileEntryRef Ref) {
328 OptionalFileEntryRef::operator=(Ref);
329 return *this;
330 }
331 OptionalFileEntryRefDegradesToFileEntryPtr &
332 operator=(OptionalFileEntryRef MaybeRef) {
333 OptionalFileEntryRef::operator=(MaybeRef);
334 return *this;
335 }
336
337 /// Degrade to 'const FileEntry *' to allow FileEntry::LastRef and
338 /// FileEntry::getName have been deleted, delete this class and replace
339 /// instances with OptionalFileEntryRef
340 operator const FileEntry *() const {
341 return has_value() ? &(*this)->getFileEntry() : nullptr;
342 }
343};
344
345static_assert(
346 std::is_trivially_copyable<
347 OptionalFileEntryRefDegradesToFileEntryPtr>::value,
348 "OptionalFileEntryRefDegradesToFileEntryPtr should be trivially copyable");
349
350inline bool operator==(const FileEntry *LHS, const OptionalFileEntryRef &RHS) {
351 return LHS == (RHS ? &RHS->getFileEntry() : nullptr);
352}
353inline bool operator==(const OptionalFileEntryRef &LHS, const FileEntry *RHS) {
354 return (LHS ? &LHS->getFileEntry() : nullptr) == RHS;
355}
356inline bool operator!=(const FileEntry *LHS, const OptionalFileEntryRef &RHS) {
357 return !(LHS == RHS);
358}
359inline bool operator!=(const OptionalFileEntryRef &LHS, const FileEntry *RHS) {
360 return !(LHS == RHS);
361}
362
363/// Cached information about one file (either on disk
364/// or in the virtual file system).
365///
366/// If the 'File' member is valid, then this FileEntry has an open file
367/// descriptor for the file.
368class FileEntry {
369 friend class FileManager;
370 friend class FileEntryTestHelper;
371 FileEntry();
372 FileEntry(const FileEntry &) = delete;
373 FileEntry &operator=(const FileEntry &) = delete;
374
375 std::string RealPathName; // Real path to the file; could be empty.
376 off_t Size = 0; // File size in bytes.
377 time_t ModTime = 0; // Modification time of file.
378 const DirectoryEntry *Dir = nullptr; // Directory file lives in.
379 llvm::sys::fs::UniqueID UniqueID;
380 unsigned UID = 0; // A unique (small) ID for the file.
381 bool IsNamedPipe = false;
382
383 /// The open file, if it is owned by the \p FileEntry.
384 mutable std::unique_ptr<llvm::vfs::File> File;
385
386 /// The file content, if it is owned by the \p FileEntry.
387 std::unique_ptr<llvm::MemoryBuffer> Content;
388
389 // First access name for this FileEntry.
390 //
391 // This is Optional only to allow delayed construction (FileEntryRef has no
392 // default constructor). It should always have a value in practice.
393 //
394 // TODO: remove this once everyone that needs a name uses FileEntryRef.
395 OptionalFileEntryRef LastRef;
396
397public:
398 ~FileEntry();
399 StringRef getName() const { return LastRef->getName(); }
400 FileEntryRef getLastRef() const { return *LastRef; }
401
402 StringRef tryGetRealPathName() const { return RealPathName; }
403 off_t getSize() const { return Size; }
404 unsigned getUID() const { return UID; }
405 const llvm::sys::fs::UniqueID &getUniqueID() const { return UniqueID; }
406 time_t getModificationTime() const { return ModTime; }
407
408 /// Return the directory the file lives in.
409 const DirectoryEntry *getDir() const { return Dir; }
410
411 /// Check whether the file is a named pipe (and thus can't be opened by
412 /// the native FileManager methods).
413 bool isNamedPipe() const { return IsNamedPipe; }
414
415 void closeFile() const;
416};
417
418off_t FileEntryRef::getSize() const { return getFileEntry().getSize(); }
419
420unsigned FileEntryRef::getUID() const { return getFileEntry().getUID(); }
421
422const llvm::sys::fs::UniqueID &FileEntryRef::getUniqueID() const {
423 return getFileEntry().getUniqueID();
424}
425
426time_t FileEntryRef::getModificationTime() const {
427 return getFileEntry().getModificationTime();
428}
429
430bool FileEntryRef::isNamedPipe() const { return getFileEntry().isNamedPipe(); }
431
432void FileEntryRef::closeFile() const { getFileEntry().closeFile(); }
433
434} // end namespace clang
435
436#endif // LLVM_CLANG_BASIC_FILEENTRY_H
437