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/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 
75   static llvm::Optional<SemaphorePipe> create() {
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 
324 llvm::Expected<std::unique_ptr<DirectoryWatcher>> clang::DirectoryWatcher::create(
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 }
362