FileSystemWatcher Class | Extending Qt Creator Manual

Extending Qt Creator Manual | FileSystemWatcher

Extending Qt Creator Manual 4.6.0

# FileSystemWatcher Class

(Utils::FileSystemWatcher)

The FileSystemWatcher class is a file watcher that internally uses a centralized QFileSystemWatcher and enforces limits on Mac OS. More...

Header: | #include <FileSystemWatcher>

- List of all members, including inherited members

## Public Types

enum | WatchMode { WatchModifiedDate, WatchAllChanges }

## Public Functions

| FileSystemWatcher(QObject *parent = 0)
| FileSystemWatcher(int id, QObject *parent = 0)
virtual | ~FileSystemWatcher()
void | addDirectories(const QStringList &files, WatchMode wm)
void | addDirectory(const QString &file, WatchMode wm)
void | addFile(const QString &file, WatchMode wm)
void | addFiles(const QStringList &files, WatchMode wm)
QStringList | directories() const
QStringList | files() const
void | removeDirectories(const QStringList &files)
void | removeDirectory(const QString &file)
void | removeFile(const QString &file)
void | removeFiles(const QStringList &files)
bool | watchesDirectory(const QString &file) const
bool | watchesFile(const QString &file) const

## Signals

void | directoryChanged(const QString &path)
void | fileChanged(const QString &path)

## Detailed Description

The FileSystemWatcher class is a file watcher that internally uses a centralized QFileSystemWatcher and enforces limits on Mac OS.

### Design Considerations

Constructing/Destructing a QFileSystemWatcher is expensive. This can be worked around by using a centralized watcher.

Note: It is (still) possible to create several instances of a QFileSystemWatcher by passing an (arbitrary) integer id != 0 to the constructor. This allows separating watchers that easily exceed operating system limits from others (see below).

### Mac OS Specifics

There is a hard limit on the number of file handles that can be open at one point per process on Mac OS X (e.g. it is 2560 on Mac OS X Snow Leopard Server, as shown by `ulimit -a`). Opening one or several `.qmlproject`'s with a large number of directories to watch easily exceeds this. The results are crashes later on, e.g. when threads cannot be created any more.

This class implements a heuristic that the file system watcher used for `.qmlproject` files never uses more than half the number of available file handles. It also increases the number from `rlim_cur` to `rlim_max` - the old code in main.cpp failed, see last section in

http://developer.apple.com/library/mac/#documentation/Darwin/Reference/ManPages/man2/setrlimit.2.html

for details.

## Member Type Documentation

### enum FileSystemWatcher::WatchMode

## Member Function Documentation

### FileSystemWatcher::FileSystemWatcher(QObject *parent = 0)

Adds directories to watcher 0.

### FileSystemWatcher::FileSystemWatcher(int id, QObject *parent = 0)

Adds directories to a watcher with the specified id.

### `[virtual]` FileSystemWatcher::~FileSystemWatcher()

Destroys the instance of FileSystemWatcher. The destructor is virtual.

### void FileSystemWatcher::addDirectories(const QStringList &files, WatchMode wm)

### void FileSystemWatcher::addDirectory(const QString &file, WatchMode wm)

### void FileSystemWatcher::addFile(const QString &file, WatchMode wm)

### void FileSystemWatcher::addFiles(const QStringList &files, WatchMode wm)

### QStringList FileSystemWatcher::directories() const

### `[signal]` void FileSystemWatcher::directoryChanged(const QString &path)

### `[signal]` void FileSystemWatcher::fileChanged(const QString &path)

### QStringList FileSystemWatcher::files() const

### void FileSystemWatcher::removeDirectories(const QStringList &files)

### void FileSystemWatcher::removeDirectory(const QString &file)

### void FileSystemWatcher::removeFile(const QString &file)

### void FileSystemWatcher::removeFiles(const QStringList &files)

### bool FileSystemWatcher::watchesDirectory(const QString &file) const

### bool FileSystemWatcher::watchesFile(const QString &file) const