File indexing completed on 2024-12-01 03:40:45

0001 // -*- c++ -*-
0002 /*
0003     This file is part of the KDE libraries
0004     SPDX-FileCopyrightText: 2000 Stephan Kulow <coolo@kde.org>
0005     SPDX-FileCopyrightText: 2000 Waldo Bastian <bastian@kde.org>
0006 
0007     SPDX-License-Identifier: LGPL-2.0-or-later
0008 */
0009 
0010 #ifndef _kio_scheduler_h
0011 #define _kio_scheduler_h
0012 
0013 #include "simplejob.h"
0014 #include <QMap>
0015 #include <QTimer>
0016 
0017 namespace KIO
0018 {
0019 class Worker;
0020 
0021 class SchedulerPrivate;
0022 /*
0023  *
0024  * The KIO::Scheduler manages KIO workers for the application.
0025  * It also queues jobs and assigns the job to a worker when one
0026  * becomes available.
0027  *
0028  * There are two possible ways for a job to get a worker:
0029  *
0030  * <h3>1. Direct</h3>
0031  * This is the default. When you create a job the
0032  * KIO::Scheduler will be notified and will find either an existing
0033  * worker that is idle or it will create a new worker for the job.
0034  *
0035  *
0036  * <h3>2. Scheduled</h3>
0037  * If you create a lot of jobs, you might want not want to have a
0038  * worker for each job. If you schedule a job, a maximum number
0039  * of workers will be created. When more jobs arrive, they will be
0040  * queued. When a worker is finished with a job, it will be assigned
0041  * a job from the queue.
0042  *
0043  * @see KIO::Job
0044  */
0045 class Scheduler : public QObject
0046 {
0047     Q_OBJECT
0048     Q_CLASSINFO("D-Bus Interface", "org.kde.KIO.Scheduler")
0049 public:
0050     /**
0051      * Register @p job with the scheduler.
0052      * The default is to create a new worker for the job if no worker
0053      * is available. This can be changed by calling setJobPriority.
0054      * @param job the job to register
0055      */
0056     static void doJob(SimpleJob *job);
0057 
0058     /**
0059      * Stop the execution of a job.
0060      * @param job the job to cancel
0061      */
0062     static void cancelJob(SimpleJob *job);
0063 
0064     /**
0065      * Called when a job is done.
0066      * @param job the finished job
0067      * @param worker the worker that executed the @p job
0068      */
0069     static void jobFinished(KIO::SimpleJob *job, KIO::Worker *worker);
0070 
0071     /**
0072      * Puts a worker on notice. A next job may reuse this worker if it
0073      * requests the same URL.
0074      *
0075      * A job can be put on hold after it has emit'ed its mimetype() signal.
0076      * Based on the MIME type, the program can give control to another
0077      * component in the same process which can then resume the job
0078      * by simply asking for the same URL again.
0079      * @param job the job that should be stopped
0080      * @param url the URL that is handled by the @p url
0081      *
0082      * @since 5.101
0083      */
0084     static void putWorkerOnHold(KIO::SimpleJob *job, const QUrl &url);
0085 
0086     /**
0087      * Removes any worker that might have been put on hold. If a worker
0088      * was put on hold it will be killed.
0089      *
0090      * @since 5.101
0091      */
0092     static void removeWorkerOnHold();
0093 
0094     static void emitReparseSlaveConfiguration();
0095     // KF6 TODO: rename to emitReparseWorkerConfiguration. See also T15956.
0096 
0097     /**
0098      * Returns true if there is a worker on hold for @p url.
0099      *
0100      * @since 5.101
0101      */
0102     static bool isWorkerOnHoldFor(const QUrl &url);
0103 
0104     /**
0105      * Updates the internal metadata from job.
0106      *
0107      * @since 4.6.5
0108      */
0109     static void updateInternalMetaData(SimpleJob *job);
0110 
0111 Q_SIGNALS:
0112 
0113     // DBUS
0114     Q_SCRIPTABLE void reparseSlaveConfiguration(const QString &);
0115     // KF6 TODO: rename to reparseWorkerConfiguration. See also T15956.
0116 
0117 private:
0118     Q_DISABLE_COPY(Scheduler)
0119     KIOCORE_NO_EXPORT Scheduler();
0120     KIOCORE_NO_EXPORT ~Scheduler() override;
0121 
0122     KIOCORE_NO_EXPORT static Scheduler *self();
0123 
0124     // connected to D-Bus signal:
0125 #ifndef KIO_ANDROID_STUB
0126     Q_PRIVATE_SLOT(d_func(), void slotReparseSlaveConfiguration(const QString &, const QDBusMessage &))
0127 #endif
0128 
0129 private:
0130     friend class SchedulerPrivate;
0131     KIOCORE_NO_EXPORT SchedulerPrivate *d_func();
0132 };
0133 
0134 }
0135 #endif