libkdepim Library API Documentation

KPIM::ThreadWeaver::Job Class Reference

A Job is a simple abstraction of an action that is to be executed in a thread context. More...

#include <weaver.h>

Inheritance diagram for KPIM::ThreadWeaver::Job:

QObject List of all members.

Signals

void started ()
void done ()
void SPR ()
void APR ()

Public Methods

 Job (QObject *parent=0, const char *name=0)
virtual ~Job ()
virtual void execute (Thread *)
virtual bool isFinished () const
void wakeAPR ()
virtual void processEvent (Event *)

Protected Methods

void lock ()
void unlock ()
virtual void run ()=0
Threadthread ()
virtual void setFinished (bool status)
void triggerSPR ()
void triggerAPR ()

Protected Attributes

bool m_finished
QMutexm_mutex
Threadm_thread
QWaitConditionm_wc

Detailed Description

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. See the SPR signal for an example.

Jobs may emit process requests as signals. Consider process requests as a kind of synchronized call to the main thread. Process Requests are a generic means for Job derivate programmers to have the jobs interact with the creators (in the main thread) during processing time. To avoid race conditions and extensive locking and unlocking, the thread executing the job is suspended during the period needed to process the request.

There are two kinds of process requests (we introduce abbreviations, also in the signal names and the code, only to save typing). Both are emitted by signals in the main thread:

Note: When using an APR, you better make sure to receive the signal with some object, otherwise the calling thread will block forever!

Definition at line 162 of file weaver.h.


Constructor & Destructor Documentation

KPIM::ThreadWeaver::Job::Job QObject   parent = 0,
const char *    name = 0
 

Construct a Job object.

Definition at line 31 of file weaver.cpp.

KPIM::ThreadWeaver::Job::~Job   [virtual]
 

Destructor.

Definition at line 39 of file weaver.cpp.


Member Function Documentation

void KPIM::ThreadWeaver::Job::execute Thread   [virtual]
 

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().

Definition at line 53 of file weaver.cpp.

References QMutex::lock(), run(), setFinished(), and QMutex::unlock().

Referenced by KPIM::ThreadWeaver::Thread::run().

bool KPIM::ThreadWeaver::Job::isFinished   const [virtual]
 

Returns true if the jobs's execute method finished.

Definition at line 73 of file weaver.cpp.

void KPIM::ThreadWeaver::Job::wakeAPR  
 

Wake the thread after an APR has been processed.

Definition at line 133 of file weaver.cpp.

References QWaitCondition::wakeOne().

void KPIM::ThreadWeaver::Job::processEvent Event   [virtual]
 

Process events related to this job (created by the processing thread or the weaver or whoever).

Definition at line 85 of file weaver.cpp.

References KPIM::ThreadWeaver::Event::action(), APR(), done(), SPR(), started(), and QWaitCondition::wakeOne().

Referenced by KPIM::ThreadWeaver::Weaver::event().

void KPIM::ThreadWeaver::Job::started   [signal]
 

This signal is emitted when a thread starts to process a job.

Referenced by processEvent().

void KPIM::ThreadWeaver::Job::done   [signal]
 

This signal is emitted when a job has been finished.

Referenced by processEvent().

void KPIM::ThreadWeaver::Job::SPR   [signal]
 

This signal is emitted when the job needs some operation done by the main thread (usually the creator of the job).

It is important to understand that the emitting thread is suspended until the signal returns. When the operation requested has been performed and this signal is finished, the thread is automatically waked. What operation needs to be performed has to be negotiated between the two objects. Note: This signal is an attempt to provide job programmers with a generic way to interact while the job is executed. I am interested in feedback about it's use.

Referenced by processEvent().

void KPIM::ThreadWeaver::Job::APR   [signal]
 

Perform an Asynchronous Process Request.

See SPR and the generic Job documentation for a comparison.

Referenced by processEvent().

void KPIM::ThreadWeaver::Job::lock   [protected]
 

Lock this Job's mutex.

Definition at line 43 of file weaver.cpp.

References QMutex::lock().

void KPIM::ThreadWeaver::Job::unlock   [protected]
 

Unlock this Job's mutex.

Definition at line 48 of file weaver.cpp.

References QMutex::unlock().

virtual void KPIM::ThreadWeaver::Job::run   [protected, pure virtual]
 

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.

Referenced by execute().

Thread * KPIM::ThreadWeaver::Job::thread   [protected]
 

Return the thread that executes this job.

Returns zero of the job is not currently executed.

Definition at line 67 of file weaver.cpp.

Referenced by triggerAPR(), and triggerSPR().

void KPIM::ThreadWeaver::Job::setFinished bool    status [protected, virtual]
 

Call with status = true to mark this job as done.

Definition at line 79 of file weaver.cpp.

Referenced by execute().

void KPIM::ThreadWeaver::Job::triggerSPR   [protected]
 

Trigger a SPR.

This emits a signal in the main thread indicating the necessity of a synchronized operation.

Definition at line 108 of file weaver.cpp.

References QMutex::lock(), KPIM::ThreadWeaver::Thread::post(), thread(), QMutex::unlock(), and QWaitCondition::wait().

void KPIM::ThreadWeaver::Job::triggerAPR   [protected]
 

Trigger an APR.

This emit a signal in the main thread indicating the necessity of an unsynchronized operation. The calling thread needs to ensure to wake the thread when the operation is done.

Definition at line 123 of file weaver.cpp.

References KPIM::ThreadWeaver::Event::JobAPR, QMutex::lock(), KPIM::ThreadWeaver::Thread::post(), thread(), QMutex::unlock(), and QWaitCondition::wait().


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for libkdepim Library Version 3.2.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Sat May 1 11:36:32 2004 by doxygen 1.2.15 written by Dimitri van Heesch, © 1997-2003