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