1 //===- DirectoryWatcher-linux.cpp - Linux-platform directory watching -----===//
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
7 //===----------------------------------------------------------------------===//
9 #include "DirectoryScanner.h"
10 #include "clang/DirectoryWatcher/DirectoryWatcher.h"
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"
19 #include <condition_variable>
27 #include <sys/epoll.h>
28 #include <sys/inotify.h>
34 using namespace clang;
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.
41 struct 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
54 other.OwnsFDs = false;
61 llvm::sys::RetryAfterSignal(-1, write, FDWrite, "A", 1);
74 static llvm::Optional<SemaphorePipe> create() {
75 int InotifyPollingStopperFDs[2];
76 if (pipe2(InotifyPollingStopperFDs, O_CLOEXEC) == -1)
78 return SemaphorePipe(InotifyPollingStopperFDs);
82 /// Mutex-protected queue of Events.
85 std::condition_variable NonEmpty;
86 std::queue<DirectoryWatcher::Event> Events;
89 void push_back(const DirectoryWatcher::Event::EventKind K,
92 std::unique_lock<std::mutex> L(Mtx);
93 Events.emplace(K, Filename);
95 NonEmpty.notify_one();
98 // Blocks on caller thread and uses codition_variable to wait until there's an
100 DirectoryWatcher::Event pop_front_blocking() {
101 std::unique_lock<std::mutex> L(Mtx);
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();
110 NonEmpty.wait(L, [this]() { return !Events.empty(); });
115 class DirectoryWatcherLinux : public clang::DirectoryWatcher {
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);
123 ~DirectoryWatcherLinux() override {
125 InotifyPollingThread.join();
126 EventsReceivingThread.join();
127 inotify_rm_watch(InotifyFD, InotifyWD);
128 llvm::sys::RetryAfterSignal(-1, close, InotifyFD);
132 const std::string WatchedDirPath;
133 // inotify file descriptor
135 // inotify watch descriptor
140 // Make sure lifetime of Receiver fully contains lifetime of
141 // EventsReceivingThread.
142 std::function<void(llvm::ArrayRef<Event>, bool)> Receiver;
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;
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.
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
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();
166 // Stops all the async work. Reentrant.
168 Queue.push_back(DirectoryWatcher::Event::EventKind::WatcherGotInvalidated,
170 InotifyPollingStopSignal.signal();
174 void 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.
187 alignas(struct inotify_event) char buffer[EventBufferLength];
189 auto ManagedBuffer = std::make_unique<Buffer>();
190 char *const Buf = ManagedBuffer->buffer;
192 const int EpollFD = epoll_create1(EPOLL_CLOEXEC);
197 auto EpollFDGuard = llvm::make_scope_exit([EpollFD]() { close(EpollFD); });
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) {
207 EventSpec.data.fd = InotifyPollingStopSignal.FDRead;
208 if (epoll_ctl(EpollFD, EPOLL_CTL_ADD, InotifyPollingStopSignal.FDRead,
214 std::array<struct epoll_event, 2> EpollEventBuffer;
217 const int EpollWaitResult = llvm::sys::RetryAfterSignal(
218 -1, epoll_wait, EpollFD, EpollEventBuffer.data(),
219 EpollEventBuffer.size(), /*timeout=*/-1 /*== infinity*/);
220 if (EpollWaitResult == -1) {
225 // Multiple epoll_events can be received for a single file descriptor per
227 for (int i = 0; i < EpollWaitResult; ++i) {
228 if (EpollEventBuffer[i].data.fd == InotifyPollingStopSignal.FDRead) {
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,
238 for (char *P = Buf; P < Buf + NumRead;) {
239 if (P + sizeof(struct inotify_event) > Buf + NumRead) {
241 llvm_unreachable("an incomplete inotify_event was read");
245 struct inotify_event *Event = reinterpret_cast<struct inotify_event *>(P);
246 P += sizeof(struct inotify_event) + Event->len;
248 if (Event->mask & (IN_CREATE | IN_MODIFY | IN_MOVED_TO | IN_DELETE) &&
251 llvm_unreachable("expected a filename from inotify");
255 if (Event->mask & (IN_CREATE | IN_MOVED_TO | IN_MODIFY)) {
256 Queue.push_back(DirectoryWatcher::Event::EventKind::Modified,
258 } else if (Event->mask & (IN_DELETE | IN_MOVED_FROM)) {
259 Queue.push_back(DirectoryWatcher::Event::EventKind::Removed,
261 } else if (Event->mask & (IN_DELETE_SELF | IN_MOVE_SELF)) {
262 Queue.push_back(DirectoryWatcher::Event::EventKind::WatchedDirRemoved,
266 } else if (Event->mask & IN_IGNORED) {
271 llvm_unreachable("Unknown event type.");
278 void DirectoryWatcherLinux::InitialScan() {
279 this->Receiver(getAsFileEvents(scanDirectory(WatchedDirPath)),
283 void DirectoryWatcherLinux::EventReceivingLoop() {
285 DirectoryWatcher::Event Event = this->Queue.pop_front_blocking();
286 this->Receiver(Event, false);
288 DirectoryWatcher::Event::EventKind::WatcherGotInvalidated) {
295 DirectoryWatcherLinux::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)) {
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) {
310 EventsReceivingThread = std::thread([this]() { EventReceivingLoop(); });
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.
316 EventReceivingLoop();
323 llvm::Expected<std::unique_ptr<DirectoryWatcher>> clang::DirectoryWatcher::create(
325 std::function<void(llvm::ArrayRef<DirectoryWatcher::Event>, bool)> Receiver,
326 bool WaitForInitialSync) {
328 llvm::report_fatal_error(
329 "DirectoryWatcher::create can not accept an empty Path.");
331 const int InotifyFD = inotify_init1(IN_CLOEXEC);
333 return llvm::make_error<llvm::StringError>(
334 std::string("inotify_init1() error: ") + strerror(errno),
335 llvm::inconvertibleErrorCode());
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
346 return llvm::make_error<llvm::StringError>(
347 std::string("inotify_add_watch() error: ") + strerror(errno),
348 llvm::inconvertibleErrorCode());
350 auto InotifyPollingStopper = SemaphorePipe::create();
352 if (!InotifyPollingStopper)
353 return llvm::make_error<llvm::StringError>(
354 std::string("SemaphorePipe::create() error: ") + strerror(errno),
355 llvm::inconvertibleErrorCode());
357 return std::make_unique<DirectoryWatcherLinux>(
358 Path, Receiver, WaitForInitialSync, InotifyFD, InotifyWD,
359 std::move(*InotifyPollingStopper));