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