clang 24.0.0git
ModuleCache.h
Go to the documentation of this file.
1//===----------------------------------------------------------------------===//
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 LLVM_CLANG_SERIALIZATION_MODULECACHE_H
10#define LLVM_CLANG_SERIALIZATION_MODULECACHE_H
11
12#include "clang/Basic/LLVM.h"
13#include "llvm/ADT/DenseMap.h"
14#include "llvm/ADT/STLFunctionalExtras.h"
15#include "llvm/ADT/StringMap.h"
16#include "llvm/Support/ErrorOr.h"
17#include "llvm/Support/FileSystem/UniqueID.h"
18
19#include <ctime>
20#include <memory>
21#include <optional>
22#include <sys/types.h>
23#include <system_error>
24
25namespace llvm {
26class AdvisoryLock;
27class MemoryBuffer;
28class MemoryBufferRef;
29} // namespace llvm
30
31namespace clang {
34
35/// The address of an instance of this class represents the identity of a module
36/// cache directory.
38
39/// The module cache used for compiling modules implicitly. This centralizes the
40/// operations the compiler might want to perform on the cache.
42 /// Mapping from a path to the module cache directory identity.
43 llvm::StringMap<const ModuleCacheDirectory *> ByPath;
44
45 /// Mapping from the filesystem entity to the module cache directory identity.
46 llvm::DenseMap<llvm::sys::fs::UniqueID, std::unique_ptr<ModuleCacheDirectory>>
47 ByUID;
48
49protected:
50 /// A logger to record timestamp read/write and file read/write.
52
53public:
55
56 /// Returns an opaque pointer representing the module cache directory. This
57 /// returns the same pointer regardless of the path spelling, as long as it
58 /// resolves to the same file system entity. This also resolves links in the
59 /// path. This may return nullptr if the module cache does not exist.
60 virtual const ModuleCacheDirectory *getDirectoryPtr(StringRef Path);
61
62 /// Returns lock for the given module file. The lock is initially unlocked.
63 virtual std::unique_ptr<llvm::AdvisoryLock>
64 getLock(StringRef ModuleFilename) = 0;
65
66 // TODO: Abstract away timestamps with isUpToDate() and markUpToDate().
67 // TODO: Consider exposing a "validation lock" API to prevent multiple clients
68 // concurrently noticing an out-of-date module file and validating its inputs.
69
70 /// Returns the timestamp denoting the last time inputs of the module file
71 /// were validated.
72 virtual std::time_t getModuleTimestamp(StringRef ModuleFilename) = 0;
73
74 /// Updates the timestamp denoting the last time inputs of the module file
75 /// were validated.
76 virtual void updateModuleTimestamp(StringRef ModuleFilename) = 0;
77
78 /// Whether the build system reported that \p Directory changed before the
79 /// build session started, or std::nullopt if this cache can't tell and the
80 /// file system has to be checked instead.
81 virtual std::optional<bool> isDirectoryInvalidated(StringRef Directory) {
82 return std::nullopt;
83 }
84
85 /// Prune module files that haven't been accessed in a long time.
86 virtual void maybePrune(StringRef Path, time_t PruneInterval,
87 time_t PruneAfter) = 0;
88
89 /// Returns this process's view of the module cache.
91 virtual const InMemoryModuleCache &getInMemoryModuleCache() const = 0;
92
93 /// Write the PCM contents to the given path in the module cache. Takes
94 /// ownership of \p Buffer, so that it can be freed as soon as possible.
95 ///
96 /// Returns a buffer with the written contents, which readers in this process
97 /// should use instead of their own copy.
98 virtual llvm::ErrorOr<std::unique_ptr<llvm::MemoryBuffer>>
99 write(StringRef Path, std::unique_ptr<llvm::MemoryBuffer> Buffer, off_t &Size,
100 time_t &ModTime) = 0;
101
103 read(StringRef FileName, off_t &Size, time_t &ModTime) = 0;
104
105 virtual ~ModuleCache() = default;
106
108};
109
110/// Creates new \c ModuleCache backed by a file system directory that may be
111/// operated on by multiple processes. This instance must be used across all
112/// \c CompilerInstance instances participating in building modules for single
113/// translation unit in order to share the same \c InMemoryModuleCache.
114std::shared_ptr<ModuleCache> createCrossProcessModuleCache();
115
116/// Shared implementation of `ModuleCache::maybePrune()`.
117///
118/// If \p OnPrune is non-empty, it is invoked once per file or directory that
119/// is successfully removed from the cache. The path passed to \p OnPrune is
120/// absolute.
121void maybePruneImpl(StringRef Path, time_t PruneInterval, time_t PruneAfter,
122 bool PruneTopLevel = false,
123 llvm::function_ref<void(StringRef)> OnPrune = {});
124
125/// Shared implementation of `ModuleCache::write()`.
126///
127/// If \p ReadBack is true, returns the contents of the written file, read back
128/// from the same file descriptor (and therefore immune to concurrent
129/// replacement of the file at \p Path). Otherwise, returns nullptr on success.
130llvm::ErrorOr<std::unique_ptr<llvm::MemoryBuffer>>
131writeImpl(StringRef Path, llvm::MemoryBufferRef Buffer, off_t &Size,
132 time_t &ModTime, bool ReadBack);
133
134/// Shared implementation of `ModuleCache::read()`.
136readImpl(StringRef FileName, off_t &Size, time_t &ModTime);
137} // namespace clang
138
139#endif
Forward-declares and imports various common LLVM datatypes that clang wants to use unqualified.
In-memory cache for modules.
The address of an instance of this class represents the identity of a module cache directory.
Definition ModuleCache.h:37
virtual std::optional< bool > isDirectoryInvalidated(StringRef Directory)
Whether the build system reported that Directory changed before the build session started,...
Definition ModuleCache.h:81
AtomicLineLogger & getLogger()
virtual ~ModuleCache()=default
virtual llvm::ErrorOr< std::unique_ptr< llvm::MemoryBuffer > > write(StringRef Path, std::unique_ptr< llvm::MemoryBuffer > Buffer, off_t &Size, time_t &ModTime)=0
Write the PCM contents to the given path in the module cache.
virtual const InMemoryModuleCache & getInMemoryModuleCache() const =0
virtual std::time_t getModuleTimestamp(StringRef ModuleFilename)=0
Returns the timestamp denoting the last time inputs of the module file were validated.
AtomicLineLogger & Logger
A logger to record timestamp read/write and file read/write.
Definition ModuleCache.h:51
virtual InMemoryModuleCache & getInMemoryModuleCache()=0
Returns this process's view of the module cache.
virtual void updateModuleTimestamp(StringRef ModuleFilename)=0
Updates the timestamp denoting the last time inputs of the module file were validated.
virtual Expected< std::unique_ptr< llvm::MemoryBuffer > > read(StringRef FileName, off_t &Size, time_t &ModTime)=0
ModuleCache(AtomicLineLogger &Logger)
Definition ModuleCache.h:54
virtual const ModuleCacheDirectory * getDirectoryPtr(StringRef Path)
Returns an opaque pointer representing the module cache directory.
virtual void maybePrune(StringRef Path, time_t PruneInterval, time_t PruneAfter)=0
Prune module files that haven't been accessed in a long time.
virtual std::unique_ptr< llvm::AdvisoryLock > getLock(StringRef ModuleFilename)=0
Returns lock for the given module file. The lock is initially unlocked.
Top level wrappers for InstallAPI frontend operations.
Expected< std::unique_ptr< llvm::MemoryBuffer > > readImpl(StringRef FileName, off_t &Size, time_t &ModTime)
Shared implementation of ModuleCache::read().
std::shared_ptr< ModuleCache > createCrossProcessModuleCache()
Creates new ModuleCache backed by a file system directory that may be operated on by multiple process...
llvm::ErrorOr< std::unique_ptr< llvm::MemoryBuffer > > writeImpl(StringRef Path, llvm::MemoryBufferRef Buffer, off_t &Size, time_t &ModTime, bool ReadBack)
Shared implementation of ModuleCache::write().
void maybePruneImpl(StringRef Path, time_t PruneInterval, time_t PruneAfter, bool PruneTopLevel=false, llvm::function_ref< void(StringRef)> OnPrune={})
Shared implementation of ModuleCache::maybePrune().
Diagnostic wrappers for TextAPI types for error reporting.
Definition Dominators.h:30