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 <KDiskFreeSpaceInfo>
  24
  25 #include <QObject>
  26
  27 /**
  28  * A MountPointObserver can be used to determine the free space on a mount
  29  * point. It will then check the free space periodically, and emit the signal
  30  * spaceInfoChanged() if the return value of spaceInfo() has changed.
  31  *
  32  * Since multiple users which watch paths on the same mount point can share
  33  * a MountPointObserver, it is not possible to create a MountPointObserver
  34  * manually. Instead, the function observerForPath(QString&) should be called,
  35  * which returns either an existing or a newly created MountPointObserver for
  36  * the mount point where the path is mounted. observerForPath(QString&) looks
  37  * for a suitable MountPointObserver in an internal cache and creates new
  38  * MountPointObservers and adds them to the cache if necessary.
  39  *
  40  * Reference counting is used to keep track of the number of users, and to
  41  * decide when the object can be deleted. A user of this class should call
  42  * the method ref() when it starts using it, and deref() when it does not need
  43  * the MountPointObserver any more.
  44  *
  45  * The object will not be deleted immediately if the reference count reaches
  46  * zero. The object will only be destroyed when the next periodic update of
  47  * the free space information happens, and the reference count is still zero.
  48  * This approach makes it possible to re-use the object if a new user requests
  49  * the free space for the same mount point before the next update.
  50  */
  51 class MountPointObserver : public QObject
  52 {
  53     Q_OBJECT
  54
  55     explicit MountPointObserver(const QString& mountPoint, QObject* parent = 0);
  56     virtual ~MountPointObserver() {}
  57
  58 public:
  59     /**
  60      * Obtains information about the available space on the observed mount point.
  61      */
  62     KDiskFreeSpaceInfo spaceInfo() const { return m_spaceInfo; }
  63
  64     /**
  65      * Call this function to indicate that the caller intends to continue using this object. An
  66      * internal reference count is increased then. When the observer is not needed any more,
  67      * deref() should be called, which decreases the reference count again.
  68      */
  69     void ref() { ++m_referenceCount; }
  70
  71     /**
  72      * This function can be used to indicate that the caller does not need this MountPointObserver
  73      * any more. Internally, a reference count is decreased. If the reference count is zero while
  74      * update() is called, the object deletes itself.
  75      */
  76     void deref()
  77     {
  78         --m_referenceCount;
  79         Q_ASSERT(m_referenceCount >= 0);
  80     }
  81
  82     /**
  83      * Returns a MountPointObserver for the given \a path. If the caller intends to continue using
  84      * the returned object, it must call its ref() method.
  85      */
  86     static MountPointObserver* observerForPath(const QString& path);
  87
  88 signals:
  89     /**
  90      * This signal is emitted if the information that spaceInfo() will return has changed.
  91      */
  92     void spaceInfoChanged();
  93
  94 public slots:
  95     /**
  96      * If this slot is invoked, MountPointObserver checks if the available space on the observed
  97      * mount point has changed, and emits spaceInfoChanged() if that is the case.
  98      */
  99     void update();
 100
 101 private:
 102     const QString m_mountPoint;
 103     int m_referenceCount;
 104     KDiskFreeSpaceInfo m_spaceInfo;
 105
 106     friend class MountPointObserverCache;
 107 };
 108
 109 #endif