src/support/FileMonitor.h

   1 // -*- C++ -*-
   2 /**
   3  * \file FileMonitor.h
   4  * This file is part of LyX, the document processor.
   5  * Licence details can be found in the file COPYING.
   6  *
   7  * \author Angus Leeming
   8  * \author Guillaume Munch
   9  *
  10  * Full author contact details are available in file CREDITS.
  11  *
  12  * FileMonitor monitors a file and informs a listener when that file has
  13  * changed.
  14  */
  15
  16 #ifndef FILEMONITOR_H
  17 #define FILEMONITOR_H
  18
  19 #include "support/FileName.h"
  20 #include "support/signals.h"
  21
  22 #include <memory>
  23
  24 #include <QFileSystemWatcher>
  25 #include <QObject>
  26 #include <QPointer>
  27
  28
  29 namespace lyx {
  30 namespace support {
  31
  32 ///
  33 ///  FileMonitor, a file monitor based on QFileSystemWatcher
  34 ///
  35
  36 class FileMonitor;
  37 class ActiveFileMonitor;
  38 class FileMonitorGuard;
  39 typedef std::unique_ptr<FileMonitor> FileMonitorPtr;
  40 typedef std::unique_ptr<ActiveFileMonitor> ActiveFileMonitorPtr;
  41
  42 ///
  43 /// Watch a file:
  44 ///   FileMonitorPtr monitor = FileSystemWatcher::monitor(file_with_path);
  45 ///   monitor.connect(...); //(using boost::signals2), or:
  46 ///   connect(monitor, SIGNAL(fileChanged()),...); // (using Qt)
  47 ///
  48 /// Remember that a unique_ptr is automatically deleted at the end of a scope if
  49 /// it has not been moved, or when assigned. When that happens, the signal
  50 /// object is deleted and therefore all the connections are closed. The file
  51 /// ceases being tracked when all the monitors for a file have been deleted.
  52 ///
  53 /// Stop watching:
  54 ///   * as determined statically by the scope, or
  55 ///   * dynamically, using:
  56 ///       monitor = nullptr;
  57 ///
  58 /// Watch a different file:
  59 ///   monitor = FileSystemWatcher::monitor(file_with_path2);
  60 ///   monitor.connect(...);
  61 /// (stops watching the first)
  62 ///
  63 /// Block notifications for the duration of a scope:
  64 ///   {
  65 ///       FileMonitorBlocker block = monitor.block();
  66 ///       ...
  67 ///   }
  68 ///
  69 /// Reset connections:
  70 ///   monitor.disconnect();
  71 ///   or the disconnect method of the connection object for the boost signal.
  72 ///
  73 class FileSystemWatcher
  74 {
  75 public:
  76         /// as described above
  77         static FileMonitorPtr monitor(FileName const & filename);
  78         /// same but with an ActiveFileMonitor
  79         static ActiveFileMonitorPtr activeMonitor(FileName const & filename,
  80                                                   int interval = 10000);
  81         /// Output whether the paths tracked by qwatcher_ and the active
  82         /// FileMonitorGuards are in correspondence.
  83         static void debug();
  84 private:
  85         FileSystemWatcher();
  86         /// A global instance is created automatically on first call
  87         static FileSystemWatcher & instance();
  88         ///
  89         std::shared_ptr<FileMonitorGuard> getGuard(FileName const & filename);
  90         /// Caches the monitor guards but allow them to be destroyed
  91         std::map<std::string, std::weak_ptr<FileMonitorGuard>> store_;
  92         /// This class is a wrapper for QFileSystemWatcher
  93         std::unique_ptr<QFileSystemWatcher> const qwatcher_;
  94 };
  95
  96
  97 /// Must be unique per path
  98 /// Ends the watch when deleted
  99 class FileMonitorGuard : public QObject
 100 {
 101         Q_OBJECT
 102
 103 public:
 104         /// Start the watch
 105         FileMonitorGuard(std::string const & filename,
 106                          QFileSystemWatcher * qwatcher);
 107         /// End the watch
 108         ~FileMonitorGuard();
 109         /// absolute path being tracked
 110         std::string const & filename() { return filename_; }
 111         /// if false, emit fileChanged() when we notice the existence of the file
 112         void setExists(bool exists) { exists_ = exists; }
 113
 114 public Q_SLOTS:
 115         /// Make sure it is being monitored, after e.g. a deletion. See
 116         /// <https://bugreports.qt.io/browse/QTBUG-46483>. This is called
 117         /// automatically.
 118         void refresh();
 119
 120 Q_SIGNALS:
 121         /// Connect to this to be notified when the file changes
 122         void fileChanged() const;
 123
 124 private Q_SLOTS:
 125         /// Receive notifications from the QFileSystemWatcher
 126         void notifyChange(QString const & path);
 127
 128 private:
 129         std::string const filename_;
 130         QFileSystemWatcher * qwatcher_;
 131         bool exists_;
 132 };
 133
 134
 135 class FileMonitorBlockerGuard : public QObject
 136 {
 137         Q_OBJECT
 138         QPointer<FileMonitor> monitor_;
 139         int delay_;
 140
 141 public:
 142         FileMonitorBlockerGuard(FileMonitor * monitor);
 143         ~FileMonitorBlockerGuard();
 144         void setDelay(int delay);
 145 };
 146
 147
 148 typedef std::shared_ptr<FileMonitorBlockerGuard> FileMonitorBlocker;
 149
 150
 151 /// Main class
 152 class FileMonitor : public QObject
 153 {
 154         Q_OBJECT
 155         friend class FileMonitorBlockerGuard;
 156
 157 public:
 158         FileMonitor(std::shared_ptr<FileMonitorGuard> monitor);
 159
 160         typedef signals2::signal<void()> sig;
 161         typedef sig::slot_type slot;
 162         /// Connect and you'll be informed when the file has changed.
 163         signals2::connection connect(slot const &);
 164         /// disconnect all slots connected to the boost signal fileChanged_ or to
 165         /// the qt signal fileChanged()
 166         void disconnect();
 167         /// absolute path being tracked
 168         std::string const & filename() { return monitor_->filename(); }
 169         /// Creates a guard that blocks notifications. Copyable. Notifications from
 170         /// this monitor are blocked as long as there are copies around.
 171         /// \param delay is the amount waited in ms after expiration of the guard
 172         /// before reconnecting. This delay thing is to deal with asynchronous
 173         /// notifications in a not so elegant fashion. But it can also be used to
 174         /// slow down incoming events.
 175         FileMonitorBlocker block(int delay = 0);
 176         /// Make sure the good file is being monitored, after e.g. a move or a
 177         /// deletion. See <https://bugreports.qt.io/browse/QTBUG-46483>. This is
 178         /// called automatically.
 179         void refresh() { monitor_->refresh(); }
 180
 181 Q_SIGNALS:
 182         /// Connect to this to be notified when the file changes
 183         void fileChanged() const;
 184
 185 protected Q_SLOTS:
 186         /// Receive notifications from the FileMonitorGuard
 187         void changed();
 188         ///
 189         void reconnectToFileMonitorGuard();
 190
 191 private:
 192         /// boost signal
 193         sig fileChanged_;
 194         /// the unique watch for our file
 195         std::shared_ptr<FileMonitorGuard> const monitor_;
 196         ///
 197         std::weak_ptr<FileMonitorBlockerGuard> blocker_;
 198 };
 199
 200
 201 /// When a more active monitoring style is needed.
 202 /// For instance because QFileSystemWatcher does not work for remote file
 203 /// systems.
 204 class ActiveFileMonitor : public FileMonitor
 205 {
 206         Q_OBJECT
 207 public:
 208         ActiveFileMonitor(std::shared_ptr<FileMonitorGuard> monitor,
 209                           FileName const & filename, int interval);
 210         /// call checkModified asynchronously
 211         void checkModifiedAsync();
 212
 213 public Q_SLOTS:
 214         /// Check explicitly for a modification, but not more than once every
 215         /// interval ms.
 216         void checkModified();
 217
 218 private Q_SLOTS:
 219         void setCooldown() { cooldown_ = true; }
 220         void clearCooldown() { cooldown_ = false; }
 221
 222 private:
 223         FileName const filename_;
 224         ///
 225         int const interval_;
 226         ///
 227         time_t timestamp_;
 228         ///
 229         unsigned long checksum_;
 230         ///
 231         bool cooldown_;
 232 };
 233
 234
 235 } // namespace support
 236 } // namespace lyx
 237
 238 #endif // FILEMONITOR_H