+/***************************************************************************
+ * Copyright (C) 2014 by Frank Reininghaus <frank78ac@googlemail.com> *
+ * *
+ * This program is free software; you can redistribute it and/or modify *
+ * it under the terms of the GNU General Public License as published by *
+ * the Free Software Foundation; either version 2 of the License, or *
+ * (at your option) any later version. *
+ * *
+ * This program is distributed in the hope that it will be useful, *
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of *
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
+ * GNU General Public License for more details. *
+ * *
+ * You should have received a copy of the GNU General Public License *
+ * along with this program; if not, write to the *
+ * Free Software Foundation, Inc., *
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA *
+ ***************************************************************************/
+
+#ifndef MOUNTPOINTOBSERVER_H
+#define MOUNTPOINTOBSERVER_H
+
+#include <KDiskFreeSpaceInfo>
+
+#include <QObject>
+
+/**
+ * A MountPointObserver can be used to determine the free space on a mount
+ * point. It will then check the free space periodically, and emit the signal
+ * spaceInfoChanged() if the return value of spaceInfo() has changed.
+ *
+ * Since multiple users which watch paths on the same mount point can share
+ * a MountPointObserver, it is not possible to create a MountPointObserver
+ * manually. Instead, the function observerForPath(QString&) should be called,
+ * which returns either an existing or a newly created MountPointObserver for
+ * the mount point where the path is mounted. observerForPath(QString&) looks
+ * for a suitable MountPointObserver in an internal cache and creates new
+ * MountPointObservers and adds them to the cache if necessary.
+ *
+ * Reference counting is used to keep track of the number of users, and to
+ * decide when the object can be deleted. A user of this class should call
+ * the method ref() when it starts using it, and deref() when it does not need
+ * the MountPointObserver any more.
+ *
+ * The object will not be deleted immediately if the reference count reaches
+ * zero. The object will only be destroyed when the next periodic update of
+ * the free space information happens, and the reference count is still zero.
+ * This approach makes it possible to re-use the object if a new user requests
+ * the free space for the same mount point before the next update.
+ */
+class MountPointObserver : public QObject
+{
+ Q_OBJECT
+
+ explicit MountPointObserver(const QString& mountPoint, QObject* parent = 0);
+ virtual ~MountPointObserver() {}
+
+public:
+ /**
+ * Obtains information about the available space on the observed mount point.
+ */
+ KDiskFreeSpaceInfo spaceInfo() const { return m_spaceInfo; }
+
+ /**
+ * Call this function to indicate that the caller intends to continue using this object. An
+ * internal reference count is increased then. When the observer is not needed any more,
+ * deref() should be called, which decreases the reference count again.
+ */
+ void ref() { ++m_referenceCount; }
+
+ /**
+ * This function can be used to indicate that the caller does not need this MountPointObserver
+ * any more. Internally, a reference count is decreased. If the reference count is zero while
+ * update() is called, the object deletes itself.
+ */
+ void deref()
+ {
+ --m_referenceCount;
+ Q_ASSERT(m_referenceCount >= 0);
+ }
+
+ /**
+ * Returns a MountPointObserver for the given \a path. If the caller intends to continue using
+ * the returned object, it must call its ref() method.
+ */
+ static MountPointObserver* observerForPath(const QString& path);
+
+signals:
+ /**
+ * This signal is emitted if the information that spaceInfo() will return has changed.
+ */
+ void spaceInfoChanged();
+
+public slots:
+ /**
+ * If this slot is invoked, MountPointObserver checks if the available space on the observed
+ * mount point has changed, and emits spaceInfoChanged() if that is the case.
+ */
+ void update();
+
+private:
+ const QString m_mountPoint;
+ int m_referenceCount;
+ KDiskFreeSpaceInfo m_spaceInfo;
+
+ friend class MountPointObserverCache;
+};
+
+#endif
projects / dolphin.git / commitdiff