threadpool.h

Upnp开发包文件

///////////////////////////////////////////////////////////////////////////
//
// Copyright (c) 2000-2003 Intel Corporation 
// All rights reserved. 
//
// Redistribution and use in source and binary forms, with or without 
// modification, are permitted provided that the following conditions are met: 
//
// * Redistributions of source code must retain the above copyright notice, 
// this list of conditions and the following disclaimer. 
// * Redistributions in binary form must reproduce the above copyright notice, 
// this list of conditions and the following disclaimer in the documentation 
// and/or other materials provided with the distribution. 
// * Neither name of Intel Corporation nor the names of its contributors 
// may be used to endorse or promote products derived from this software 
// without specific prior written permission.
// 
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR 
// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY 
// OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
///////////////////////////////////////////////////////////////////////////

#ifndef THREADPOOL_H
#define THREADPOOL_H

#ifdef __cplusplus
extern "C" {
#endif

//Size of job free list
#define JOBFREELISTSIZE 100

#define INFINITE_THREADS -1

#define EMAXTHREADS (-8 & 1<<29)

//Invalid Policy
#define INVALID_POLICY (-9 & 1<<29)

//Invalid JOB Id
#define INVALID_JOB_ID (-2 & 1<<29)

typedef enum duration {SHORT_TERM,PERSISTENT} Duration;

typedef enum priority {LOW_PRIORITY,
		       MED_PRIORITY,
		       HIGH_PRIORITY} ThreadPriority;

#define DEFAULT_PRIORITY MED_PRIORITY //default priority used by TPJobInit
#define DEFAULT_MIN_THREADS 1	      //default minimum used by TPAttrInit
#define DEFAULT_MAX_THREADS 10	      //default max used by TPAttrInit	
#define DEFAULT_JOBS_PER_THREAD 10    //default jobs per thread used by TPAttrInit
#define DEFAULT_STARVATION_TIME	500   //default starvation time used by TPAttrInit
#define DEFAULT_IDLE_TIME 10 * 1000   //default idle time used by TPAttrInit
#define DEFAULT_FREE_ROUTINE NULL     //default free routine used TPJobInit 

#define STATS 1 //always include stats because code change is minimal


//Statistics 
#ifdef STATS
#define STATSONLY(x) x
#else
#define STATSONLY(x)
#endif

#ifdef _DEBUG
#define DEBUG 1
#endif

//DEBUGGING
#ifdef DEBUG
#define DBGONLY(x) x
#else
#define DBGONLY(x)
#endif

#include "LinkedList.h"
#include <sys/timeb.h>
#include "FreeList.h"

#include "ithread.h"
#include <errno.h>
#include <sys/timeb.h>
#define EXPORT 
typedef int PolicyType;
#define DEFAULT_POLICY SCHED_OTHER
#define DEFAULT_SCHED_PARAM 0 //default priority

/****************************************************************************
 * Name: free_routine
 *
 *  Description:
 *     Function for freeing a thread argument
 *****************************************************************************/
typedef void (*free_routine)(void *arg);

/****************************************************************************
 * Name: ThreadPoolAttr
 *
 *  Description:
 *     Attributes for thread pool. Used to set and change parameters of 
 *     thread pool
 *****************************************************************************/
typedef struct THREADPOOLATTR
{
  int minThreads; //minThreads, ThreadPool will always maintain at least
                  //this many threads
  
  int maxThreads; //maxThreads, ThreadPool will never have more than this
                  //number of threads
  
  int maxIdleTime;   //maxIdleTime (in milliseconds) 
                     // this is the maximum time a thread will remain idle
                     // before dying

  int jobsPerThread; //jobs per thread to maintain
					  
  int starvationTime;   //the time a low priority or med priority
	                    //job waits before getting bumped
                        //up a priority (in milliseconds)
  
  PolicyType schedPolicy; //scheduling policy to use

} ThreadPoolAttr;

/****************************************************************************
 * Name: ThreadPool
 *
 *  Description:
 *     Internal ThreadPool Job
 *****************************************************************************/
typedef struct THREADPOOLJOB
{
  start_routine func; //function
  void *arg;          //arg
  free_routine free_func; //free function
  struct timeb requestTime; //time of request
  int priority;       //priority of request
  int jobId;         //id 
} ThreadPoolJob;

/****************************************************************************
 * Name: ThreadPoolStats
 *
 *  Description:
 *     Structure to hold statistics
 *****************************************************************************/

STATSONLY(

typedef struct TPOOLSTATS
{
  double totalTimeHQ; //total time spent by all jobs in high priority Q
  int totalJobsHQ;    //total jobs in HQ run so far
  double avgWaitHQ;   //average wait in HQ 
  double totalTimeMQ; //total time spent by all jobs in med priority Q
  int totalJobsMQ;    //total jobs in MQ run so far
  double avgWaitMQ;   //average wait in MQ
  double totalTimeLQ; //total time spent by all jobs in low priority Q
  int totalJobsLQ;    //total jobs in LQ run so far
  double avgWaitLQ;	//average wait in LQ	
  double totalWorkTime; //total time spent working for all threads
  double totalIdleTime; //total time spent idle for all threads
  int workerThreads; //number of current workerThreads
  int idleThreads;   //number of current idle threads
  int persistentThreads; //number of persistent threads
  int totalThreads; //total number of current threads
  int maxThreads; //max threads so far	
  int currentJobsHQ; // current jobs in Q
  int currentJobsLQ; //current jobs in Q
  int currentJobsMQ; //current jobs in Q
}ThreadPoolStats;

)


/****************************************************************************
 * Name: ThreadPool
 *
 *  Description:
 *     A thread pool similar to the thread pool in the UPnP SDK.
 *     Allows jobs to be scheduled for running by threads in a 
 *     thread pool. The thread pool is initialized with a 
 *     minimum and maximum thread number as well as a 
 *	   max idle time
 *     and a jobs per thread ratio. If a worker thread waits the whole
 *     max idle time without receiving a job and the thread pool
 *     currently has more threads running than the minimum
 *     then the worker thread will exit. If when 
 *     scheduling a job the current job to thread ratio
 *     becomes greater than the set ratio and the thread pool currently has
 *     less than the maximum threads then a new thread will
 *     be created.
 *
 *****************************************************************************/

typedef struct THREADPOOL
{
  ithread_mutex_t mutex; //mutex to protect job qs
  ithread_cond_t condition; //condition variable to signal Q
  ithread_cond_t start_and_shutdown; //condition variable for start 
                                     //and stop     
  int lastJobId; //ids for jobs 
  int shutdown;   //whether or not we are shutting down
  int totalThreads;       //total number of threads	
  int persistentThreads; //number of persistent threads
  FreeList jobFreeList; //free list of jobs
  LinkedList lowJobQ;    //low priority job Q
  LinkedList medJobQ;    //med priority job Q
  LinkedList highJobQ;   //high priority job Q
  ThreadPoolJob *persistentJob; //persistent job
 
  ThreadPoolAttr attr; //thread pool attributes
  
  //statistics 
  STATSONLY(ThreadPoolStats stats;)
 
} ThreadPool;



/****************************************************************************
 * Function: ThreadPoolInit
 *
 *  Description:
 *      Initializes and starts ThreadPool. Must be called first.
 *      And only once for ThreadPool.
 *  Parameters:
 *      tp  - must be valid, non null, pointer to ThreadPool.
 *      attr - can be null
 *
 *       if not null then attr contains the following fields:
 *
 *      minWorkerThreads - minimum number of worker threads
 *                                 thread pool will never have less than this
 *                                  number of threads.
 *      maxWorkerThreads - maximum number of worker threads
 *                         thread pool will never have more than this
 *                         number of threads.
 *      maxIdleTime      - maximum time that a worker thread will spend
 *                         idle. If a worker is idle longer than this
 *                         time and there are more than the min
 *                         number of workers running, than the
 *                         worker thread exits.
 *      jobsPerThread    - ratio of jobs to thread to try and maintain
 *                         if a job is scheduled and the number of jobs per
 *                         thread is greater than this number,and  
 *                         if less than the maximum number of
 *                         workers are running then a new thread is 
 *                         started to help out with efficiency.
 *      schedPolicy      - scheduling policy to try and set (OS dependent)
 *  Returns:
 *      0 on success, nonzero on failure.
 *      EAGAIN if not enough system resources to create minimum threads.
 *      INVALID_POLICY if schedPolicy can't be set
 *      EMAXTHREADS if minimum threads is greater than maximum threads
 *****************************************************************************/
int ThreadPoolInit(ThreadPool *tp,
  ThreadPoolAttr *attr);