kdelibs/threadweaver/Weaver/WeaverInterface.h

/* -*- C++ -*-

   This file declares the WeaverInterface class.

   $ Author: Mirko Boehm $
   $ Copyright: (C) 2005-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: WeaverImpl.h 29 2005-08-14 19:04:30Z mirko $
*/

#ifndef WEAVERINTERFACE_H
#define WEAVERINTERFACE_H

#include <QtCore/QObject>

#include <threadweaver/threadweaver_export.h>

namespace ThreadWeaver {

class Job;
class State;
class WeaverObserver;

/** WeaverInterface provides a common interface for weaver implementations.

In most cases, it is sufficient for an application to hold exactly one
ThreadWeaver job queue. To execute jobs in a specific order, use job
dependencies. To limit the number of jobs of a certain type that can
be executed at the same time, use resource restrictions. To handle
special requirements of the application when it comes to the order of
execution of jobs, implement a special queue policy and apply it to
the jobs.

Users of the ThreadWeaver API are encouraged to program to this
interface, instead of the implementation. This way, implementation
changes will not affect user programs.

This interface can be used for example to implement adapters and
decorators. The member documentation is provided in the Weaver and
WeaverImpl classes.
*/

class THREADWEAVER_EXPORT WeaverInterface : public QObject {
    Q_OBJECT

public:
    /** A ThreadWeaver object manages a queue of Jobs.
    It inherits QObject.
    */
    explicit WeaverInterface ( QObject* parent = 0 );
    virtual ~WeaverInterface() {}
    /** Return the state of the weaver object. */
    virtual const State& state() const = 0;

    /** Set the maximum number of threads this Weaver object may start. */
    virtual void setMaximumNumberOfThreads( int cap ) = 0;

    /** Get the maximum number of threads this Weaver may start. */
    virtual int maximumNumberOfThreads() const = 0;

    /** Returns the current number of threads in the inventory. */
    virtual int currentNumberOfThreads () const = 0;

    /** Register an observer.

    Observers provides signals on different weaver events that are
    otherwise only available through objects of different classes
    (threads, jobs). Usually, access to the signals of those objects
    is not provided through the weaver API. Use an observer to reveice
    notice, for example, on thread activity.

    To unregister, simply delete the observer.
    */
    virtual void registerObserver ( WeaverObserver* ) = 0;
    /** Add a job to be executed.

    It depends on the state if execution of the job will be attempted
    immediately. In suspended state, jobs can be added to the queue,
    but the threads remain suspended. In WorkongHard state, an idle
    thread may immediately execute the job, or it might be queued if
    all threads are busy.
    */
    virtual void enqueue ( Job* ) = 0;
    /** Remove a job from the queue.
    If the job was queued but not started so far, it is simply
    removed from the queue. For now, it is unsupported to
    dequeue a job once its execution has started.

    For that case, you will have to provide a method to interrupt your
    job's execution (and receive the done signal).
    Returns true if the job has been dequeued, false if the
    job has already been started or is not found in the
    queue. */
    virtual bool dequeue ( Job* ) = 0;
    /** Remove all queued jobs.
    Please note that this will not kill the threads, therefore
    all jobs that are being processed will be continued. */
    virtual void dequeue () = 0;
    /** Finish all queued operations, then return.

    This method is used in imperative (not event driven) programs that
    cannot react on events to have the controlling (main) thread wait
    wait for the jobs to finish. The call will block the calling
    thread and return when all queued jobs have been processed.

    Warning: This will suspend your thread!
    Warning: If one of your jobs enters an infinite loop, this
    will never return! */
    virtual void finish () = 0;
    /** Suspend job execution.
    When suspending, all threads are allowed to finish the
    currently assigned job but will not receive a new
    assignment.
    When all threads are done processing the assigned job, the
    signal suspended will() be emitted.
    If you call suspend() and there are no jobs left to
    be done, you will immediately receive the suspended()
    signal. */
    virtual void suspend () = 0;
    /** Resume job queueing.
    @see suspend
    */
    virtual void resume () = 0;
    /** Is the queue empty?
    The queue is empty if no more jobs are queued. */
    virtual bool isEmpty () const = 0;
    /** Is the weaver idle?
    The weaver is idle if no jobs are queued and no jobs are processed
    by the threads. */
    virtual bool isIdle () const = 0;
    /** Returns the number of pending jobs.
    This will return the number of queued jobs. Jobs that are
    currently being executed are not part of the queue. All jobs in
    the queue are waiting to be executed.
    */
    virtual int queueLength () const = 0;

    /** Request aborts of the currently executed jobs.
    It is important to understand that aborts are requested, but
    cannot be guaranteed, as not all Job classes support it. It is up
    to the application to decide if and how job aborts are
    necessary. */
    virtual void requestAbort() = 0;

Q_SIGNALS:
    /** This signal is emitted when the Weaver has finished ALL currently
    queued jobs.
    If a number of jobs is enqueued sequentially, this signal might be
    emitted a couple of times (what happens is that all already queued
    jobs have been processed while you still add new ones). This is
    not a bug, but the intended behaviour. */
    void finished ();

    /** Thread queueing has been suspended.
    When suspend is called with, all threads are
    allowed to finish their job. When the last thread
    finished, this signal is emitted. */
    void suspended ();

    /** This signal is emitted when a job is finished.  In addition,
    the Job itself emits a done() signal just before the jobDone() signal
    is emitted.
    */
    void jobDone ( ThreadWeaver::Job* );
    // FIXME (0.7) test if signal is emitted properly
    // FIXME (0.7) provide jobStarted and jobFailed signals
    // FIXME (0.7) or remove all these, and add them to WeaverObserver

    /** The Weaver's state has changed. */
    void stateChanged ( ThreadWeaver::State* );
};

}

#endif