KPIM::ThreadWeaver::Job Class Reference

#include <weaver.h>

Inherits TQObject.

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

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

Protected Member Functions
void	lock ()
void	unlock ()
virtual void	run ()=0
Thread *	thread ()
virtual void	setFinished (bool status)
void	triggerSPR ()
void	triggerAPR ()

Protected Attributes
bool	m_finished
TQMutex *	m_mutex
Thread *	m_thread
TQWaitCondition *	m_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:

• Synchronous Process Requests (SPR): Synchronous requests expect that the complete request is performed in the slots connected to the signals. For example, to update a widget according to the progress of the job, a SPR may be used. In such cases, the Job's execution will be resumed immediately after the signal has been processed.
• Asynchronous Process Requests (APR): For APRs, the job emitting the signal does not assume anything about the amount of time needed to perform the operation. Therefore, the thread is not waked after the signal returns. The creator has to wake to thread whenever it is ready by calling the wakeAPR method.

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 163 of file weaver.h.

Constructor & Destructor Documentation

Job()

KPIM::ThreadWeaver::Job::Job	(	TQObject *	parent = 0,
		const char *	name = 0
	)

Construct a Job object.

Definition at line 30 of file weaver.cpp.

~Job()

KPIM::ThreadWeaver::Job::~Job ( )

virtual

Destructor.

Definition at line 38 of file weaver.cpp.

Member Function Documentation

APR

void KPIM::ThreadWeaver::Job::APR ( )

signal

Perform an Asynchronous Process Request.

See SPR and the generic Job documentation for a comparison.

done

void KPIM::ThreadWeaver::Job::done ( )

signal

This signal is emitted when a job has been finished.

execute()

void KPIM::ThreadWeaver::Job::execute ( Thread *  th )

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 52 of file weaver.cpp.

isFinished()

bool KPIM::ThreadWeaver::Job::isFinished ( ) const

virtual

Returns true if the jobs's execute method finished.

Definition at line 72 of file weaver.cpp.

lock()

void KPIM::ThreadWeaver::Job::lock ( )

protected

Lock this Job's mutex.

Definition at line 42 of file weaver.cpp.

processEvent()

void KPIM::ThreadWeaver::Job::processEvent ( Event *  e )

virtual

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

Definition at line 84 of file weaver.cpp.

run()

virtual void KPIM::ThreadWeaver::Job::run ( )

protectedpure 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.

setFinished()

void KPIM::ThreadWeaver::Job::setFinished ( bool  status )

protectedvirtual

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

Definition at line 78 of file weaver.cpp.

SPR

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.

started

void KPIM::ThreadWeaver::Job::started ( )

signal

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

thread()

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 66 of file weaver.cpp.

triggerAPR()

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 122 of file weaver.cpp.

triggerSPR()

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 107 of file weaver.cpp.

unlock()

void KPIM::ThreadWeaver::Job::unlock ( )

protected

Unlock this Job's mutex.

Definition at line 47 of file weaver.cpp.

wakeAPR()

void KPIM::ThreadWeaver::Job::wakeAPR

(

)

Wake the thread after an APR has been processed.

Definition at line 132 of file weaver.cpp.

---

The documentation for this class was generated from the following files:

• weaver.h
• weaver.cpp