Manage a threadpool (for internal use only). More...

#include "LinkedList.hpp"
#include <UPnPsdk/port_sock.hpp>

Include dependency graph for ThreadPool.hpp:

This graph shows which files directly or indirectly include this file:

Classes
struct	timezone
	Timezone. More...

struct	ThreadPoolAttr
	Attributes for thread pool. More...

struct	ThreadPoolJob
	Internal ThreadPool Job. More...

struct	ThreadPoolStats
	Structure to hold statistics. More...

struct	ThreadPool
	A thread pool. More...

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

#define	STATS 1
	Statistics.

#define	DEFAULT_POLICY SCHED_OTHER
	Define default schedule policy that are defined in <sched.h>.

Typedefs
typedef void(*	free_routine) (void *arg)

typedef int	PolicyType
	Type of the thread policy.

Enumerations
enum	Duration { SHORT_TERM , PERSISTENT }
	Duration. More...

enum	ThreadPriority { LOW_PRIORITY , MED_PRIORITY , HIGH_PRIORITY }
	Thread priority. More...

Functions
int	gettimeofday (struct timeval tv, struct timezone tz)
	Get time of day.

void	TPSetMaxJobsTotal (int mjt)
	Sets the maximum number of jobs in the thread pool.

int	ThreadPoolInit (ThreadPool tp, ThreadPoolAttr attr)
	Initializes and starts ThreadPool.

int	ThreadPoolAddPersistent (ThreadPool tp, ThreadPoolJob job, int *jobId)
	Adds a persistent job to the thread pool.

int	ThreadPoolGetAttr (ThreadPool tp, ThreadPoolAttr out)
	Gets the current set of attributes associated with the thread pool.

int	ThreadPoolSetAttr (ThreadPool tp, ThreadPoolAttr attr)
	Sets the attributes for the thread pool.

int	ThreadPoolAdd (ThreadPool tp, ThreadPoolJob job, int *jobId)
	Adds a job to the thread pool.

int	ThreadPoolRemove (ThreadPool tp, int jobId, ThreadPoolJob out)
	Removes a job from the thread pool.

int	ThreadPoolShutdown (ThreadPool *tp)
	Shuts the thread pool down.

int	TPJobInit (ThreadPoolJob job, UPnPsdk::start_routine func, void arg)
	Initializes thread pool job.

int	TPJobSetPriority (ThreadPoolJob *job, ThreadPriority priority)
	Sets the priority of the threadpool job.

int	TPJobSetFreeFunction (ThreadPoolJob *job, free_routine func)
	Sets the jobs free function.

int	TPAttrInit (ThreadPoolAttr *attr)
	Initializes thread pool attributes.

int	TPAttrSetMaxThreads (ThreadPoolAttr *attr, int maxThreads)
	Sets the max threads for the thread pool attributes.

int	TPAttrSetMinThreads (ThreadPoolAttr *attr, int minThreads)
	Sets the min threads for the thread pool attributes.

int	TPAttrSetStackSize (ThreadPoolAttr *attr, size_t stackSize)
	Sets the stack size for the thread pool attributes.

int	TPAttrSetIdleTime (ThreadPoolAttr *attr, int idleTime)
	Sets the idle time for the thread pool attributes.

int	TPAttrSetJobsPerThread (ThreadPoolAttr *attr, int jobsPerThread)
	Sets the jobs per thread ratio.

int	TPAttrSetStarvationTime (ThreadPoolAttr *attr, int starvationTime)
	Sets the starvation time for the thread pool attributes.

int	TPAttrSetSchedPolicy (ThreadPoolAttr *attr, PolicyType schedPolicy)
	Sets the scheduling policy for the thread pool attributes.

int	TPAttrSetMaxJobsTotal (ThreadPoolAttr *attr, int totalMaxJobs)
	Sets the maximum number jobs that can be qeued totally.

int	ThreadPoolGetStats (ThreadPool tp, ThreadPoolStats stats)
	Returns various statistics about the thread pool.

void	ThreadPoolPrintStats (ThreadPoolStats *stats)
	Prints various statistics about the thread pool to stderr.

Variables
constexpr ThreadPriority	DEFAULT_PRIORITY {MED_PRIORITY}

constexpr int	DEFAULT_MIN_THREADS {1}

constexpr int	DEFAULT_MAX_THREADS {10}

constexpr int	DEFAULT_STACK_SIZE {0u}

constexpr int	DEFAULT_JOBS_PER_THREAD {10}

constexpr int	DEFAULT_STARVATION_TIME {500}

constexpr int	DEFAULT_IDLE_TIME {10 * 1000}

constexpr free_routine	DEFAULT_FREE_ROUTINE {nullptr}

constexpr int	DEFAULT_MAX_JOBS_TOTAL {100}

int	maxJobsTotal

Detailed Description

Manage a threadpool (for internal use only).

Because this is for internal use, parameters are NOT checked for validity. The caller must ensure valid parameters.

Definition in file ThreadPool.hpp.

Class Documentation

◆ timezone

struct timezone

Timezone.

Definition at line 52 of file ThreadPool.hpp.

Class Members
int	tz_minuteswest	Minutes W of Greenwich.
int	tz_dsttime	Type of dst correction.

◆ ThreadPoolAttr

struct ThreadPoolAttr

Attributes for thread pool.

Used to set and change parameters of thread pool.

Definition at line 128 of file ThreadPool.hpp.

Class Members
int	minThreads	ThreadPool will always maintain at least this many threads.
int	maxThreads	ThreadPool will never have more than this number of threads.
size_t	stackSize	This is the minimum stack size allocated for each thread.
int	maxIdleTime	this is the maximum time a thread will remain idle before dying (in milliseconds).
int	jobsPerThread	Jobs per thread to maintain.
int	maxJobsTotal	Maximum number of jobs that can be queued totally.
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.

◆ ThreadPoolJob

struct ThreadPoolJob

Internal ThreadPool Job.

Definition at line 150 of file ThreadPool.hpp.

Class Members
start_routine	func
void *	arg
free_routine	free_func
struct timeval	requestTime
ThreadPriority	priority
int	jobId

◆ ThreadPoolStats

struct ThreadPoolStats

Structure to hold statistics.

Definition at line 160 of file ThreadPool.hpp.

Class Members
double	totalTimeHQ
int	totalJobsHQ
double	avgWaitHQ
double	totalTimeMQ
int	totalJobsMQ
double	avgWaitMQ
double	totalTimeLQ
int	totalJobsLQ
double	avgWaitLQ
double	totalWorkTime
double	totalIdleTime
int	workerThreads
int	idleThreads
int	persistentThreads
int	totalThreads
int	maxThreads
int	currentJobsHQ
int	currentJobsLQ
int	currentJobsMQ

◆ ThreadPool

struct ThreadPool

A thread pool.

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.

Definition at line 194 of file ThreadPool.hpp.

Collaboration diagram for ThreadPool:

Class Members
pthread_mutex_t	mutex	Mutex to protect job qs.
pthread_cond_t	condition	Condition variable to signal Q.
pthread_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	pendingWorkerThreadStart	flag that's set when waiting for a new worker thread to start
int	busyThreads	number of threads that are currently executing jobs
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
ThreadPoolStats	stats	statistics

Macro Definition Documentation

◆ INVALID_JOB_ID

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

Invalid JOB Id.

Definition at line 68 of file ThreadPool.hpp.

◆ STATS

#define STATS 1

Statistics.

Always include stats because code change is minimal.

Definition at line 113 of file ThreadPool.hpp.

◆ DEFAULT_POLICY

#define DEFAULT_POLICY SCHED_OTHER

Define default schedule policy that are defined in <sched.h>.

Definition at line 123 of file ThreadPool.hpp.

Typedef Documentation

◆ free_routine

typedef void(* free_routine) (void *arg)

Function for freeing a thread argument.

Definition at line 71 of file ThreadPool.hpp.

◆ PolicyType

typedef int PolicyType

Type of the thread policy.

Definition at line 120 of file ThreadPool.hpp.

Enumeration Type Documentation

◆ Duration

enum Duration

Duration.

Definition at line 74 of file ThreadPool.hpp.

◆ ThreadPriority

enum ThreadPriority

Thread priority.

Definition at line 77 of file ThreadPool.hpp.

Function Documentation

◆ gettimeofday()

int gettimeofday	(	struct timeval *	tv,
		struct timezone *	tz
	)

Get time of day.

Definition at line 1211 of file ThreadPool.cpp.

Here is the caller graph for this function:

◆ TPSetMaxJobsTotal()

void TPSetMaxJobsTotal ( int mjt )

Sets the maximum number of jobs in the thread pool.

This option is intended for server applications to avoid an overflow of jobs when serving e.g. many web requests.

Definition at line 1026 of file ThreadPool.cpp.

Here is the caller graph for this function:

◆ ThreadPoolInit()

int ThreadPoolInit	(	ThreadPool *	tp,
		ThreadPoolAttr *	attr
	)

Initializes and starts ThreadPool.

Must be called first and only once for ThreadPool.

Returns

On success: 0
On error:

EINVAL with invalid ThreadPool.
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

[in]	tp	Must be valid, non null, pointer to ThreadPool.
[in]	attr	Can be nullptr. If not nullptr 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).

Definition at line 669 of file ThreadPool.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ 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

On success: 0
On error:

EOUTOFMEM not enough memory to add job.
EMAXTHREADS not enough threads to add persistent job.

Parameters

[in]	tp	Valid thread pool pointer.
[in]	job	Valid thread pool job.
[in]	jobId	Job ID

Definition at line 737 of file ThreadPool.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ThreadPoolGetAttr()

int ThreadPoolGetAttr	(	ThreadPool *	tp,
		ThreadPoolAttr *	out
	)

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

Returns: On success: 0
On error: nonzero

Parameters

[in]	tp	Valid thread pool pointer.
[in]	out	Non null pointer to store attributes.

Definition at line 892 of file ThreadPool.cpp.

◆ ThreadPoolSetAttr()

int ThreadPoolSetAttr	(	ThreadPool *	tp,
		ThreadPoolAttr *	attr
	)

Sets the attributes for the thread pool.

Only affects future calculations.

Returns

On success: 0
On error: nonzero

INVALID_POLICY if policy can not be set.

Parameters

[in]	tp	Valid thread pool pointer.
[in]	attr	Pointer to attributes, null sets attributes to default.

Definition at line 904 of file ThreadPool.cpp.

Here is the call graph for this function:

◆ 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

On success: 0
On error: nonzero

EOUTOFMEM if not enough memory to add job.

Parameters

[in]	tp	Valid thread pool pointer.
[in]	job	Job
[in]	jobId	id of job.

Definition at line 784 of file ThreadPool.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ 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

On success: 0
On error: nonzero

INVALID_JOB_ID if job not found.

Parameters

[in]	tp	Valid thread pool pointer.
[in]	jobId	Id of job.
[out]	out	Space for removed job.

Definition at line 836 of file ThreadPool.cpp.

Here is the call graph for this function:

◆ 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: On success: 0
On error: nonzero

Parameters

[in] tp Must be valid tp.

Definition at line 944 of file ThreadPool.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ TPJobInit()

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

Initializes thread pool job.

Sets the priority to default defined in ThreadPool.hpp. Sets the free_routine to default defined in ThreadPool.hpp.

Returns: Always 0.

Parameters

[in]	job	Must be valid thread pool attributes.
[in]	func	Function to run, must be valid.
[in]	arg	Argument to pass to function.

Definition at line 1043 of file ThreadPool.cpp.

Here is the caller graph for this function:

◆ TPJobSetPriority()

int TPJobSetPriority	(	ThreadPoolJob *	job,
		ThreadPriority	priority
	)

Sets the priority of the threadpool job.

Returns: On success: 0
On error: EINVAL.

Parameters

[in]	job	Must be valid thread pool attributes.
[in]	priority	Value to set.

Definition at line 1054 of file ThreadPool.cpp.

Here is the caller graph for this function:

◆ TPJobSetFreeFunction()

int TPJobSetFreeFunction	(	ThreadPoolJob *	job,
		free_routine	func
	)

Sets the jobs free function.

Returns: On success: 0
On error: EINVAL.

Parameters

[in]	job	Must be valid thread pool attributes.
[in]	func	Value to set.

Definition at line 1068 of file ThreadPool.cpp.

Here is the caller graph for this function:

◆ TPAttrInit()

int TPAttrInit ( ThreadPoolAttr * attr )

Initializes thread pool attributes.

Sets values to defaults defined in ThreadPool.hpp.

Returns: On success: 0
On error: EINVAL.

Parameters

[in] attr Must be valid thread pool attributes.

Definition at line 1028 of file ThreadPool.cpp.

Here is the caller graph for this function:

◆ TPAttrSetMaxThreads()

int TPAttrSetMaxThreads	(	ThreadPoolAttr *	attr,
		int	maxThreads
	)

Sets the max threads for the thread pool attributes.

Returns: On success: 0
On error: EINVAL.

Parameters

[in]	attr	Must be valid thread pool attributes.
[in]	maxThreads	Value to set.

Definition at line 1076 of file ThreadPool.cpp.

Here is the caller graph for this function:

◆ TPAttrSetMinThreads()

int TPAttrSetMinThreads	(	ThreadPoolAttr *	attr,
		int	minThreads
	)

Sets the min threads for the thread pool attributes.

Returns: On success: 0
On error: EINVAL.

Parameters

[in]	attr	must be valid thread pool attributes.
[in]	minThreads	value to set.

Definition at line 1084 of file ThreadPool.cpp.

Here is the caller graph for this function:

◆ TPAttrSetStackSize()

int TPAttrSetStackSize	(	ThreadPoolAttr *	attr,
		size_t	stackSize
	)

Sets the stack size for the thread pool attributes.

Returns: On success: 0
On error: EINVAL.

Parameters

[in]	attr	Must be valid thread pool attributes.
[in]	stackSize	Value to set.

Definition at line 1092 of file ThreadPool.cpp.

Here is the caller graph for this function:

◆ TPAttrSetIdleTime()

int TPAttrSetIdleTime	(	ThreadPoolAttr *	attr,
		int	idleTime
	)

Sets the idle time for the thread pool attributes.

Returns: On success: 0
On error: EINVAL.

Parameters

[in]	attr	Must be valid thread pool attributes.
[in]	idleTime	Idle time

Definition at line 1100 of file ThreadPool.cpp.

Here is the caller graph for this function:

◆ TPAttrSetJobsPerThread()

int TPAttrSetJobsPerThread	(	ThreadPoolAttr *	attr,
		int	jobsPerThread
	)

Sets the jobs per thread ratio.

Returns: On success: 0
On error: EINVAL.

Parameters

[in]	attr	Must be valid thread pool attributes.
[in]	jobsPerThread	Number of jobs per thread to maintain.

Definition at line 1108 of file ThreadPool.cpp.

Here is the caller graph for this function:

◆ TPAttrSetStarvationTime()

int TPAttrSetStarvationTime	(	ThreadPoolAttr *	attr,
		int	starvationTime
	)

Sets the starvation time for the thread pool attributes.

Returns: On success: 0
On error: EINVAL.

Parameters

[in]	attr	Must be valid thread pool attributes.
[in]	starvationTime	Milliseconds.

Definition at line 1116 of file ThreadPool.cpp.

◆ TPAttrSetSchedPolicy()

int TPAttrSetSchedPolicy	(	ThreadPoolAttr *	attr,
		PolicyType	schedPolicy
	)

Sets the scheduling policy for the thread pool attributes.

Returns: On success: 0
On error: EINVAL.

Parameters

[in]	attr	Must be valid thread pool attributes.
[in]	schedPolicy	Must be a valid policy type.

Definition at line 1124 of file ThreadPool.cpp.

◆ TPAttrSetMaxJobsTotal()

int TPAttrSetMaxJobsTotal	(	ThreadPoolAttr *	attr,
		int	totalMaxJobs
	)

Sets the maximum number jobs that can be qeued totally.

Returns: On success: 0
On error: EINVAL.

Parameters

[in]	attr	Must be valid thread pool attributes.
[in]	totalMaxJobs	Maximum number of jobs.

Definition at line 1132 of file ThreadPool.cpp.

Here is the caller graph for this function:

◆ ThreadPoolGetStats()

int ThreadPoolGetStats	(	ThreadPool *	tp,
		ThreadPoolStats *	stats
	)

Returns various statistics about the thread pool.

Only valid if STATS has been defined.

Returns: On success: 0
On error: EINVAL.

Parameters

[in]	tp	Valid initialized threadpool.
[out]	stats	Valid stats, out parameter.

Definition at line 1168 of file ThreadPool.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ThreadPoolPrintStats()

void ThreadPoolPrintStats ( ThreadPoolStats * stats )

Prints various statistics about the thread pool to stderr.

Only valid if STATS has been defined.

Parameters

[in] stats Valid threadpool stats

Definition at line 1141 of file ThreadPool.cpp.

Here is the call graph for this function:

Variable Documentation

◆ DEFAULT_PRIORITY

constexpr ThreadPriority DEFAULT_PRIORITY {MED_PRIORITY}

constexpr

default priority used by TPJobInit

Definition at line 80 of file ThreadPool.hpp.

◆ DEFAULT_MIN_THREADS

constexpr int DEFAULT_MIN_THREADS {1}

constexpr

default minimum used by TPAttrInit

Definition at line 83 of file ThreadPool.hpp.

◆ DEFAULT_MAX_THREADS

constexpr int DEFAULT_MAX_THREADS {10}

constexpr

default max used by TPAttrInit

Definition at line 86 of file ThreadPool.hpp.

◆ DEFAULT_STACK_SIZE

constexpr int DEFAULT_STACK_SIZE {0u}

constexpr

default stack size used by TPAttrInit

Definition at line 89 of file ThreadPool.hpp.

◆ DEFAULT_JOBS_PER_THREAD

constexpr int DEFAULT_JOBS_PER_THREAD {10}

constexpr

default jobs per thread used by TPAttrInit

Definition at line 92 of file ThreadPool.hpp.

◆ DEFAULT_STARVATION_TIME

constexpr int DEFAULT_STARVATION_TIME {500}

constexpr

default starvation time used by TPAttrInit

Definition at line 95 of file ThreadPool.hpp.

◆ DEFAULT_IDLE_TIME

constexpr int DEFAULT_IDLE_TIME {10 * 1000}

constexpr

default idle time used by TPAttrInit

Definition at line 98 of file ThreadPool.hpp.

◆ DEFAULT_FREE_ROUTINE

constexpr free_routine DEFAULT_FREE_ROUTINE {nullptr}

constexpr

default free routine used TPJobInit

Definition at line 101 of file ThreadPool.hpp.

◆ DEFAULT_MAX_JOBS_TOTAL

constexpr int DEFAULT_MAX_JOBS_TOTAL {100}

constexpr

default max jobs used TPAttrInit

Definition at line 104 of file ThreadPool.hpp.

◆ maxJobsTotal

int maxJobsTotal

extern

Specify how many jobs maximal can be used with the threadpool

Definition at line 1024 of file ThreadPool.cpp.

UPnPsdk 0.1 Universal Plug and Play +, Software Development Kit

Classes

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Class Documentation

◆ timezone

◆ ThreadPoolAttr

◆ ThreadPoolJob

◆ ThreadPoolStats

◆ ThreadPool

Macro Definition Documentation

◆ INVALID_JOB_ID

◆ STATS

◆ DEFAULT_POLICY

Typedef Documentation

◆ free_routine

◆ PolicyType

Enumeration Type Documentation

◆ Duration

◆ ThreadPriority

Function Documentation

◆ gettimeofday()

◆ TPSetMaxJobsTotal()

◆ ThreadPoolInit()

◆ ThreadPoolAddPersistent()

◆ ThreadPoolGetAttr()

◆ ThreadPoolSetAttr()

◆ ThreadPoolAdd()

◆ ThreadPoolRemove()

◆ ThreadPoolShutdown()

◆ TPJobInit()

◆ TPJobSetPriority()

◆ TPJobSetFreeFunction()

◆ TPAttrInit()

◆ TPAttrSetMaxThreads()

◆ TPAttrSetMinThreads()

◆ TPAttrSetStackSize()

◆ TPAttrSetIdleTime()

◆ TPAttrSetJobsPerThread()

◆ TPAttrSetStarvationTime()

◆ TPAttrSetSchedPolicy()

◆ TPAttrSetMaxJobsTotal()

◆ ThreadPoolGetStats()

◆ ThreadPoolPrintStats()

Variable Documentation

◆ DEFAULT_PRIORITY

◆ DEFAULT_MIN_THREADS

◆ DEFAULT_MAX_THREADS

◆ DEFAULT_STACK_SIZE

◆ DEFAULT_JOBS_PER_THREAD

◆ DEFAULT_STARVATION_TIME

◆ DEFAULT_IDLE_TIME

◆ DEFAULT_FREE_ROUTINE

◆ DEFAULT_MAX_JOBS_TOTAL

◆ maxJobsTotal