thrCreateWorkforce

Create a thread pool holding a specified number of threads

Description:

This function creates a new " workforce" - a pool of threads that can be used to execute tasks in parallel. Each task should be split into two or more jobs, and a description of each job should be given to the workforce using thrAddJob. As each job is added, any available worker thread claims the job and executes it. If all workers are busy, the jobs will be claimed by workers once they have completed their current jobs. Once all jobs have been added, thrWait should be called to wait until all jobs have ben completed.

The model used by this module is of a group of people (each person representing a thread), most of which are " workers" whose duty it is to collect jobs from a " job desk" and then go away and perform them, returning to the job desk to report completion of the job and to get a new job. The lists of available jobs, active jobs, etc, are kept at the job desk, and everyone must queue at the job desk to gain access to this information. In order to prevent confusion being caused by different people acccessing the job desk information at the same time, only the person at the head of the queue can access these lists (stored in the workforce structure in reality). This job desk queue is implemented using a mutex - a thread (person) joins the queue by attempting to lock the mutex. At this point the thread blocks (the person waits) until they have reached the head of the queue as indicated by the thrMutexLock call returning. [In fact the queue is not guaranteed to be first-in, first-out - some " queue jumping" may occur as determined by the thread scheduler - but that shouldn’ t matter.]

Two condition variables are used; one is used to signal that new jobs have been placed on the job desk (any idle workers will respond to this signal by rejoining the job desk queue), and the other is used to signal that all jobs have been completed (i.e. no jobs waiting to be started and no active jobs). The person (thread) who added the jobs to the table will respond to this signal by waking up and continuing with whetever else it has to do (which may include submitting more jobs to the job desk).

Invocation

ThrWorkForce ∗thrCreateWorkforce( int nworker, int ∗status )

Arguments

nworker
The number of threads within the new thread pool. If zero, a NULL pointer will be returned without error.
status
Pointer to the inherited status value.

Returned Value

A pointer to a structure describing the new thread pool. The
returned pool should be freed using thrDestroyWorkforce when
no longer needed.