home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kio / scheduler.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  12.8 KB  |  365 lines
  1. // -*- c++ -*-
  2. /* This file is part of the KDE libraries
  3.     Copyright (C) 2000 Stephan Kulow <coolo@kde.org>
  4.                        Waldo Bastian <bastian@kde.org>
  5.  
  6.     This library is free software; you can redistribute it and/or
  7.     modify it under the terms of the GNU Library General Public
  8.     License as published by the Free Software Foundation; either
  9.     version 2 of the License, or (at your option) any later version.
  10.  
  11.     This library is distributed in the hope that it will be useful,
  12.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  13.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14.     Library General Public License for more details.
  15.  
  16.     You should have received a copy of the GNU Library General Public License
  17.     along with this library; see the file COPYING.LIB.  If not, write to
  18.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  19.     Boston, MA 02110-1301, USA.
  20. */
  21.  
  22. #ifndef _kio_scheduler_h
  23. #define _kio_scheduler_h
  24.  
  25. #include "kio/job.h"
  26. #include "kio/jobclasses.h"
  27. #include <qtimer.h>
  28. #include <qptrdict.h>
  29. #include <qmap.h>
  30.  
  31. #include <dcopobject.h>
  32.  
  33. namespace KIO {
  34.  
  35.     class Slave;
  36.     class SlaveList;
  37.     class SlaveConfig;
  38.     class SessionData;
  39.  
  40.     /**
  41.      * The KIO::Scheduler manages io-slaves for the application.
  42.      * It also queues jobs and assigns the job to a slave when one
  43.      * becomes available.
  44.      *
  45.      * There are 3 possible ways for a job to get a slave:
  46.      *
  47.      * <h3>1. Direct</h3>
  48.      * This is the default. When you create a job the
  49.      * KIO::Scheduler will be notified and will find either an existing
  50.      * slave that is idle or it will create a new slave for the job.
  51.      *
  52.      * Example:
  53.      * \code
  54.      *    TransferJob *job = KIO::get(KURL("http://www.kde.org"));
  55.      * \endcode
  56.      *
  57.      *
  58.      * <h3>2. Scheduled</h3>
  59.      * If you create a lot of jobs, you might want not want to have a
  60.      * slave for each job. If you schedule a job, a maximum number
  61.      * of slaves will be created. When more jobs arrive, they will be
  62.      * queued. When a slave is finished with a job, it will be assigned
  63.      * a job from the queue.
  64.      *
  65.      * Example:
  66.      * \code
  67.      *    TransferJob *job = KIO::get(KURL("http://www.kde.org"));
  68.      *    KIO::Scheduler::scheduleJob(job);
  69.      * \endcode
  70.      *
  71.      * <h3>3. Connection Oriented</h3>
  72.      * For some operations it is important that multiple jobs use
  73.      * the same connection. This can only be ensured if all these jobs
  74.      * use the same slave.
  75.      *
  76.      * You can ask the scheduler to open a slave for connection oriented
  77.      * operations. You can then use the scheduler to assign jobs to this
  78.      * slave. The jobs will be queued and the slave will handle these jobs
  79.      * one after the other.
  80.      *
  81.      * Example:
  82.      * \code
  83.      *    Slave *slave = KIO::Scheduler::getConnectedSlave(
  84.      *            KURL("pop3://bastian:password@mail.kde.org"));
  85.      *    TransferJob *job1 = KIO::get(
  86.      *            KURL("pop3://bastian:password@mail.kde.org/msg1"));
  87.      *    KIO::Scheduler::assignJobToSlave(slave, job1);
  88.      *    TransferJob *job2 = KIO::get(
  89.      *            KURL("pop3://bastian:password@mail.kde.org/msg2"));
  90.      *    KIO::Scheduler::assignJobToSlave(slave, job2);
  91.      *    TransferJob *job3 = KIO::get(
  92.      *            KURL("pop3://bastian:password@mail.kde.org/msg3"));
  93.      *    KIO::Scheduler::assignJobToSlave(slave, job3);
  94.      *
  95.      *    // ... Wait for jobs to finish...
  96.      *
  97.      *    KIO::Scheduler::disconnectSlave(slave);
  98.      * \endcode
  99.      *
  100.      * Note that you need to explicitly disconnect the slave when the 
  101.      * connection goes down, so your error handler should contain:
  102.      * \code
  103.      *    if (error == KIO::ERR_CONNECTION_BROKEN)
  104.      *        KIO::Scheduler::disconnectSlave(slave);
  105.      * \endcode
  106.      *
  107.      * @see KIO::Slave
  108.      * @see KIO::Job
  109.      **/
  110.  
  111.     class KIO_EXPORT Scheduler : public QObject, virtual public DCOPObject {
  112.         Q_OBJECT
  113.  
  114.     public:
  115.         typedef QPtrList<SimpleJob> JobList;
  116.  
  117.         // InfoDict needs Info, so we can't declare it private
  118.         class ProtocolInfo;
  119.         class JobData;
  120.  
  121.         ~Scheduler();
  122.  
  123.         /**
  124.          * Register @p job with the scheduler. 
  125.          * The default is to create a new slave for the job if no slave
  126.          * is available. This can be changed by calling scheduleJob.
  127.      * @param job the job to register
  128.          */
  129.         static void doJob(SimpleJob *job)
  130.         { self()->_doJob(job); }
  131.  
  132.         /**
  133.          * Calling ths function makes that @p job gets scheduled for later
  134.          * execution, if multiple jobs are registered it might wait for
  135.          * other jobs to finish.
  136.      * @param job the job to schedule
  137.          */
  138.         static void scheduleJob(SimpleJob *job)
  139.         { self()->_scheduleJob(job); }
  140.  
  141.         /**
  142.          * Stop the execution of a job.
  143.      * @param job the job to cancel
  144.          */
  145.         static void cancelJob(SimpleJob *job)
  146.         { self()->_cancelJob(job); }
  147.  
  148.         /**
  149.          * Called when a job is done.
  150.      * @param job the finished job
  151.      * @param slave the slave that executed the @p job
  152.          */
  153.         static void jobFinished(KIO::SimpleJob *job, KIO::Slave *slave)
  154.         { self()->_jobFinished(job, slave); }
  155.  
  156.         /**
  157.          * Puts a slave on notice. A next job may reuse this slave if it
  158.          * requests the same URL.
  159.          *
  160.          * A job can be put on hold after it has emit'ed its mimetype.
  161.          * Based on the mimetype, the program can give control to another
  162.          * component in the same process which can then resume the job
  163.          * by simply asking for the same URL again.
  164.      * @param job the job that should be stopped
  165.      * @param url the URL that is handled by the @p url
  166.          */
  167.         static void putSlaveOnHold(KIO::SimpleJob *job, const KURL &url)
  168.         { self()->_putSlaveOnHold(job, url); }
  169.  
  170.         /**
  171.          * Removes any slave that might have been put on hold. If a slave 
  172.          * was put on hold it will be killed.
  173.          */
  174.         static void removeSlaveOnHold()
  175.         { self()->_removeSlaveOnHold(); }
  176.  
  177.         /**
  178.          * Send the slave that was put on hold back to KLauncher. This
  179.          * allows another process to take over the slave and resume the job
  180.          * that was started.
  181.          */
  182.         static void publishSlaveOnHold()
  183.         { self()->_publishSlaveOnHold(); }
  184.  
  185.         /**
  186.          * Requests a slave for use in connection-oriented mode.
  187.          *
  188.          * @param url This defines the username,password,host & port to
  189.          *            connect with.
  190.          * @param config Configuration data for the slave.
  191.          *
  192.          * @return A pointer to a connected slave or 0 if an error occurred.
  193.          * @see assignJobToSlave()
  194.          * @see disconnectSlave()
  195.          */
  196.         static KIO::Slave *getConnectedSlave(const KURL &url, const KIO::MetaData &config = MetaData() )
  197.         { return self()->_getConnectedSlave(url, config); }
  198.  
  199.         /*
  200.          * Uses @p slave to do @p job.
  201.          * This function should be called immediately after creating a Job.
  202.          *
  203.          * @param slave The slave to use. The slave must have been obtained
  204.          *              with a call to getConnectedSlave and must not
  205.          *              be currently assigned to any other job.
  206.          * @param job The job to do.
  207.          *
  208.          * @return true is successful, false otherwise.
  209.          *
  210.          * @see getConnectedSlave()
  211.          * @see disconnectSlave()
  212.          * @see slaveConnected()
  213.          * @see slaveError()
  214.          */
  215.         static bool assignJobToSlave(KIO::Slave *slave, KIO::SimpleJob *job)
  216.         { return self()->_assignJobToSlave(slave, job); }
  217.  
  218.         /*
  219.          * Disconnects @p slave.
  220.          *
  221.          * @param slave The slave to disconnect. The slave must have been
  222.          *              obtained with a call to getConnectedSlave
  223.          *              and must not be assigned to any job.
  224.          *
  225.          * @return true is successful, false otherwise.
  226.          *
  227.          * @see getConnectedSlave
  228.          * @see assignJobToSlave
  229.          */
  230.         static bool disconnectSlave(KIO::Slave *slave)
  231.         { return self()->_disconnectSlave(slave); }
  232.  
  233.         /**
  234.          * Send the slave that was put on hold back to KLauncher. This
  235.          * allows another process to take over the slave and resume the job
  236.          * the that was started.
  237.          * Register the mainwindow @p wid with the KIO subsystem
  238.          * Do not call this, it is called automatically from
  239.          * void KIO::Job::setWindow(QWidget*).
  240.      * @param wid the window to register
  241.      * @since 3.1
  242.          */
  243.         static void registerWindow(QWidget *wid)
  244.         { self()->_registerWindow(wid); }
  245.         
  246.         /**
  247.          * @internal
  248.          * Unregisters the window registered by registerWindow().
  249.          */
  250.         static void unregisterWindow(QObject *wid)
  251.         { self()->slotUnregisterWindow(wid); }
  252.  
  253.         /**
  254.          * Function to connect signals emitted by the scheduler.
  255.          *
  256.          * @see slaveConnected()
  257.          * @see slaveError()
  258.          */
  259.         static bool connect( const char *signal, const QObject *receiver,
  260.                              const char *member)
  261.         { return QObject::connect(self(), signal, receiver, member); }
  262.  
  263.         static bool connect( const QObject* sender, const char* signal,
  264.                              const QObject* receiver, const char* member )
  265.         { return QObject::connect(sender, signal, receiver, member); }
  266.  
  267.         static bool disconnect( const QObject* sender, const char* signal,
  268.                                 const QObject* receiver, const char* member )
  269.         { return QObject::disconnect(sender, signal, receiver, member); }
  270.  
  271.         bool connect( const QObject *sender, const char *signal,
  272.                       const char *member )
  273.         { return QObject::connect(sender, signal, member); }
  274.  
  275.         /**
  276.          * When true, the next job will check whether KLauncher has a slave 
  277.          * on hold that is suitable for the job.
  278.      * @param b true when KLauncher has a job on hold
  279.          */
  280.         static void checkSlaveOnHold(bool b) { self()->_checkSlaveOnHold(b); }
  281.  
  282.         void debug_info();
  283.  
  284.         virtual bool process(const QCString &fun, const QByteArray &data,
  285.                              QCString& replyType, QByteArray &replyData);
  286.  
  287.         virtual QCStringList functions();
  288.  
  289.     public slots:
  290.         void slotSlaveDied(KIO::Slave *slave);
  291.         void slotSlaveStatus(pid_t pid, const QCString &protocol,
  292.                              const QString &host, bool connected);
  293.     signals:
  294.         void slaveConnected(KIO::Slave *slave);
  295.         void slaveError(KIO::Slave *slave, int error, const QString &errorMsg);
  296.  
  297.     protected:
  298.         void setupSlave(KIO::Slave *slave, const KURL &url, const QString &protocol, const QString &proxy , bool newSlave, const KIO::MetaData *config=0);
  299.         bool startJobScheduled(ProtocolInfo *protInfo);
  300.         bool startJobDirect();
  301.         Scheduler();
  302.  
  303.     protected slots:
  304.         void startStep();
  305.         void slotCleanIdleSlaves();
  306.         void slotSlaveConnected();
  307.         void slotSlaveError(int error, const QString &errorMsg);
  308.         void slotScheduleCoSlave();
  309.       /// @since 3.1
  310.         void slotUnregisterWindow(QObject *);
  311.  
  312.     private:
  313.         class ProtocolInfoDict;
  314.         class ExtraJobData;
  315.  
  316.         Scheduler(const Scheduler&);
  317.         static Scheduler *self();
  318.         static Scheduler *instance;
  319.         void _doJob(SimpleJob *job);
  320.         void _scheduleJob(SimpleJob *job);
  321.         void _cancelJob(SimpleJob *job);
  322.         void _jobFinished(KIO::SimpleJob *job, KIO::Slave *slave);
  323.         void _scheduleCleanup();
  324.         void _putSlaveOnHold(KIO::SimpleJob *job, const KURL &url);
  325.         void _removeSlaveOnHold();
  326.         Slave *_getConnectedSlave(const KURL &url, const KIO::MetaData &metaData );
  327.         bool _assignJobToSlave(KIO::Slave *slave, KIO::SimpleJob *job);
  328.         bool _disconnectSlave(KIO::Slave *slave);
  329.         void _checkSlaveOnHold(bool b);
  330.         void _publishSlaveOnHold();
  331.         void _registerWindow(QWidget *wid);
  332.         
  333.         Slave *findIdleSlave(ProtocolInfo *protInfo, SimpleJob *job, bool &exact);
  334.         Slave *createSlave(ProtocolInfo *protInfo, SimpleJob *job, const KURL &url);
  335.         
  336.  
  337.         QTimer slaveTimer;
  338.         QTimer coSlaveTimer;
  339.         QTimer cleanupTimer;
  340.         bool busy;
  341.  
  342.         SlaveList *slaveList;
  343.         SlaveList *idleSlaves;
  344.         SlaveList *coIdleSlaves;
  345.  
  346.         ProtocolInfoDict *protInfoDict;
  347.         Slave *slaveOnHold;
  348.         KURL urlOnHold;
  349.         JobList newJobs;
  350.  
  351.         QPtrDict<JobList> coSlaves;
  352.         ExtraJobData *extraJobData;
  353.         SlaveConfig *slaveConfig;
  354.         SessionData *sessionData;
  355.         bool checkOnHold;
  356.         QMap<QObject *,WId> m_windowList;
  357.     protected:
  358.     virtual void virtual_hook( int id, void* data );
  359.     private:
  360.     class SchedulerPrivate* d;
  361. };
  362.  
  363. }
  364. #endif
  365.