libUPnP  1.6.17
Data Structures | Defines | Typedefs | Enumerations | Functions
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...

Defines

#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.
int ThreadPoolGetStats (ThreadPool *tp, ThreadPoolStats *stats)
 Returns various statistics about the thread pool.
void ThreadPoolPrintStats (ThreadPoolStats *stats)

Detailed Description


Define Documentation

#define DEFAULT_FREE_ROUTINE   NULL

default free routine used TPJobInit

Referenced by TPJobInit().

#define DEFAULT_IDLE_TIME   10 * 1000

default idle time used by TPAttrInit

Referenced by TPAttrInit().

#define DEFAULT_JOBS_PER_THREAD   10

default jobs per thread used by TPAttrInit

Referenced by TPAttrInit().

#define DEFAULT_MAX_JOBS_TOTAL   100

default max jobs used TPAttrInit

Referenced by TPAttrInit().

#define DEFAULT_MAX_THREADS   10

default max used by TPAttrInit

Referenced by TPAttrInit().

#define DEFAULT_MIN_THREADS   1

default minimum used by TPAttrInit

Referenced by TPAttrInit().

#define DEFAULT_PRIORITY   MED_PRIORITY

default priority used by TPJobInit

Referenced by TPJobInit(), and WorkerThread().

#define DEFAULT_STACK_SIZE   0u

default stack size used by TPAttrInit

Referenced by TPAttrInit().

#define DEFAULT_STARVATION_TIME   500

default starvation time used by TPAttrInit

Referenced by TPAttrInit().

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

Invalid JOB Id

Referenced by ThreadPoolAdd(), ThreadPoolAddPersistent(), and ThreadPoolRemove().

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

Invalid Policy

Referenced by ThreadPoolInit(), and ThreadPoolSetAttr().

#define JOBFREELISTSIZE   100

Size of job free list

Referenced by ThreadPoolInit().

#define STATS   1

Statistics.

Always include stats because code change is minimal.


Typedef Documentation

typedef void(* free_routine)(void *arg)

Function for freeing a thread argument.

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.

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

typedef struct THREADPOOLJOB ThreadPoolJob

Internal ThreadPool Job.

typedef struct TPOOLSTATS ThreadPoolStats

Structure to hold statistics.


Function Documentation

int ThreadPoolAdd ( ThreadPool tp,
ThreadPoolJob job,
int *  jobId 
)
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().

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.

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.

Referenced by PrintThreadPoolStats().

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(), FreeListInit(), THREADPOOL::highJobQ, INVALID_POLICY, THREADPOOL::jobFreeList, JOBFREELISTSIZE, THREADPOOL::lastJobId, ListInit(), 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, ThreadPoolShutdown(), THREADPOOL::totalThreads, and TPAttrInit().

Referenced by UpnpInitThreadPools().

Parameters:
stats.
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, ListDelNode(), ListFind(), THREADPOOL::lowJobQ, THREADPOOL::medJobQ, THREADPOOL::mutex, and THREADPOOL::persistentJob.

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().

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, FreeListDestroy(), FreeThreadPoolJob(), THREADPOOL::highJobQ, THREADPOOL::jobFreeList, ListDelNode(), ListDestroy(), ListHead(), 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().

int TPAttrInit ( ThreadPoolAttr attr)
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().

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().

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().

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().

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().

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.

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().

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.

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 genaInitNotify(), genaInitNotifyExt(), genaNotifyAll(), genaNotifyAllExt(), genaNotifyThread(), readFromSSDPSocket(), ScheduleGenaAutoRenew(), SearchByTarget(), ssdp_handle_ctrlpt_msg(), ssdp_handle_device_request(), StartMiniServer(), TimerThreadInit(), UpnpGetServiceVarStatusAsync(), UpnpRenewSubscriptionAsync(), UpnpSendActionAsync(), UpnpSendActionExAsync(), UpnpSendAdvertisementLowPower(), UpnpSubscribeAsync(), and UpnpUnSubscribeAsync().

int TPJobSetFreeFunction ( ThreadPoolJob job,
free_routine  func 
)
int TPJobSetPriority ( ThreadPoolJob job,
ThreadPriority  priority 
)