ThreadPool.h File Reference
`#include "FreeList.h"`
`#include "ithread.h"`
`#include "LinkedList.h"`
`#include "UpnpInet.h"`
`#include "UpnpGlobal.h"`
`#include <errno.h>`
`#include <sys/param.h>`
`#include <sys/time.h>`
Include dependency graph for ThreadPool.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Data Structures

struct | THREADPOOLATTR
struct | THREADPOOLJOB
struct | TPOOLSTATS
struct | THREADPOOL
| A thread pool similar to the thread pool in the UPnP SDK. More...

## Macros

#define | JOBFREELISTSIZE 100
#define | INFINITE_THREADS -1
#define | EMAXTHREADS (-8 & 1<<29)
#define | INVALID_POLICY (-9 & 1<<29)
#define | INVALID_JOB_ID (-2 & 1<<29)
#define | DEFAULT_PRIORITY MED_PRIORITY
#define | DEFAULT_MIN_THREADS 1
#define | DEFAULT_MAX_THREADS 10
#define | DEFAULT_STACK_SIZE 0u
#define | DEFAULT_JOBS_PER_THREAD 10
#define | DEFAULT_STARVATION_TIME 500
#define | DEFAULT_IDLE_TIME 10 * 1000
#define | DEFAULT_FREE_ROUTINE NULL
#define | DEFAULT_MAX_JOBS_TOTAL 100
#define | STATS 1
| Statistics. More...
#define | DEFAULT_POLICY SCHED_OTHER

## Typedefs

typedef enum duration | Duration
typedef enum priority | ThreadPriority
typedef int | PolicyType
typedef void(* | free_routine) (void *arg)
typedef struct THREADPOOLATTR | ThreadPoolAttr
typedef struct THREADPOOLJOB | ThreadPoolJob
typedef struct TPOOLSTATS | ThreadPoolStats
typedef struct THREADPOOL | ThreadPool
| A thread pool similar to the thread pool in the UPnP SDK. More...

## Enumerations

enum | duration { SHORT_TERM, PERSISTENT }
enum | priority { LOW_PRIORITY, MED_PRIORITY, HIGH_PRIORITY }

## Functions

int | ThreadPoolInit (ThreadPool *tp, ThreadPoolAttr *attr)
| Initializes and starts ThreadPool. Must be called first and only once for ThreadPool. More...
int | ThreadPoolAddPersistent (ThreadPool *tp, ThreadPoolJob *job, int *jobId)
| Adds a persistent job to the thread pool. More...
int | ThreadPoolGetAttr (ThreadPool *tp, ThreadPoolAttr *out)
| Gets the current set of attributes associated with the thread pool. More...
int | ThreadPoolSetAttr (ThreadPool *tp, ThreadPoolAttr *attr)
| Sets the attributes for the thread pool. Only affects future calculations. More...
int | ThreadPoolAdd (ThreadPool *tp, ThreadPoolJob *job, int *jobId)
| Adds a job to the thread pool. Job will be run as soon as possible. More...
int | ThreadPoolRemove (ThreadPool *tp, int jobId, ThreadPoolJob *out)
| Removes a job from the thread pool. Can only remove jobs which are not currently running. More...
int | ThreadPoolShutdown (ThreadPool *tp)
| Shuts the thread pool down. Waits for all threads to finish. May block indefinitely if jobs do not exit. More...
int | TPJobInit (ThreadPoolJob *job, start_routine func, void *arg)
| Initializes thread pool job. Sets the priority to default defined in ThreadPool.h. Sets the free_routine to default defined in ThreadPool.h. More...
int | TPJobSetPriority (ThreadPoolJob *job, ThreadPriority priority)
| Sets the max threads for the thread pool attributes. More...
int | TPJobSetFreeFunction (ThreadPoolJob *job, free_routine func)
| Sets the max threads for the thread pool attributes. More...
int | TPAttrInit (ThreadPoolAttr *attr)
| Initializes thread pool attributes. Sets values to defaults defined in ThreadPool.h. More...
int | TPAttrSetMaxThreads (ThreadPoolAttr *attr, int maxThreads)
| Sets the max threads for the thread pool attributes. More...
int | TPAttrSetMinThreads (ThreadPoolAttr *attr, int minThreads)
| Sets the min threads for the thread pool attributes. More...
int | TPAttrSetStackSize (ThreadPoolAttr *attr, size_t stackSize)
| Sets the stack size for the thread pool attributes. More...
int | TPAttrSetIdleTime (ThreadPoolAttr *attr, int idleTime)
| Sets the idle time for the thread pool attributes. More...
int | TPAttrSetJobsPerThread (ThreadPoolAttr *attr, int jobsPerThread)
| Sets the jobs per thread ratio. More...
int | TPAttrSetStarvationTime (ThreadPoolAttr *attr, int starvationTime)
| Sets the starvation time for the thread pool attributes. More...
int | TPAttrSetSchedPolicy (ThreadPoolAttr *attr, PolicyType schedPolicy)
| Sets the scheduling policy for the thread pool attributes. More...
int | TPAttrSetMaxJobsTotal (ThreadPoolAttr *attr, int maxJobsTotal)
| Sets the maximum number jobs that can be qeued totally. More...
int | ThreadPoolGetStats (ThreadPool *tp, ThreadPoolStats *stats)
| Returns various statistics about the thread pool. More...
void | ThreadPoolPrintStats (ThreadPoolStats *stats)

## Macro Definition Documentation

## DEFAULT_FREE_ROUTINE

#define DEFAULT_FREE_ROUTINE NULL

default free routine used TPJobInit

## DEFAULT_IDLE_TIME

#define DEFAULT_IDLE_TIME 10 * 1000

default idle time used by TPAttrInit

Referenced by TPAttrInit().

## DEFAULT_JOBS_PER_THREAD

#define DEFAULT_JOBS_PER_THREAD 10

default jobs per thread used by TPAttrInit

Referenced by TPAttrInit().

## DEFAULT_MAX_JOBS_TOTAL

#define DEFAULT_MAX_JOBS_TOTAL 100

default max jobs used TPAttrInit

## DEFAULT_MAX_THREADS

#define DEFAULT_MAX_THREADS 10

default max used by TPAttrInit

Referenced by TPAttrInit().

## DEFAULT_MIN_THREADS

#define DEFAULT_MIN_THREADS 1

default minimum used by TPAttrInit

Referenced by TPAttrInit().

## DEFAULT_PRIORITY

#define DEFAULT_PRIORITY MED_PRIORITY

default priority used by TPJobInit

## DEFAULT_STACK_SIZE

#define DEFAULT_STACK_SIZE 0u

default stack size used by TPAttrInit

Referenced by TPAttrInit().

## DEFAULT_STARVATION_TIME

#define DEFAULT_STARVATION_TIME 500

default starvation time used by TPAttrInit

## INVALID_JOB_ID

#define INVALID_JOB_ID (-2 & 1<<29)

Invalid JOB Id

Referenced by ThreadPoolAddPersistent(), and ThreadPoolRemove().

## INVALID_POLICY

#define INVALID_POLICY (-9 & 1<<29)

Invalid Policy

## JOBFREELISTSIZE

#define JOBFREELISTSIZE 100

Size of job free list

## STATS

#define STATS 1

Statistics.

Always include stats because code change is minimal.

## Typedef Documentation

## free_routine

typedef void(* free_routine) (void *arg)

Function for freeing a thread argument.

## ThreadPool

typedef struct THREADPOOL ThreadPool

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.

## ThreadPoolAttr

typedef struct THREADPOOLATTR ThreadPoolAttr

Attributes for thread pool. Used to set and change parameters of thread pool.

## ThreadPoolJob

typedef struct THREADPOOLJOB ThreadPoolJob

Internal ThreadPool Job.

## ThreadPoolStats

typedef struct TPOOLSTATS ThreadPoolStats

Structure to hold statistics.

## Function Documentation

## ThreadPoolAdd()

int ThreadPoolAdd | ( | ThreadPool * | tp,
|  | ThreadPoolJob * | job,
|  | int * | jobId
| ) |  |

Adds a job to the thread pool. Job will be run as soon as possible.

Returns
  - `0` on success, nonzero on failure.
  - `EOUTOFMEM` if not enough memory to add job.

Parameters

  tp | valid thread pool pointer.
  job | .
  jobId | id of job.

## ThreadPoolAddPersistent()

int ThreadPoolAddPersistent | ( | ThreadPool * | tp,
|  | ThreadPoolJob * | job,
|  | int * | jobId
| ) |  |

Adds a persistent job to the thread pool.

Job will be run as soon as possible. Call will block until job is scheduled.

Returns
  - `0` on success.
  - `EOUTOFMEM` not enough memory to add job.
  - `EMAXTHREADS` not enough threads to add persistent job.

Parameters

  tp | Valid thread pool pointer.
  job | Valid thread pool job.
  jobId | .

References INVALID_JOB_ID.

## ThreadPoolGetAttr()

int ThreadPoolGetAttr | ( | ThreadPool * | tp,
|  | ThreadPoolAttr * | out
| ) |  |

Gets the current set of attributes associated with the thread pool.

Returns
  - `0` on success, nonzero on failure.

Parameters

  tp | valid thread pool pointer.
  out | non null pointer to store attributes.

References THREADPOOL::shutdown.

## ThreadPoolGetStats()

int ThreadPoolGetStats | ( | ThreadPool * | tp,
|  | ThreadPoolStats * | stats
| ) |  |

Returns various statistics about the thread pool.

Only valid if STATS has been defined.

Returns
  Always returns 0.

Parameters

  tp | Valid initialized threadpool.
  stats | Valid stats, out parameter.

References THREADPOOL::shutdown.

Referenced by PrintThreadPoolStats().

## ThreadPoolInit()

int ThreadPoolInit | ( | ThreadPool * | tp,
|  | ThreadPoolAttr * | attr
| ) |  |

Initializes and starts ThreadPool. Must be called first and only once for ThreadPool.

Returns
  - `0` on success.
  - `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.

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, then 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).

Referenced by UpnpInitThreadPools().

## ThreadPoolPrintStats()

void ThreadPoolPrintStats | ( | ThreadPoolStats * | stats | ) |

Parameters

  stats | .

References StatsTime().

## ThreadPoolRemove()

int ThreadPoolRemove | ( | ThreadPool * | tp,
|  | int | jobId,
|  | ThreadPoolJob * | out
| ) |  |

Removes a job from the thread pool. Can only remove jobs which are not currently running.

Returns
  - `0` on success, nonzero on failure.
  - `INVALID_JOB_ID` if job not found.

Parameters

  tp | valid thread pool pointer.
  jobId | id of job.
  out | space for removed job.

References INVALID_JOB_ID.

## ThreadPoolSetAttr()

int ThreadPoolSetAttr | ( | ThreadPool * | tp,
|  | ThreadPoolAttr * | attr
| ) |  |

Sets the attributes for the thread pool. Only affects future calculations.

Returns
  - `0` on success, nonzero on failure.
  - `INVALID_POLICY` if policy can not be set.

Parameters

  tp | valid thread pool pointer.
  attr | pointer to attributes, null sets attributes to default.

## ThreadPoolShutdown()

int ThreadPoolShutdown | ( | ThreadPool * | tp | ) |

Shuts the thread pool down. Waits for all threads to finish. May block indefinitely if jobs do not exit.

Returns
  0 on success, nonzero on failure

Parameters

  tp | must be valid tp.

## TPAttrInit()

int TPAttrInit | ( | ThreadPoolAttr * | attr | ) |

Initializes thread pool attributes. Sets values to defaults defined in ThreadPool.h.

Returns
  Always returns 0.

Parameters

  attr | must be valid thread pool attributes.

References DEFAULT_IDLE_TIME, DEFAULT_JOBS_PER_THREAD, DEFAULT_MAX_THREADS, DEFAULT_MIN_THREADS, DEFAULT_STACK_SIZE, THREADPOOLATTR::jobsPerThread, THREADPOOLATTR::maxIdleTime, THREADPOOLATTR::maxThreads, THREADPOOLATTR::minThreads, THREADPOOLATTR::schedPolicy, and THREADPOOLATTR::stackSize.

Referenced by UpnpInitThreadPools().

## TPAttrSetIdleTime()

int TPAttrSetIdleTime | ( | ThreadPoolAttr * | attr,
|  | int | idleTime
| ) |  |

Sets the idle time for the thread pool attributes.

Returns
  Always returns 0.

Parameters

  attr | must be valid thread pool attributes.
  idleTime | .

References THREADPOOLATTR::maxIdleTime.

Referenced by UpnpInitThreadPools().

## TPAttrSetJobsPerThread()

int TPAttrSetJobsPerThread | ( | ThreadPoolAttr * | attr,
|  | int | jobsPerThread
| ) |  |

Sets the jobs per thread ratio.

Returns
  Always returns 0.

Parameters

  attr | must be valid thread pool attributes.
  jobsPerThread | number of jobs per thread to maintain.

References THREADPOOLATTR::jobsPerThread.

Referenced by UpnpInitThreadPools().

## TPAttrSetMaxJobsTotal()

int TPAttrSetMaxJobsTotal | ( | ThreadPoolAttr * | attr,
|  | int | maxJobsTotal
| ) |  |

Sets the maximum number jobs that can be qeued totally.

Returns
  Always returns 0.

Parameters

  attr | must be valid thread pool attributes.
  maxJobsTotal | maximum number of jobs.

References THREADPOOLATTR::maxJobsTotal.

Referenced by UpnpInitThreadPools().

## TPAttrSetMaxThreads()

int TPAttrSetMaxThreads | ( | ThreadPoolAttr * | attr,
|  | int | maxThreads
| ) |  |

Sets the max threads for the thread pool attributes.

Returns
  Always returns 0.

Parameters

  attr | must be valid thread pool attributes.
  maxThreads | value to set.

References THREADPOOLATTR::maxThreads.

Referenced by UpnpInitThreadPools().

## TPAttrSetMinThreads()

int TPAttrSetMinThreads | ( | ThreadPoolAttr * | attr,
|  | int | minThreads
| ) |  |

Sets the min threads for the thread pool attributes.

Returns
  Always returns 0.

Parameters

  attr | must be valid thread pool attributes.
  minThreads | value to set.

References THREADPOOLATTR::minThreads.

Referenced by UpnpInitThreadPools().

## TPAttrSetSchedPolicy()

int TPAttrSetSchedPolicy | ( | ThreadPoolAttr * | attr,
|  | PolicyType | schedPolicy
| ) |  |

Sets the scheduling policy for the thread pool attributes.

Returns
  Always returns 0.

Parameters

  attr | must be valid thread pool attributes.
  schedPolicy | must be a valid policy type.

References THREADPOOLATTR::schedPolicy.

## TPAttrSetStackSize()

int TPAttrSetStackSize | ( | ThreadPoolAttr * | attr,
|  | size_t | stackSize
| ) |  |

Sets the stack size for the thread pool attributes.

Returns
  Always returns 0.

Parameters

  attr | must be valid thread pool attributes.
  stackSize | value to set.

References THREADPOOLATTR::stackSize.

Referenced by UpnpInitThreadPools().

## TPAttrSetStarvationTime()

int TPAttrSetStarvationTime | ( | ThreadPoolAttr * | attr,
|  | int | starvationTime
| ) |  |

Sets the starvation time for the thread pool attributes.

Returns
  Always returns 0.

Parameters

  attr | must be valid thread pool attributes.
  starvationTime | milliseconds.

References THREADPOOLATTR::starvationTime.

## TPJobInit()

int TPJobInit | ( | ThreadPoolJob * | job,
|  | start_routine | func,
|  | void * | arg
| ) |  |

Initializes thread pool job. Sets the priority to default defined in ThreadPool.h. Sets the free_routine to default defined in ThreadPool.h.

Returns
  Always returns 0.

Parameters

  job | must be valid thread pool attributes.
  func | function to run, must be valid.
  arg | argument to pass to function.

## TPJobSetFreeFunction()

int TPJobSetFreeFunction | ( | ThreadPoolJob * | job,
|  | free_routine | func
| ) |  |

Sets the max threads for the thread pool attributes.

Returns
  Always returns 0.

Parameters

  job | must be valid thread pool attributes.
  func | value to set.

## TPJobSetPriority()

int TPJobSetPriority | ( | ThreadPoolJob * | job,
|  | ThreadPriority | priority
| ) |  |

Sets the max threads for the thread pool attributes.

Returns
  Always returns 0.

Parameters

  job | must be valid thread pool attributes.
  priority | value to set.