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 public:
  47     /**
  48      * Call this function to indicate that the caller intends to continue using this object. An
  49      * internal reference count is increased then. When the observer is not needed any more,
  50      * deref() should be called, which decreases the reference count again.
  51      */
  52     void ref() { ++m_referenceCount; }
  53
  54     /**
  55      * This function can be used to indicate that the caller does not need this MountPointObserver
  56      * any more. Internally, a reference count is decreased. If the reference count is zero while
  57      * update() is called, the object deletes itself.
  58      */
  59     void deref()
  60     {
  61         --m_referenceCount;
  62         Q_ASSERT(m_referenceCount >= 0);
  63     }
  64
  65     /**
  66      * Returns a MountPointObserver for the given \a url. If the caller intends to continue using
  67      * the returned object, it must call its ref() method.
  68      */
  69     static MountPointObserver* observerForUrl(const QUrl& url);
  70
  71 signals:
  72     /**
  73      * This signal is emitted when the size has been retrieved.
  74      */
  75     void spaceInfoChanged(quint64 size, quint64 available);
  76
  77 public slots:
  78     /**
  79      * If this slot is invoked, MountPointObserver starts a new driveSize job
  80      * to get the drive's size.
  81      */
  82     void update();
  83
  84 private slots:
  85     void freeSpaceResult(KIO::Job* job, KIO::filesize_t size, KIO::filesize_t available);
  86
  87 private:
  88     const QUrl m_url;
  89     int m_referenceCount;
  90
  91     friend class MountPointObserverCache;
  92 };
  93
  94 #endif