libUPnP 1.14.19
Data Structures | Macros | Typedefs | Enumerations | Functions
ThreadPool.h File Reference
#include "FreeList.h"
#include "LinkedList.h"
#include "UpnpGlobal.h"
#include "UpnpInet.h"
#include "ithread.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.
 
#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.
 

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.
 
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. Only affects future calculations.
 
int ThreadPoolAdd (ThreadPool *tp, ThreadPoolJob *job, int *jobId)
 Adds a job to the thread pool. Job will be run as soon as possible.
 
int ThreadPoolRemove (ThreadPool *tp, int jobId, ThreadPoolJob *out)
 Removes a job from the thread pool. Can only remove jobs which are not currently running.
 
int ThreadPoolShutdown (ThreadPool *tp)
 Shuts the thread pool down. Waits for all threads to finish. May block indefinitely if jobs do not exit.
 
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.
 
int TPJobSetPriority (ThreadPoolJob *job, ThreadPriority priority)
 Sets the max threads for the thread pool attributes.
 
int TPJobSetFreeFunction (ThreadPoolJob *job, free_routine func)
 Sets the max threads for the thread pool attributes.
 
int TPAttrInit (ThreadPoolAttr *attr)
 Initializes thread pool attributes. Sets values to defaults defined in ThreadPool.h.
 
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 maxJobsTotal)
 Sets the maximum number jobs that can be qeued totally.
 
UPNP_EXPORT_SPEC int ThreadPoolGetStats (ThreadPool *tp, ThreadPoolStats *stats)
 Returns various statistics about the thread pool.
 
UPNP_EXPORT_SPEC 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

◆ DEFAULT_JOBS_PER_THREAD

#define DEFAULT_JOBS_PER_THREAD   10

default jobs per thread used 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

◆ DEFAULT_MIN_THREADS

#define DEFAULT_MIN_THREADS   1

default minimum used 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

◆ 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

◆ 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

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 
)

◆ 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
tpValid thread pool pointer.
jobValid thread pool job.
jobId.

References THREADPOOL::attr, THREADPOOL::condition, CreateThreadPoolJob(), CreateWorker(), INVALID_JOB_ID, THREADPOOL::lastJobId, THREADPOOLATTR::maxThreads, THREADPOOL::mutex, THREADPOOL::persistentJob, THREADPOOL::persistentThreads, THREADPOOL::start_and_shutdown, and THREADPOOL::totalThreads.

Referenced by StartMiniServer(), TimerThreadInit(), and TimerThreadWorker().

◆ 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
tpvalid thread pool pointer.
outnon null pointer to store attributes.

References THREADPOOL::attr, THREADPOOL::mutex, and THREADPOOL::shutdown.

◆ ThreadPoolGetStats()

UPNP_EXPORT_SPEC 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
tpValid initialized threadpool.
statsValid stats, out parameter.

References THREADPOOL::highJobQ, THREADPOOL::lowJobQ, THREADPOOL::medJobQ, THREADPOOL::mutex, THREADPOOL::persistentThreads, THREADPOOL::shutdown, THREADPOOL::stats, and THREADPOOL::totalThreads.

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
tpMust be valid, non null, pointer to ThreadPool.
attrCan 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).

References THREADPOOL::attr, THREADPOOL::busyThreads, CmpThreadPoolJob(), THREADPOOL::condition, CreateWorker(), THREADPOOL::highJobQ, INVALID_POLICY, THREADPOOL::jobFreeList, JOBFREELISTSIZE, THREADPOOL::lastJobId, THREADPOOL::lowJobQ, THREADPOOL::medJobQ, THREADPOOLATTR::minThreads, THREADPOOL::mutex, THREADPOOL::pendingWorkerThreadStart, THREADPOOL::persistentJob, THREADPOOL::persistentThreads, THREADPOOLATTR::schedPolicy, SetPolicyType(), THREADPOOL::shutdown, THREADPOOL::start_and_shutdown, THREADPOOL::stats, StatsInit(), ThreadPoolShutdown(), THREADPOOL::totalThreads, and TPAttrInit().

Referenced by UpnpInitThreadPools().

◆ ThreadPoolPrintStats()

UPNP_EXPORT_SPEC 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
tpvalid thread pool pointer.
jobIdid of job.
outspace for removed job.

References FreeThreadPoolJob(), THREADPOOL::highJobQ, INVALID_JOB_ID, THREADPOOL::lowJobQ, THREADPOOL::medJobQ, THREADPOOL::mutex, and THREADPOOL::persistentJob.

◆ 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
tpvalid thread pool pointer.
attrpointer to attributes, null sets attributes to default.

References THREADPOOL::attr, THREADPOOL::condition, CreateWorker(), INVALID_POLICY, THREADPOOLATTR::minThreads, THREADPOOL::mutex, THREADPOOLATTR::schedPolicy, SetPolicyType(), ThreadPoolShutdown(), THREADPOOL::totalThreads, and TPAttrInit().

◆ 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
tpmust be valid tp.

References THREADPOOL::condition, FreeThreadPoolJob(), THREADPOOL::highJobQ, THREADPOOL::jobFreeList, THREADPOOL::lowJobQ, THREADPOOL::medJobQ, THREADPOOL::mutex, THREADPOOL::persistentJob, THREADPOOL::shutdown, LINKEDLIST::size, THREADPOOL::start_and_shutdown, and THREADPOOL::totalThreads.

Referenced by ThreadPoolInit(), ThreadPoolSetAttr(), and UpnpFinish().

◆ TPAttrInit()

int TPAttrInit ( ThreadPoolAttr attr)

◆ TPAttrSetIdleTime()

int TPAttrSetIdleTime ( ThreadPoolAttr attr,
int  idleTime 
)

Sets the idle time for the thread pool attributes.

Returns
Always returns 0.
Parameters
attrmust 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
attrmust be valid thread pool attributes.
jobsPerThreadnumber 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
attrmust be valid thread pool attributes.
maxJobsTotalmaximum 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
attrmust be valid thread pool attributes.
maxThreadsvalue 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
attrmust be valid thread pool attributes.
minThreadsvalue 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
attrmust be valid thread pool attributes.
schedPolicymust 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
attrmust be valid thread pool attributes.
stackSizevalue 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
attrmust be valid thread pool attributes.
starvationTimemilliseconds.

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
jobmust be valid thread pool attributes.
funcfunction to run, must be valid.
argargument to pass to function.

References DEFAULT_FREE_ROUTINE, and DEFAULT_PRIORITY.

Referenced by readFromSSDPSocket(), ScheduleGenaAutoRenew(), SearchByTarget(), ssdp_handle_ctrlpt_msg(), ssdp_handle_device_request(), StartMiniServer(), TimerThreadInit(), UpnpGetServiceVarStatusAsync(), UpnpRenewSubscriptionAsync(), UpnpSendActionAsync(), UpnpSendActionExAsync(), UpnpSendAdvertisementLowPower(), UpnpSubscribeAsync(), and UpnpUnSubscribeAsync().

◆ TPJobSetFreeFunction()

int TPJobSetFreeFunction ( ThreadPoolJob job,
free_routine  func 
)

◆ TPJobSetPriority()

int TPJobSetPriority ( ThreadPoolJob job,
ThreadPriority  priority 
)

Sets the max threads for the thread pool attributes.

Returns
Always returns 0.
Parameters
jobmust be valid thread pool attributes.
priorityvalue to set.

Referenced by readFromSSDPSocket(), ScheduleGenaAutoRenew(), SearchByTarget(), ssdp_handle_ctrlpt_msg(), StartMiniServer(), TimerThreadInit(), UpnpGetServiceVarStatusAsync(), UpnpRenewSubscriptionAsync(), UpnpSendActionAsync(), UpnpSendActionExAsync(), UpnpSendAdvertisementLowPower(), UpnpSubscribeAsync(), and UpnpUnSubscribeAsync().