libkdepim

KPIM::ThreadWeaver::Weaver Class Reference

#include <weaver.h>

List of all members.


Detailed Description

A weaver is the manager of worker threads (Thread objects) to which it assigns jobs from it's queue.

Definition at line 296 of file weaver.h.


Signals

void finished ()
void suspended ()
void jobDone (Job *)
void threadCreated (Thread *)
void threadDestroyed (Thread *)
void threadBusy (Thread *)
void threadSuspended (Thread *)

Public Member Functions

 Weaver (QObject *parent=0, const char *name=0, int inventoryMin=4, int inventoryMax=32)
virtual ~Weaver ()
virtual void enqueue (Job *)
void enqueue (QPtrList< Job > jobs)
virtual bool dequeue (Job *)
virtual void dequeue ()
virtual void finish ()
virtual void suspend (bool state)
bool isEmpty () const
bool isIdle () const
int queueLength ()
virtual JobapplyForWork (Thread *thread, Job *previous)
void lock ()
void unlock ()
void post (Event::Action, Thread *=0, Job *=0)
int threads () const

Protected Member Functions

void assignJobs ()
bool event (QEvent *)

Protected Attributes

QPtrList< Threadm_inventory
QPtrList< Jobm_assignments
int m_active
int m_inventoryMin
int m_inventoryMax
QWaitCondition m_jobAvailable
QWaitCondition m_jobFinished
bool m_shuttingDown
bool m_running
bool m_suspend

Member Function Documentation

void KPIM::ThreadWeaver::Weaver::enqueue ( Job  )  [virtual]

Add a job to be executed.

Definition at line 327 of file weaver.cpp.

void KPIM::ThreadWeaver::Weaver::enqueue ( QPtrList< Job jobs  ) 

Enqueue all jobs in the given list.

This is an atomic operation, no jobs will start before all jobs in the list are enqueued. If you need a couple of jobs done and want to receive the finished () signal afterwards, use this method to queue them. Otherwise, when enqueueing your jobs individually, there is a chance that you receive more than one finished signal.

Definition at line 339 of file weaver.cpp.

bool KPIM::ThreadWeaver::Weaver::dequeue ( Job  )  [virtual]

Remove a job from the queue.

If the job qas queued but not started so far, it is simple 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.

Definition at line 353 of file weaver.cpp.

void KPIM::ThreadWeaver::Weaver::dequeue (  )  [virtual]

Remove all queued jobs.

Please note that this will not kill the threads, therefore all jobs that are being processed will be continued.

Definition at line 359 of file weaver.cpp.

void KPIM::ThreadWeaver::Weaver::finish (  )  [virtual]

Finish all queued operations, then return.

This method is used in imperative programs that cannot react on events to have the controlling (main) thread wait wait for the jobs to finish. Warning: This will suspend your thread! Warning: If your jobs enter for example an infinite loop, this will never return!

Definition at line 537 of file weaver.cpp.

void KPIM::ThreadWeaver::Weaver::suspend ( bool  state  )  [virtual]

Suspend job execution if state = true, otherwise resume job execution if it was suspended.

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 (true) and there are no jobs left to be done, you will immidiately receive the suspended() signal.

Definition at line 365 of file weaver.cpp.

bool KPIM::ThreadWeaver::Weaver::isEmpty (  )  const

Is the queue empty?

Definition at line 451 of file weaver.cpp.

bool KPIM::ThreadWeaver::Weaver::isIdle (  )  const

Is the weaver idle? The weaver is idle if no jobs are queued and no jobs are processed by the threads (m_active is zero).

Definition at line 531 of file weaver.cpp.

int KPIM::ThreadWeaver::Weaver::queueLength (  ) 

Returns the number of pending jobs.

Definition at line 525 of file weaver.cpp.

Job * KPIM::ThreadWeaver::Weaver::applyForWork ( Thread thread,
Job previous 
) [virtual]

Assign a job to the calling thread.

This is supposed to be called from the Thread objects in the inventory. Returns 0 if the weaver is shutting down, telling the calling thread to finish and exit. If no jobs are available and shut down is not in progress, the calling thread is suspended until either condition is met. In previous, threads give the job they have completed. If this is the first job, previous is zero.

Definition at line 457 of file weaver.cpp.

void KPIM::ThreadWeaver::Weaver::lock (  ) 

Lock the mutex for this weaver.

The threads in the inventory need to lock the weaver's mutex to synchronize the job management.

Definition at line 306 of file weaver.cpp.

void KPIM::ThreadWeaver::Weaver::unlock (  ) 

Unlock.

See lock().

Definition at line 313 of file weaver.cpp.

void KPIM::ThreadWeaver::Weaver::post ( Event::Action  ,
Thread = 0,
Job = 0 
)

Post an event that is handled by this object, but in the main (GUI) thread.

Different threads may use this method to communicate with the main thread. thread and job mark the objects associated with this event.

Definition at line 445 of file weaver.cpp.

int KPIM::ThreadWeaver::Weaver::threads (  )  const

Returns the current number of threads in the inventory.

Definition at line 321 of file weaver.cpp.

void KPIM::ThreadWeaver::Weaver::finished (  )  [signal]

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 KPIM::ThreadWeaver::Weaver::suspended (  )  [signal]

Thread queueing has been suspended.

When suspend is called with state = true, all threads are allowed to finish their job. When the last thread finished, this signal is emitted.

void KPIM::ThreadWeaver::Weaver::jobDone ( Job  )  [signal]

This signal is emitted when a job is done.

It is up to the programmer if this signal or the done signal of the job is more handy.

void KPIM::ThreadWeaver::Weaver::assignJobs (  )  [protected]

Schedule enqueued jobs to be executed by idle threads.

This will try to distribute as many jobs as possible to all idle threads.

Definition at line 387 of file weaver.cpp.

bool KPIM::ThreadWeaver::Weaver::event ( QEvent *   )  [protected]

Check incoming events for user defined ones.

The threads use user defined events to communicate with the Weaver.

Definition at line 392 of file weaver.cpp.


Member Data Documentation

The thread inventory.

Definition at line 415 of file weaver.h.

The job queue.

Definition at line 417 of file weaver.h.

The number of jobs that are assigned to the worker threads, but not finished.

Definition at line 420 of file weaver.h.

Stored setting.

Definition at line 422 of file weaver.h.

Stored setting .

Definition at line 424 of file weaver.h.

QWaitCondition KPIM::ThreadWeaver::Weaver::m_jobAvailable [protected]

Wait condition all idle or done threads wait for.

Definition at line 426 of file weaver.h.

QWaitCondition KPIM::ThreadWeaver::Weaver::m_jobFinished [protected]

Wait for a job to finish.

Definition at line 428 of file weaver.h.

Indicates if the weaver is shutting down and exiting it's threads.

Definition at line 431 of file weaver.h.

m_running is set to true when a job is enqueued and set to false when the job finishes that was the last in the queue.

E.g., this will flip from false to true to false when you continuously enqueue one single job.

Definition at line 436 of file weaver.h.

If m_suspend is true, no new jobs will be assigned to threads.

Jobs may be queued, but will not be processed until suspend (false) is called.

Definition at line 441 of file weaver.h.


The documentation for this class was generated from the following files:
KDE Home | KDE Accessibility Home | Description of Access Keys