The C++ framework for developing highly scalable, high performance servers on Windows platforms.

CThreadPool Class Reference
[Win32 Threading primitivesWin32 I/O Completion Ports]

Inheritance diagram for CThreadPool:
Collaboration diagram for CThreadPool:

List of all members.


Detailed Description

A thread pool which can expand and contract (i.e. change the number of pooled threads) based on the work load. The pool has minimum and maximum sizes and a dispatch timeout. If dispatching a work item to a worker thread takes longer than the timeout then the pool is enlarged by one thread. There is also a maximum number of "dormant" threads, that is threads that are not working and when this number is reached worker threads are removed from the pool. The thread pool uses two I/O completion ports to do its work. Work items are dispatched to the dispatch port and are processed by the maintenance thread which dispatches the work items to the work port where the worker threads are waiting. This two layer dispatching means that dispatching from user code is fast but the pool can adjust its size depending on how long it takes for a worker thread to pick up a work item. Work items only ever queue on the dispatch port, the work port will only ever have a single work item on it at a time.

Public Types

typedef unsigned short ThreadCount
typedef ThreadIdentifier ThreadIdentifier

Public Member Functions

 CThreadPool (ThreadCount initialThreads, ThreadCount minThreads, ThreadCount maxThreads, ThreadCount maxDormantThreads, Milliseconds poolMaintPeriod, Milliseconds dispatchTimeout, JetByteTools::Core::IThreadPoolWorkerThreadFactory &threadFactory)
 Create a thread pool with the specified number of initial, min and max and max dormant threads. In the absense of any work to do the pool's threads will be considered for shutdown every poolMaintPeriod milliseconds. If a work item takes longer than dispatchTimeout milliseconds to begin being processed by a worker thread then a new thread will be started. The supplied thread factory is used to create instances of IThreadPoolWorkerThread whenerve a new worker thread is required and these do the actual work of processing work items.
 CThreadPool (JetByteTools::Core::IMonitorThreadPool &monitor, ThreadCount initialThreads, ThreadCount minThreads, ThreadCount maxThreads, ThreadCount maxDormantThreads, Milliseconds poolMaintPeriod, Milliseconds dispatchTimeout, JetByteTools::Core::IThreadPoolWorkerThreadFactory &threadFactory)
 Create a thread pool with the specified number of initial, min and max and max dormant threads. In the absense of any work to do the pool's threads will be considered for shutdown every poolMaintPeriod milliseconds. If a work item takes longer than dispatchTimeout milliseconds to begin being processed by a worker thread then a new thread will be started. The supplied thread factory is used to create instances of IThreadPoolWorkerThread whenerve a new worker thread is required and these do the actual work of processing work items. The thread pool will report monitoring information to the supplied monitor interface.
 CThreadPool (const CThreadPool &rhs)
 ~CThreadPool () override
 Cleans up. Shuts down the pool if it has been started.
CThreadPooloperator= (const CThreadPool &rhs)
void SetThreadPriority (int priority)
 Sets the priority of the thread pool worker threads to the supplied value. Note that this must be called before calling Start() for it to have an effect.
void SetThreadName (const JetByteTools::Core::_tstring &threadName) const
 Sets the name of the thread pool worker threads as displayed in the Visual Studio debugger to the supplied name. By default the constructors set the name of the threads to "ThreadPool". Note that this must be called before calling Start() for it to have an effect.
void SetDispatchThreadName (const JetByteTools::Core::_tstring &threadName) const
 Sets the name of the thread pool's dispatch thread as displayed in the Visual Studio debugger to the supplied name. By default the constructors set the name of this thread to "ThreadPoolDispatch". Note that this must be called before calling Start() for it to have an effect.
void Start (bool enableMaintenance=true)
 Starts the thread pool. Creates the pool maintenance thread and the specified number of initial threads for the pool. Optionally enables dormant thread maintenance.
bool EnableMaintenance (bool enableMaintenance=true, bool maintenanceEnabledForOnePassOnly=false)
 Enable or disable dormant thread maintenance.
void BeginShutdown ()
 Start the shutdown proceedure. All worker threads will be shutdown once they finish working on their current work item the pool maitenance thread will be shut down.
bool WaitForShutdownToComplete (Milliseconds forceTerminationAfter=INFINITE)
 Waits for the worker threads and pool maintenance thread to shut down. Can be set to forcibly terminate worker threads if they take longer than forceTerminationAfterMillis milliseconds to terminate on their own. It's generally best to leave this set at INFINITE and NOT forcibly terminate worker threads. Returns true if threads were forcibly terminated.
void Dispatch (ULONG_PTR completionKey, DWORD numberOfBytes=0, JetByteTools::Core::IAsyncWorkItem *pWorkItem=nullptr)
 Dispatch a work item to the worker threads. The completion key can be any value except 0.

Classes

class  WorkerThread
 A worker thread for the CThreadPool. The user work is done by an instance of IThreadPoolWorkerThread which is created by the supplied factory in the worker thread's constructor and destroyed in the destructor. More...

Member Typedef Documentation

typedef unsigned short ThreadCount


Constructor & Destructor Documentation

CThreadPool ( ThreadCount  initialThreads,
ThreadCount  minThreads,
ThreadCount  maxThreads,
ThreadCount  maxDormantThreads,
Milliseconds  poolMaintPeriod,
Milliseconds  dispatchTimeout,
JetByteTools::Core::IThreadPoolWorkerThreadFactory threadFactory 
)

Create a thread pool with the specified number of initial, min and max and max dormant threads. In the absense of any work to do the pool's threads will be considered for shutdown every poolMaintPeriod milliseconds. If a work item takes longer than dispatchTimeout milliseconds to begin being processed by a worker thread then a new thread will be started. The supplied thread factory is used to create instances of IThreadPoolWorkerThread whenerve a new worker thread is required and these do the actual work of processing work items.

CThreadPool ( JetByteTools::Core::IMonitorThreadPool monitor,
ThreadCount  initialThreads,
ThreadCount  minThreads,
ThreadCount  maxThreads,
ThreadCount  maxDormantThreads,
Milliseconds  poolMaintPeriod,
Milliseconds  dispatchTimeout,
JetByteTools::Core::IThreadPoolWorkerThreadFactory threadFactory 
)

Create a thread pool with the specified number of initial, min and max and max dormant threads. In the absense of any work to do the pool's threads will be considered for shutdown every poolMaintPeriod milliseconds. If a work item takes longer than dispatchTimeout milliseconds to begin being processed by a worker thread then a new thread will be started. The supplied thread factory is used to create instances of IThreadPoolWorkerThread whenerve a new worker thread is required and these do the actual work of processing work items. The thread pool will report monitoring information to the supplied monitor interface.

CThreadPool ( const CThreadPool rhs  ) 

~CThreadPool (  )  [override]

Cleans up. Shuts down the pool if it has been started.


Member Function Documentation

CThreadPool& operator= ( const CThreadPool rhs  ) 

void SetThreadPriority ( int  priority  ) 

Sets the priority of the thread pool worker threads to the supplied value. Note that this must be called before calling Start() for it to have an effect.

void SetThreadName ( const JetByteTools::Core::_tstring threadName  )  const

Sets the name of the thread pool worker threads as displayed in the Visual Studio debugger to the supplied name. By default the constructors set the name of the threads to "ThreadPool". Note that this must be called before calling Start() for it to have an effect.

void SetDispatchThreadName ( const JetByteTools::Core::_tstring threadName  )  const

Sets the name of the thread pool's dispatch thread as displayed in the Visual Studio debugger to the supplied name. By default the constructors set the name of this thread to "ThreadPoolDispatch". Note that this must be called before calling Start() for it to have an effect.

void Start ( bool  enableMaintenance = true  ) 

Starts the thread pool. Creates the pool maintenance thread and the specified number of initial threads for the pool. Optionally enables dormant thread maintenance.

bool EnableMaintenance ( bool  enableMaintenance = true,
bool  maintenanceEnabledForOnePassOnly = false 
)

Enable or disable dormant thread maintenance.

void BeginShutdown (  ) 

Start the shutdown proceedure. All worker threads will be shutdown once they finish working on their current work item the pool maitenance thread will be shut down.

bool WaitForShutdownToComplete ( Milliseconds  forceTerminationAfter = INFINITE  ) 

Waits for the worker threads and pool maintenance thread to shut down. Can be set to forcibly terminate worker threads if they take longer than forceTerminationAfterMillis milliseconds to terminate on their own. It's generally best to leave this set at INFINITE and NOT forcibly terminate worker threads. Returns true if threads were forcibly terminated.

void Dispatch ( ULONG_PTR  completionKey,
DWORD  numberOfBytes = 0,
JetByteTools::Core::IAsyncWorkItem pWorkItem = nullptr 
)

Dispatch a work item to the worker threads. The completion key can be any value except 0.


Generated on Sun Sep 12 19:11:51 2021 for The Server Framework - v7.4 by doxygen 1.5.3