src/statusbar/mountpointobserver.h

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