File indexing completed on 2024-12-08 12:44:38

 /*
     SPDX-FileCopyrightText: 2014 Daniel Vrátil <dvratil@redhat.com>
     SPDX-FileCopyrightText: 2016 Daniel Vrátil <dvratil@kde.org>
 
     SPDX-License-Identifier: LGPL-2.0-or-later
 */
 
 #ifndef FUTURE_H
 #define FUTURE_H
 
 #include "kasync_export.h"
 
 class QEventLoop;
 
 #include <type_traits>
 
 #include <QSharedDataPointer>
 #include <QPointer>
 #include <QVector>
 #include <QEventLoop>
 
 namespace KAsync {
 
 //@cond PRIVATE
 
 class FutureWatcherBase;
 template<typename T>
 class FutureWatcher;
 
 namespace Private {
 struct Execution;
 class ExecutorBase;
 
 typedef QSharedPointer<Execution> ExecutionPtr;
 } // namespace Private
 
 struct KASYNC_EXPORT Error
 {
     Error() : errorCode(0) {};
     explicit Error(const char *message) : errorCode(1), errorMessage(QString::fromLatin1(message)) {}
     Error(int code, const char *message) : errorCode(code), errorMessage(QString::fromLatin1(message)) {}
     Error(int code, const QString &message) : errorCode(code), errorMessage(message) {}
 
     bool operator ==(const Error &other) const {
         return (errorCode == other.errorCode) && (errorMessage == other.errorMessage);
     }
 
     bool operator !=(const Error &other) const {
         return !(*this == other);
     }
 
     operator bool() const {
         return (errorCode != 0);
     }
 
     int errorCode;
     QString errorMessage;
 private:
     //Disable all implicit conversions except to bool, to avoid accidentally implicitly casting an error to a continuation argument.
     //This becomes an issue if you forget to specify all template arguments, as the template argument deduction may employ a nonsensical implicit conversion from i.e. error to int. So as long as the Error object is used in the Job::then overload resolution no implicit conversions here.
     //Of course this "solution" still breaks if you forget the template argument  with a boolean parameter....
     template <typename T>
     operator T() const;
 };
 
 class KASYNC_EXPORT FutureBase
 {
     friend struct KAsync::Private::Execution;
     friend class FutureWatcherBase;
 
 public:
     virtual ~FutureBase();
 
 
     void setFinished();
     bool isFinished() const;
 
     void setError(int code = 1, const QString &message = QString());
     void setError(const Error &error);
     void addError(const Error &error);
     void clearErrors();
     bool hasError() const;
     int errorCode() const;
     QString errorMessage() const;
     QVector<Error> errors() const;
 
     void setProgress(qreal progress);
     void setProgress(int processed, int total);
 
 protected:
     class KASYNC_EXPORT PrivateBase : public QSharedData
     {
     public:
         explicit PrivateBase(const KAsync::Private::ExecutionPtr &execution);
         virtual ~PrivateBase();
 
         void releaseExecution();
 
         bool finished;
         QVector<Error> errors;
 
         QVector<QPointer<FutureWatcherBase>> watchers;
     private:
         QWeakPointer<KAsync::Private::Execution> mExecution;
     };
 
     explicit FutureBase();
     explicit FutureBase(FutureBase::PrivateBase *dd);
     FutureBase(const FutureBase &other);
     FutureBase &operator=(const FutureBase &other) = default;
 
     void addWatcher(KAsync::FutureWatcherBase *watcher);
     void releaseExecution();
 
 protected:
     QExplicitlySharedDataPointer<PrivateBase> d;
 };
 
 template<typename T>
 class FutureWatcher;
 
 template<typename T>
 class Future;
 
 template<typename T>
 class FutureGeneric : public FutureBase
 {
     friend class FutureWatcher<T>;
 
 public:
 
     void waitForFinished() const
     {
         if (isFinished()) {
             return;
         }
         FutureWatcher<T> watcher;
         QEventLoop eventLoop;
         QObject::connect(&watcher, &KAsync::FutureWatcher<T>::futureReady,
                          &eventLoop, &QEventLoop::quit);
         watcher.setFuture(*static_cast<const KAsync::Future<T>*>(this));
         eventLoop.exec();
     }
 
 protected:
     //@cond PRIVATE
     explicit FutureGeneric(const KAsync::Private::ExecutionPtr &execution)
         : FutureBase(new Private(execution))
     {}
 
     FutureGeneric(const FutureGeneric &) = default;
     FutureGeneric &operator=(const FutureGeneric &) = default;
 
 protected:
     class Private : public FutureBase::PrivateBase
     {
     public:
         explicit Private(const KAsync::Private::ExecutionPtr &execution)
             : FutureBase::PrivateBase(execution)
         {}
 
         std::conditional_t<std::is_void<T>::value, int /* dummy */, T> value;
     };
 };
 //@endcond
 
 
 
 /**
  * @ingroup Future
  *
  * @brief Future is a promise that is used by Job to deliver result
  * of an asynchronous execution.
  *
  * The Future is passed internally to each executed task, and the task can use
  * it to report its progress, result and notify when it is finished.
  *
  * Users use Future they receive from calling Job::exec() to get access
  * to the overall result of the execution. FutureWatcher&lt;T&gt; can be used
  * to wait for the Future to finish in non-blocking manner.
  *
  * @see Future<void>
  */
 template<typename T>
 class Future : public FutureGeneric<T>
 {
     //@cond PRIVATE
     friend class KAsync::Private::ExecutorBase;
 
     template<typename T_>
     friend class KAsync::FutureWatcher;
     //@endcond
 public:
     /**
      * @brief Constructor
      */
     explicit Future()
         : FutureGeneric<T>(KAsync::Private::ExecutionPtr())
     {}
 
     /**
      * @brief Copy constructor
      */
     Future(const Future<T> &other)
         : FutureGeneric<T>(other)
     {}
 
     /**
      * Set the result of the Future. This method is called by the task upon
      * calculating the result. After setting the value, the caller must also
      * call setFinished() to notify users that the result
      * is available.
      *
      * @warning This method must only be called by the tasks inside Job,
      * never by outside users.
      *
      * @param value The result value
      */
     void setValue(const T &value)
     {
         dataImpl()->value = value;
     }
 
     /**
      * Retrieve the result of the Future. Calling this method when the future has
      * not yet finished (i.e. isFinished() returns false)
      * returns undefined result.
      */
     T value() const
     {
         return dataImpl()->value;
     }
 
     T *operator->()
     {
         return &(dataImpl()->value);
     }
 
     const T *operator->() const
     {
         return &(dataImpl()->value);
     }
 
     T &operator*()
     {
         return dataImpl()->value;
     }
 
     const T &operator*() const
     {
         return dataImpl()->value;
     }
 
 #ifdef ONLY_DOXYGEN
     /**
      * Will block until the Future has finished.
      *
      * @note Internally this method is using a nested QEventLoop, which can
      * in some situation cause problems and deadlocks. It is recommended to use
      * FutureWatcher.
      *
      * @see isFinished()
      */
     void waitForFinished() const;
 
     /**
      * Marks the future as finished. This will cause all FutureWatcher&lt;T&gt;
      * objects watching this particular instance to emit FutureWatcher::futureReady()
      * signal, and will cause all callers currently blocked in Future::waitForFinished()
      * method of this particular instance to resume.
      *
      * @warning This method must only be called by the tasks inside Job,
      * never by outside users.
      *
      * @see isFinished()
      */
     void setFinished();
 
     /**
      * Query whether the Future has already finished.
      *
      * @see setFinished()
      */
     bool isFinished() const;
 
     /**
      * Used by tasks to report an error that happened during execution. If an
      * error handler was provided to the task, it will be executed with the
      * given arguments. Otherwise the error will be propagated to next task
      * that has an error handler, or all the way up to user.
      *
      * This method also internally calls setFinished()
      *
      * @warning This method must only be called by the tasks inside Job,
      * never by outside users.
      *
      * @param code Optional error code
      * @param message Optional error message
      *
      * @see errorCode(), errorMessage()
      */
     void setError(int code = 1, const QString &message = QString());
 
     /**
      * Returns error code set via setError() or 0 if no
      * error has occurred.
      *
      * @see setError(), errorMessage()
      */
     int errorCode() const;
 
     /**
      * Returns error message set via setError() or empty
      * string if no error occurred.
      *
      * @see setError(), errorCode()
      */
     QString errorMessage() const;
 
     /**
      * Sets progress of the task. All FutureWatcher instances watching
      * this particular future will then emit FutureWatcher::futureProgress()
      * signal.
      *
      * @param processed Already processed amount
      * @param total Total amount to process
      */
     void setProgress(int processed, int total);
 
     /**
      * Sets progress of the task.
      *
      * @param progress Progress
      */
     void setProgress(qreal progress);
 
 #endif // ONLY_DOXYGEN
     void setResult(const T &value)
     {
         dataImpl()->value = value;
         FutureBase::setFinished();
     }
 
 protected:
     //@cond PRIVATE
     Future(const KAsync::Private::ExecutionPtr &execution)
         : FutureGeneric<T>(execution)
     {}
     //@endcond
 
 private:
     inline auto dataImpl()
     {
         return static_cast<typename FutureGeneric<T>::Private*>(this->d.data());
     }
 
     inline auto dataImpl() const
     {
         return static_cast<typename FutureGeneric<T>::Private*>(this->d.data());
     }
 };
 
 /**
  * @ingroup Future
  *
  * @brief A specialization of Future&lt;T&gt; for tasks that have no (void)
  * result.
  *
  * Unlike the generic Future&lt;T&gt; this specialization does not have
  * setValue() and value() methods to set/retrieve result.
  *
  * @see Future
  */
 template<>
 class Future<void> : public FutureGeneric<void>
 {
     friend class KAsync::Private::ExecutorBase;
 
 public:
     /**
      * @brief Constructor
      */
     Future()
         : FutureGeneric<void>(KAsync::Private::ExecutionPtr())
     {}
 
 protected:
     //@cond PRIVATE
     Future(const KAsync::Private::ExecutionPtr &execution)
         : FutureGeneric<void>(execution)
     {}
     //@endcond
 };
 
 
 
 
 //@cond PRIVATE
 class KASYNC_EXPORT FutureWatcherBase : public QObject
 {
     Q_OBJECT
 
     friend class FutureBase;
 
 Q_SIGNALS:
     void futureReady();
     void futureProgress(qreal progress);
 
 protected:
     FutureWatcherBase(QObject *parent = nullptr);
 
     virtual ~FutureWatcherBase();
 
     void futureReadyCallback();
     void futureProgressCallback(qreal progress);
 
     void setFutureImpl(const KAsync::FutureBase &future);
 
 protected:
     class Private {
     public:
         KAsync::FutureBase future;
     };
 
     Private * const d;
 
 private:
     Q_DISABLE_COPY(FutureWatcherBase)
 };
 //@endcond
 
 
 /**
  * @ingroup Future
  *
  * @brief The FutureWatcher allows monitoring of Job results using
  * signals and slots.
  *
  * FutureWatcher is returned by Job upon execution. User can then
  * connect to its futureReady() and futureProgress() signals to be notified
  * about progress of the asynchronous job. When futureReady() signal is emitted,
  * the result of the job is available in Future::value().
  */
 template<typename T>
 class FutureWatcher : public FutureWatcherBase
 {
     //@cond PRIVATE
     friend class KAsync::FutureGeneric<T>;
     //@endcond
 
 public:
     /**
      * Constructs a new FutureWatcher that can watch for status of Future&lt;T&gt;
      */
     FutureWatcher(QObject *parent = nullptr)
         : FutureWatcherBase(parent)
     {}
 
     ~FutureWatcher()
     {}
 
     /**
      * Set future to watch.
      *
      * @param future Future object to watch
      */
     void setFuture(const KAsync::Future<T> &future)
     {
         setFutureImpl(*static_cast<const KAsync::FutureBase*>(&future));
     }
 
     /**
      * Returns currently watched future.
      */
     KAsync::Future<T> future() const
     {
         return *static_cast<KAsync::Future<T>*>(&d->future);
     }
 
 #ifdef ONLY_DOXYGEN
 Q_SIGNALS:
     /**
      * The signal is emitted when the execution has finished and the result
      * can be collected.
      *
      * @see Future::setFinished(), Future::setError()
      */
     void futureReady();
 
     /**
      * The signal is emitted when progress of the execution changes. This has
      * to be explicitly supported by the job being executed, otherwise the
      * signal is not emitted.
      *
      * @see Future::setProgress()
      */
     void futureProgress(qreal progress);
 #endif
 
 private:
     FutureWatcher(const FutureWatcher<T> &) = delete;
     FutureWatcher &operator=(const FutureWatcher<T> &) = delete;
 };
 
 } // namespace Async
 
 KASYNC_EXPORT QDebug& operator<<(QDebug &dbg, const KAsync::Error &error);
 
 #endif // FUTURE_H