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 
31 namespace llvm {
32 
33 class MemoryBuffer;
34 
35 namespace vfs {
36 
37 class File;
38 
39 } // namespace vfs
40 } // namespace llvm
41 
42 namespace clang {
43 
44 class FileEntryRef;
45 
46 namespace optional_detail {
47 
48 /// Forward declare a template specialization for OptionalStorage.
49 template <> class OptionalStorage<clang::FileEntryRef>;
50 
51 } // namespace optional_detail
52 
53 class 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.
57 class FileEntryRef {
58 public:
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 
171 private:
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 
196 static_assert(sizeof(FileEntryRef) == sizeof(const FileEntry *),
197               "FileEntryRef must avoid size overhead");
198 
199 static_assert(std::is_trivially_copyable<FileEntryRef>::value,
200               "FileEntryRef must be trivially copyable");
201 
202 using OptionalFileEntryRef = CustomizableOptional<FileEntryRef>;
203 
204 namespace 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.
208 template <>
209 class OptionalStorage<clang::FileEntryRef>
210     : public clang::FileMgr::MapEntryOptionalStorage<clang::FileEntryRef> {
211   using StorageImpl =
212       clang::FileMgr::MapEntryOptionalStorage<clang::FileEntryRef>;
213 
214 public:
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 
227 static_assert(sizeof(OptionalFileEntryRef) == sizeof(FileEntryRef),
228               "OptionalFileEntryRef must avoid size overhead");
229 
230 static_assert(std::is_trivially_copyable<OptionalFileEntryRef>::value,
231               "OptionalFileEntryRef should be trivially copyable");
232 
233 } // end namespace optional_detail
234 } // namespace clang
235 
236 namespace llvm {
237 
238 template <> 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.
253 template <> 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 
282 namespace 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.
305 class OptionalFileEntryRefDegradesToFileEntryPtr : public OptionalFileEntryRef {
306 public:
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 
345 static_assert(
346     std::is_trivially_copyable<
347         OptionalFileEntryRefDegradesToFileEntryPtr>::value,
348     "OptionalFileEntryRefDegradesToFileEntryPtr should be trivially copyable");
349 
350 inline bool operator==(const FileEntry *LHS, const OptionalFileEntryRef &RHS) {
351   return LHS == (RHS ? &RHS->getFileEntry() : nullptr);
352 }
353 inline bool operator==(const OptionalFileEntryRef &LHS, const FileEntry *RHS) {
354   return (LHS ? &LHS->getFileEntry() : nullptr) == RHS;
355 }
356 inline bool operator!=(const FileEntry *LHS, const OptionalFileEntryRef &RHS) {
357   return !(LHS == RHS);
358 }
359 inline 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.
368 class 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 
397 public:
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 
418 off_t FileEntryRef::getSize() const { return getFileEntry().getSize(); }
419 
420 unsigned FileEntryRef::getUID() const { return getFileEntry().getUID(); }
421 
422 const llvm::sys::fs::UniqueID &FileEntryRef::getUniqueID() const {
423   return getFileEntry().getUniqueID();
424 }
425 
426 time_t FileEntryRef::getModificationTime() const {
427   return getFileEntry().getModificationTime();
428 }
429 
430 bool FileEntryRef::isNamedPipe() const { return getFileEntry().isNamedPipe(); }
431 
432 void FileEntryRef::closeFile() const { getFileEntry().closeFile(); }
433 
434 } // end namespace clang
435 
436 #endif // LLVM_CLANG_BASIC_FILEENTRY_H
437