clang  14.0.0git
DirectoryWatcher-linux.cpp
Go to the documentation of this file.
1 //===- DirectoryWatcher-linux.cpp - Linux-platform directory watching -----===//
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 #include "DirectoryScanner.h"
11 
12 #include "llvm/ADT/STLExtras.h"
13 #include "llvm/ADT/ScopeExit.h"
14 #include "llvm/Support/AlignOf.h"
15 #include "llvm/Support/Errno.h"
16 #include "llvm/Support/Error.h"
17 #include "llvm/Support/MathExtras.h"
18 #include "llvm/Support/Path.h"
19 #include <atomic>
20 #include <condition_variable>
21 #include <mutex>
22 #include <queue>
23 #include <string>
24 #include <thread>
25 #include <vector>
26 
27 #include <fcntl.h>
28 #include <sys/epoll.h>
29 #include <sys/inotify.h>
30 #include <unistd.h>
31 
32 namespace {
33 
34 using namespace llvm;
35 using namespace clang;
36 
37 /// Pipe for inter-thread synchronization - for epoll-ing on multiple
38 /// conditions. It is meant for uni-directional 1:1 signalling - specifically:
39 /// no multiple consumers, no data passing. Thread waiting for signal should
40 /// poll the FDRead. Signalling thread should call signal() which writes single
41 /// character to FDRead.
42 struct SemaphorePipe {
43  // Expects two file-descriptors opened as a pipe in the canonical POSIX
44  // order: pipefd[0] refers to the read end of the pipe. pipefd[1] refers to
45  // the write end of the pipe.
46  SemaphorePipe(int pipefd[2])
47  : FDRead(pipefd[0]), FDWrite(pipefd[1]), OwnsFDs(true) {}
48  SemaphorePipe(const SemaphorePipe &) = delete;
49  void operator=(const SemaphorePipe &) = delete;
50  SemaphorePipe(SemaphorePipe &&other)
51  : FDRead(other.FDRead), FDWrite(other.FDWrite),
52  OwnsFDs(other.OwnsFDs) // Someone could have moved from the other
53  // instance before.
54  {
55  other.OwnsFDs = false;
56  };
57 
58  void signal() {
59 #ifndef NDEBUG
60  ssize_t Result =
61 #endif
62  llvm::sys::RetryAfterSignal(-1, write, FDWrite, "A", 1);
63  assert(Result != -1);
64  }
65  ~SemaphorePipe() {
66  if (OwnsFDs) {
67  close(FDWrite);
68  close(FDRead);
69  }
70  }
71  const int FDRead;
72  const int FDWrite;
73  bool OwnsFDs;
74 
76  int InotifyPollingStopperFDs[2];
77  if (pipe2(InotifyPollingStopperFDs, O_CLOEXEC) == -1)
78  return llvm::None;
79  return SemaphorePipe(InotifyPollingStopperFDs);
80  }
81 };
82 
83 /// Mutex-protected queue of Events.
84 class EventQueue {
85  std::mutex Mtx;
86  std::condition_variable NonEmpty;
87  std::queue<DirectoryWatcher::Event> Events;
88 
89 public:
90  void push_back(const DirectoryWatcher::Event::EventKind K,
91  StringRef Filename) {
92  {
93  std::unique_lock<std::mutex> L(Mtx);
94  Events.emplace(K, Filename);
95  }
96  NonEmpty.notify_one();
97  }
98 
99  // Blocks on caller thread and uses codition_variable to wait until there's an
100  // event to return.
101  DirectoryWatcher::Event pop_front_blocking() {
102  std::unique_lock<std::mutex> L(Mtx);
103  while (true) {
104  // Since we might have missed all the prior notifications on NonEmpty we
105  // have to check the queue first (under lock).
106  if (!Events.empty()) {
107  DirectoryWatcher::Event Front = Events.front();
108  Events.pop();
109  return Front;
110  }
111  NonEmpty.wait(L, [this]() { return !Events.empty(); });
112  }
113  }
114 };
115 
116 class DirectoryWatcherLinux : public clang::DirectoryWatcher {
117 public:
118  DirectoryWatcherLinux(
119  llvm::StringRef WatchedDirPath,
120  std::function<void(llvm::ArrayRef<Event>, bool)> Receiver,
121  bool WaitForInitialSync, int InotifyFD, int InotifyWD,
122  SemaphorePipe &&InotifyPollingStopSignal);
123 
124  ~DirectoryWatcherLinux() override {
125  StopWork();
126  InotifyPollingThread.join();
127  EventsReceivingThread.join();
128  inotify_rm_watch(InotifyFD, InotifyWD);
129  llvm::sys::RetryAfterSignal(-1, close, InotifyFD);
130  }
131 
132 private:
133  const std::string WatchedDirPath;
134  // inotify file descriptor
135  int InotifyFD = -1;
136  // inotify watch descriptor
137  int InotifyWD = -1;
138 
139  EventQueue Queue;
140 
141  // Make sure lifetime of Receiver fully contains lifetime of
142  // EventsReceivingThread.
143  std::function<void(llvm::ArrayRef<Event>, bool)> Receiver;
144 
145  // Consumes inotify events and pushes directory watcher events to the Queue.
146  void InotifyPollingLoop();
147  std::thread InotifyPollingThread;
148  // Using pipe so we can epoll two file descriptors at once - inotify and
149  // stopping condition.
150  SemaphorePipe InotifyPollingStopSignal;
151 
152  // Does the initial scan of the directory - directly calling Receiver,
153  // bypassing the Queue. Both InitialScan and EventReceivingLoop use Receiver
154  // which isn't necessarily thread-safe.
155  void InitialScan();
156 
157  // Processing events from the Queue.
158  // In case client doesn't want to do the initial scan synchronously
159  // (WaitForInitialSync=false in ctor) we do the initial scan at the beginning
160  // of this thread.
161  std::thread EventsReceivingThread;
162  // Push event of WatcherGotInvalidated kind to the Queue to stop the loop.
163  // Both InitialScan and EventReceivingLoop use Receiver which isn't
164  // necessarily thread-safe.
165  void EventReceivingLoop();
166 
167  // Stops all the async work. Reentrant.
168  void StopWork() {
169  Queue.push_back(DirectoryWatcher::Event::EventKind::WatcherGotInvalidated,
170  "");
171  InotifyPollingStopSignal.signal();
172  }
173 };
174 
175 void DirectoryWatcherLinux::InotifyPollingLoop() {
176  // We want to be able to read ~30 events at once even in the worst case
177  // (obscenely long filenames).
178  constexpr size_t EventBufferLength =
179  30 * (sizeof(struct inotify_event) + NAME_MAX + 1);
180  // http://man7.org/linux/man-pages/man7/inotify.7.html
181  // Some systems cannot read integer variables if they are not
182  // properly aligned. On other systems, incorrect alignment may
183  // decrease performance. Hence, the buffer used for reading from
184  // the inotify file descriptor should have the same alignment as
185  // struct inotify_event.
186 
187  struct Buffer {
188  alignas(struct inotify_event) char buffer[EventBufferLength];
189  };
190  auto ManagedBuffer = std::make_unique<Buffer>();
191  char *const Buf = ManagedBuffer->buffer;
192 
193  const int EpollFD = epoll_create1(EPOLL_CLOEXEC);
194  if (EpollFD == -1) {
195  StopWork();
196  return;
197  }
198  auto EpollFDGuard = llvm::make_scope_exit([EpollFD]() { close(EpollFD); });
199 
200  struct epoll_event EventSpec;
201  EventSpec.events = EPOLLIN;
202  EventSpec.data.fd = InotifyFD;
203  if (epoll_ctl(EpollFD, EPOLL_CTL_ADD, InotifyFD, &EventSpec) == -1) {
204  StopWork();
205  return;
206  }
207 
208  EventSpec.data.fd = InotifyPollingStopSignal.FDRead;
209  if (epoll_ctl(EpollFD, EPOLL_CTL_ADD, InotifyPollingStopSignal.FDRead,
210  &EventSpec) == -1) {
211  StopWork();
212  return;
213  }
214 
215  std::array<struct epoll_event, 2> EpollEventBuffer;
216 
217  while (true) {
218  const int EpollWaitResult = llvm::sys::RetryAfterSignal(
219  -1, epoll_wait, EpollFD, EpollEventBuffer.data(),
220  EpollEventBuffer.size(), /*timeout=*/-1 /*== infinity*/);
221  if (EpollWaitResult == -1) {
222  StopWork();
223  return;
224  }
225 
226  // Multiple epoll_events can be received for a single file descriptor per
227  // epoll_wait call.
228  for (int i = 0; i < EpollWaitResult; ++i) {
229  if (EpollEventBuffer[i].data.fd == InotifyPollingStopSignal.FDRead) {
230  StopWork();
231  return;
232  }
233  }
234 
235  // epoll_wait() always return either error or >0 events. Since there was no
236  // event for stopping, it must be an inotify event ready for reading.
237  ssize_t NumRead = llvm::sys::RetryAfterSignal(-1, read, InotifyFD, Buf,
238  EventBufferLength);
239  for (char *P = Buf; P < Buf + NumRead;) {
240  if (P + sizeof(struct inotify_event) > Buf + NumRead) {
241  StopWork();
242  llvm_unreachable("an incomplete inotify_event was read");
243  return;
244  }
245 
246  struct inotify_event *Event = reinterpret_cast<struct inotify_event *>(P);
247  P += sizeof(struct inotify_event) + Event->len;
248 
249  if (Event->mask & (IN_CREATE | IN_MODIFY | IN_MOVED_TO | IN_DELETE) &&
250  Event->len <= 0) {
251  StopWork();
252  llvm_unreachable("expected a filename from inotify");
253  return;
254  }
255 
256  if (Event->mask & (IN_CREATE | IN_MOVED_TO | IN_MODIFY)) {
257  Queue.push_back(DirectoryWatcher::Event::EventKind::Modified,
258  Event->name);
259  } else if (Event->mask & (IN_DELETE | IN_MOVED_FROM)) {
260  Queue.push_back(DirectoryWatcher::Event::EventKind::Removed,
261  Event->name);
262  } else if (Event->mask & (IN_DELETE_SELF | IN_MOVE_SELF)) {
263  Queue.push_back(DirectoryWatcher::Event::EventKind::WatchedDirRemoved,
264  "");
265  StopWork();
266  return;
267  } else if (Event->mask & IN_IGNORED) {
268  StopWork();
269  return;
270  } else {
271  StopWork();
272  llvm_unreachable("Unknown event type.");
273  return;
274  }
275  }
276  }
277 }
278 
279 void DirectoryWatcherLinux::InitialScan() {
280  this->Receiver(getAsFileEvents(scanDirectory(WatchedDirPath)),
281  /*IsInitial=*/true);
282 }
283 
284 void DirectoryWatcherLinux::EventReceivingLoop() {
285  while (true) {
286  DirectoryWatcher::Event Event = this->Queue.pop_front_blocking();
287  this->Receiver(Event, false);
288  if (Event.Kind ==
289  DirectoryWatcher::Event::EventKind::WatcherGotInvalidated) {
290  StopWork();
291  return;
292  }
293  }
294 }
295 
296 DirectoryWatcherLinux::DirectoryWatcherLinux(
297  StringRef WatchedDirPath,
298  std::function<void(llvm::ArrayRef<Event>, bool)> Receiver,
299  bool WaitForInitialSync, int InotifyFD, int InotifyWD,
300  SemaphorePipe &&InotifyPollingStopSignal)
301  : WatchedDirPath(WatchedDirPath), InotifyFD(InotifyFD),
302  InotifyWD(InotifyWD), Receiver(Receiver),
303  InotifyPollingStopSignal(std::move(InotifyPollingStopSignal)) {
304 
305  InotifyPollingThread = std::thread([this]() { InotifyPollingLoop(); });
306  // We have no guarantees about thread safety of the Receiver which is being
307  // used in both InitialScan and EventReceivingLoop. We shouldn't run these
308  // only synchronously.
309  if (WaitForInitialSync) {
310  InitialScan();
311  EventsReceivingThread = std::thread([this]() { EventReceivingLoop(); });
312  } else {
313  EventsReceivingThread = std::thread([this]() {
314  // FIXME: We might want to terminate an async initial scan early in case
315  // of a failure in EventsReceivingThread.
316  InitialScan();
317  EventReceivingLoop();
318  });
319  }
320 }
321 
322 } // namespace
323 
325  StringRef Path,
326  std::function<void(llvm::ArrayRef<DirectoryWatcher::Event>, bool)> Receiver,
327  bool WaitForInitialSync) {
328  if (Path.empty())
329  llvm::report_fatal_error(
330  "DirectoryWatcher::create can not accept an empty Path.");
331 
332  const int InotifyFD = inotify_init1(IN_CLOEXEC);
333  if (InotifyFD == -1)
334  return llvm::make_error<llvm::StringError>(
335  std::string("inotify_init1() error: ") + strerror(errno),
336  llvm::inconvertibleErrorCode());
337 
338  const int InotifyWD = inotify_add_watch(
339  InotifyFD, Path.str().c_str(),
340  IN_CREATE | IN_DELETE | IN_DELETE_SELF | IN_MODIFY |
341  IN_MOVED_FROM | IN_MOVE_SELF | IN_MOVED_TO | IN_ONLYDIR | IN_IGNORED
342 #ifdef IN_EXCL_UNLINK
343  | IN_EXCL_UNLINK
344 #endif
345  );
346  if (InotifyWD == -1)
347  return llvm::make_error<llvm::StringError>(
348  std::string("inotify_add_watch() error: ") + strerror(errno),
349  llvm::inconvertibleErrorCode());
350 
351  auto InotifyPollingStopper = SemaphorePipe::create();
352 
353  if (!InotifyPollingStopper)
354  return llvm::make_error<llvm::StringError>(
355  std::string("SemaphorePipe::create() error: ") + strerror(errno),
356  llvm::inconvertibleErrorCode());
357 
358  return std::make_unique<DirectoryWatcherLinux>(
359  Path, Receiver, WaitForInitialSync, InotifyFD, InotifyWD,
360  std::move(*InotifyPollingStopper));
361 }
llvm
Definition: Dominators.h:30
string
string(SUBSTRING ${CMAKE_CURRENT_BINARY_DIR} 0 ${PATH_LIB_START} PATH_HEAD) string(SUBSTRING $
Definition: CMakeLists.txt:22
clang::DirectoryWatcher::Event::Kind
EventKind Kind
Definition: DirectoryWatcher.h:93
Filename
StringRef Filename
Definition: Format.cpp:2333
llvm::Optional
Definition: LLVM.h:40
llvm::Expected
Definition: LLVM.h:41
clang::DirectoryWatcher::Event::EventKind
EventKind
Definition: DirectoryWatcher.h:67
DirectoryScanner.h
DirectoryWatcher.h
clang::DirectoryWatcher::Event
Definition: DirectoryWatcher.h:66
P
StringRef P
Definition: ASTMatchersInternal.cpp:563
clang::serialized_diags::create
std::unique_ptr< DiagnosticConsumer > create(StringRef OutputFile, DiagnosticOptions *Diags, bool MergeChildRecords=false)
Returns a DiagnosticConsumer that serializes diagnostics to a bitcode file.
Definition: SerializedDiagnosticPrinter.cpp:302
clang::DirectoryWatcher
Provides notifications for file changes in a directory.
Definition: DirectoryWatcher.h:64
clang::getAsFileEvents
std::vector< DirectoryWatcher::Event > getAsFileEvents(const std::vector< std::string > &Scan)
Create event with EventKind::Added for every element in Scan.
Definition: DirectoryScanner.cpp:43
clang::DirectoryWatcher::create
static llvm::Expected< std::unique_ptr< DirectoryWatcher > > create(llvm::StringRef Path, std::function< void(llvm::ArrayRef< DirectoryWatcher::Event > Events, bool IsInitial)> Receiver, bool WaitForInitialSync)
llvm fatal_error if
Definition: DirectoryWatcher-not-implemented.cpp:14
llvm::ArrayRef
Definition: LLVM.h:34
std
Definition: Format.h:4034
clang
Definition: CalledOnceCheck.h:17
endif
endif() if(clang_vc AND LLVM_APPEND_VC_REV) set(clang_source_dir $
Definition: CMakeLists.txt:15
true
#define true
Definition: stdbool.h:16
clang::scanDirectory
std::vector< std::string > scanDirectory(StringRef Path)
Definition: DirectoryScanner.cpp:25