mirror of
https://bitbucket.org/smil3y/kdelibs.git
synced 2025-02-24 10:52:49 +00:00
61333c4671
most of the changes were done trought Katie's namefsck script which convertes forward class declarations to include directives, however other fixes here and there were needed as well as some questionable changes to Q_DECLARE_TYPEINFO() macro calls because they most likely have to do the namespacing themselfs (QT_BEGIN/END_NAMESPACE, and probably will be in Katie) meaning that some of the changes may be temporary and reverted later. Signed-off-by: Ivailo Monev <xakepa10@gmail.com>
238 lines
8.8 KiB
C++
238 lines
8.8 KiB
C++
/* -*- C++ -*-
|
|
|
|
This file declares the Job class.
|
|
|
|
$ Author: Mirko Boehm $
|
|
$ Copyright: (C) 2004-2013 Mirko Boehm $
|
|
$ Contact: mirko@kde.org
|
|
http://www.kde.org
|
|
http://creative-destruction.me $
|
|
|
|
This library is free software; you can redistribute it and/or
|
|
modify it under the terms of the GNU Library General Public
|
|
License as published by the Free Software Foundation; either
|
|
version 2 of the License, or (at your option) any later version.
|
|
|
|
This library is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Library General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Library General Public License
|
|
along with this library; see the file COPYING.LIB. If not, write to
|
|
the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
|
|
Boston, MA 02110-1301, USA.
|
|
|
|
$Id: Job.h 32 2005-08-17 08:38:01Z mirko $
|
|
*/
|
|
|
|
#ifndef THREADWEAVER_JOB_H
|
|
#define THREADWEAVER_JOB_H
|
|
|
|
#include <QtCore/QObject>
|
|
|
|
#include <threadweaver/threadweaver_export.h>
|
|
|
|
#include <QMutex>
|
|
#include <QWaitCondition>
|
|
|
|
namespace ThreadWeaver {
|
|
|
|
class Thread;
|
|
class QueuePolicy;
|
|
class JobRunHelper;
|
|
class WeaverInterface;
|
|
class QueuePolicyList;
|
|
|
|
/** A Job is a simple abstraction of an action that is to be
|
|
executed in a thread context.
|
|
It is essential for the ThreadWeaver library that as a kind of
|
|
convention, the different creators of Job objects do not touch the
|
|
protected data members of the Job until somehow notified by the
|
|
Job.
|
|
|
|
Also, please note that Jobs may not be executed twice. Create two
|
|
different objects to perform two consecutive or parallel runs.
|
|
|
|
Jobs may declare dependencies. If Job B depends on Job A, B may not be
|
|
executed before A is finished. To learn about dependencies, see
|
|
DependencyPolicy.
|
|
|
|
Job objects finish by emitting the done(Job*) signal. Once this has been emitted,
|
|
ThreadWeaver is no longer using the Job which may then be deleted.
|
|
*/
|
|
|
|
class THREADWEAVER_EXPORT Job : public QObject
|
|
{
|
|
Q_OBJECT
|
|
|
|
public:
|
|
friend class JobRunHelper;
|
|
|
|
/** Construct a Job.
|
|
|
|
@param parent the parent QObject
|
|
*/
|
|
explicit Job ( QObject* parent = 0 );
|
|
|
|
/** Destructor. */
|
|
virtual ~Job();
|
|
|
|
/** Perform the job. The thread in which this job is executed
|
|
is given as a parameter.
|
|
Do not overload this method to create your own Job
|
|
implementation, overload run(). */
|
|
virtual void execute(Thread*);
|
|
|
|
/** The queueing priority of the job.
|
|
Jobs will be sorted by their queueing priority when
|
|
enqueued. A higher queueing priority will place the job in
|
|
front of all lower-priority jobs in the queue.
|
|
|
|
Note: A higher or lower priority does not influence queue
|
|
policies. For example, a high-priority job that has an
|
|
unresolved dependency will not be executed, which means an
|
|
available lower-priority job will take precedence.
|
|
|
|
The default implementation returns zero. Only if this method
|
|
is overloaded for some job classes, priorities will
|
|
influence the execution order of jobs.
|
|
*/
|
|
virtual int priority() const;
|
|
|
|
/** Return whether the Job finished successfully or not.
|
|
The default implementation simply returns true. Overload in
|
|
derived classes if the derived Job class can fail.
|
|
|
|
If a job fails (success() returns false), it will *NOT* resolve
|
|
its dependencies when it finishes. This will make sure that Jobs
|
|
that depend on the failed job will not be started.
|
|
|
|
There is an important gotcha: When a Job object is deleted, it
|
|
will always resolve its dependencies. If dependent jobs should
|
|
not be executed after a failure, it is important to dequeue those
|
|
before deleting the failed Job.
|
|
|
|
A JobSequence may be helpful for that purpose.
|
|
*/
|
|
virtual bool success () const;
|
|
|
|
/** Abort the execution of the job.
|
|
Call this method to ask the Job to abort if it is currently executed.
|
|
Please note that the default implementation of the method does
|
|
nothing (!). This is due to the fact that there is no generic
|
|
method to abort a processing Job. Not even a default boolean flag
|
|
makes sense, as Job could, for example, be in an event loop and
|
|
will need to create an exit event.
|
|
You have to reimplement the method to actually initiate an abort
|
|
action.
|
|
The method is not pure virtual because users are not supposed to
|
|
be forced to always implement requestAbort().
|
|
Also, this method is supposed to return immediately, not after the
|
|
abort has completed. It requests the abort, the Job has to act on
|
|
the request. */
|
|
virtual void requestAbort () {}
|
|
|
|
/** The job is about to be added to the weaver's job queue.
|
|
The job will be added right after this method finished. The
|
|
default implementation does nothing.
|
|
Use this method to, for example, queue sub-operations as jobs
|
|
before the job itself is queued.
|
|
|
|
Note: When this method is called, the associated Weaver object's
|
|
thread holds a lock on the weaver's queue. Therefore, it is save
|
|
to assume that recursive queueing is atomic from the queues
|
|
perspective.
|
|
|
|
@param weaver the Weaver object the job will be queued in
|
|
*/
|
|
virtual void aboutToBeQueued ( WeaverInterface *weaver );
|
|
|
|
/** This Job is about the be dequeued from the weaver's job queue.
|
|
The job will be removed from the queue right after this method
|
|
returns.
|
|
Use this method to dequeue, if necessary, sub-operations (jobs) that this job
|
|
has enqueued.
|
|
|
|
Note: When this method is called, the associated Weaver object's
|
|
thread does hold a lock on the weaver's queue.
|
|
|
|
Note: The default implementation does nothing.
|
|
|
|
@param weaver the Weaver object from which the job will be dequeued
|
|
*/
|
|
virtual void aboutToBeDequeued ( WeaverInterface *weaver );
|
|
|
|
/** canBeExecuted() returns true if all the jobs queue policies agree to it.
|
|
If it returns true, it expects that the job is executed right
|
|
after that. The done() methods of the queue policies will be
|
|
automatically called when the job is finished.
|
|
|
|
If it returns false, all queue policy resources have been freed,
|
|
and the method can be called again at a later time.
|
|
*/
|
|
virtual bool canBeExecuted();
|
|
|
|
/** Returns true if the jobs's execute method finished. */
|
|
bool isFinished() const;
|
|
|
|
/** Assign a queue policy.
|
|
Queue Policies customize the queueing (running) behaviour of sets
|
|
of jobs. Examples for queue policies are dependencies and resource
|
|
restrictions.
|
|
Every queue policy object can only be assigned once to a job,
|
|
multiple assignments will be IGNORED.
|
|
*/
|
|
void assignQueuePolicy ( QueuePolicy* );
|
|
|
|
/** Remove a queue policy from this job.
|
|
*/
|
|
void removeQueuePolicy ( QueuePolicy* );
|
|
|
|
Q_SIGNALS:
|
|
/** This signal is emitted when this job is being processed by a
|
|
thread. */
|
|
void started ( ThreadWeaver::Job* );
|
|
/**
|
|
* This signal is emitted when the job has been finished (no matter if it succeeded or not).
|
|
* After this signal has been emitted, ThreadWeaver no longer references the Job internally
|
|
* and the Job can be deleted.
|
|
*/
|
|
void done ( ThreadWeaver::Job* );
|
|
|
|
/** This job has failed.
|
|
This signal is emitted when success() returns false after the job
|
|
is executed.
|
|
*/
|
|
void failed( ThreadWeaver::Job* );
|
|
|
|
protected:
|
|
class Private;
|
|
Private* d;
|
|
|
|
/** Free the queue policies acquired before this job has been
|
|
executed. */
|
|
void freeQueuePolicyResources();
|
|
|
|
/** The method that actually performs the job. It is called from
|
|
execute(). This method is the one to overload it with the
|
|
job's task. */
|
|
virtual void run () = 0;
|
|
/** Return the thread that executes this job.
|
|
Returns zero of the job is not currently executed.
|
|
|
|
Do not confuse with QObject::thread() const !
|
|
// @todo rename to executingThread()
|
|
*/
|
|
Thread *thread();
|
|
|
|
/** Call with status = true to mark this job as done. */
|
|
void setFinished ( bool status );
|
|
|
|
/** The mutex used to protect this job. */
|
|
// QMutex& mutex();
|
|
|
|
};
|
|
}
|
|
|
|
#endif // THREADWEAVER_JOB_H
|