src/statusbar/mountpointobserver.h

   1 /***************************************************************************
   2  *   Copyright (C) 2014 by Frank Reininghaus <frank78ac@googlemail.com>    *
   3  *                                                                         *
   4  *   This program is free software; you can redistribute it and/or modify  *
   5  *   it under the terms of the GNU General Public License as published by  *
   6  *   the Free Software Foundation; either version 2 of the License, or     *
   7  *   (at your option) any later version.                                   *
   8  *                                                                         *
   9  *   This program is distributed in the hope that it will be useful,       *
  10  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  11  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  12  *   GNU General Public License for more details.                          *
  13  *                                                                         *
  14  *   You should have received a copy of the GNU General Public License     *
  15  *   along with this program; if not, write to the                         *
  16  *   Free Software Foundation, Inc.,                                       *
  17  *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA          *
  18  ***************************************************************************/
  19
  20 #ifndef MOUNTPOINTOBSERVER_H
  21 #define MOUNTPOINTOBSERVER_H
  22
  23 #include <KIO/Job>
  24
  25 #include <QObject>
  26 #include <QUrl>
  27
  28 /**
  29  * A MountPointObserver can be used to determine the free space on a mount
  30  * point. It will then check the free space periodically, and emit the signal
  31  * spaceInfoChanged() if the return value of spaceInfo() has changed.
  32  *
  33  * Since multiple users which watch paths on the same mount point can share
  34  * a MountPointObserver, it is not possible to create a MountPointObserver
  35  * manually. Instead, the function observerForPath(QString&) should be called,
  36  * which returns either an existing or a newly created MountPointObserver for
  37  * the mount point where the path is mounted. observerForPath(QString&) looks
  38  * for a suitable MountPointObserver in an internal cache and creates new
  39  * MountPointObservers and adds them to the cache if necessary.
  40  *
  41  * Reference counting is used to keep track of the number of users, and to
  42  * decide when the object can be deleted. A user of this class should call
  43  * the method ref() when it starts using it, and deref() when it does not need
  44  * the MountPointObserver any more.
  45  *
  46  * The object will not be deleted immediately if the reference count reaches
  47  * zero. The object will only be destroyed when the next periodic update of
  48  * the free space information happens, and the reference count is still zero.
  49  * This approach makes it possible to re-use the object if a new user requests
  50  * the free space for the same mount point before the next update.
  51  */
  52 class MountPointObserver : public QObject
  53 {
  54     Q_OBJECT
  55
  56     explicit MountPointObserver(const QUrl& url, QObject* parent = 0);
  57     ~MountPointObserver() override {}
  58
  59 public:
  60     /**
  61      * Call this function to indicate that the caller intends to continue using this object. An
  62      * internal reference count is increased then. When the observer is not needed any more,
  63      * deref() should be called, which decreases the reference count again.
  64      */
  65     void ref() { ++m_referenceCount; }
  66
  67     /**
  68      * This function can be used to indicate that the caller does not need this MountPointObserver
  69      * any more. Internally, a reference count is decreased. If the reference count is zero while
  70      * update() is called, the object deletes itself.
  71      */
  72     void deref()
  73     {
  74         --m_referenceCount;
  75         Q_ASSERT(m_referenceCount >= 0);
  76     }
  77
  78     /**
  79      * Returns a MountPointObserver for the given \a url. If the caller intends to continue using
  80      * the returned object, it must call its ref() method.
  81      */
  82     static MountPointObserver* observerForUrl(const QUrl& url);
  83
  84 signals:
  85     /**
  86      * This signal is emitted when the size has been retrieved.
  87      */
  88     void spaceInfoChanged(quint64 size, quint64 available);
  89
  90 public slots:
  91     /**
  92      * If this slot is invoked, MountPointObserver starts a new driveSize job
  93      * to get the drive's size.
  94      */
  95     void update();
  96
  97 private slots:
  98     void freeSpaceResult(KIO::Job* job, KIO::filesize_t size, KIO::filesize_t available);
  99
 100 private:
 101     const QUrl m_url;
 102     int m_referenceCount;
 103
 104     friend class MountPointObserverCache;
 105 };
 106
 107 #endif