HTTPServerWrappers and CPPCThreadPool v1.12

One of the class frameworks I developed and published on my web site many years ago was W3MFC and CThreadPoolServer. These helped me learn how HTTP and HTTPS worked as well as learn multi-threaded coding on Windows. A lot has changed in the years since this code was initially developed and I wanted to develop a new framework which encapsulates the HTTP Server API's available on Windows. These APIs let you embed an enterprise ready web server in your C++ Windows application. HTTPServerWrappers is a set of classes to encapsulate this functionality. To provide good performance you also need to tie this code to some sort of thread pool architecture. The CPPCThreadPool classes provide this thread pool functionality.

The classes provided are:

HTTPServer::CAutoInit This class provides a RAII wrapper for the SDK functions HttpInitialize and HttpTerminate.
HTTPServer::CSession This class provides a RAII wrapper for the SDK HTTP_SERVER_SESSION_ID typedef.
HTTPServer::CURLGroup This class provides a RAII wrapper for the SDK HTTP_URL_GROUP_ID typedef.
HTTPServer::CRequestQueue This class provides a RAII wrapper for the SDK request queue handle.
HTTPServer::CServer This class provides a actual class you can use in your client code to implement the HTTP server in your application.
CppConcurrency::CFunctionWrapper This class is used by the CThreadPool framework to implement its internal queue using std::packaged_task<>.
CppConcurrency::CThreadPool This class provides a thread pool framework written using just pure C++ 17 code.
CSecHandle This class provides a simple RAII wrapper for an SDK SecHandle.
CCredHandle This class provides a simple RAII wrapper for an SDK CredHandle.

Features

Usage

Class Framework Reference

History

Contacting the Author

Features

Encapsulates all the HTTP Server v2.0 functionality in a "HTTPServer" C++ namespace and is implemented in the HTTPServerWrappers.h header file.
Allows all the complicated HTTP server functionality to be customized using simple virtual methods in the HTTPServer::CServer class.
Provides a complete thread pool implementation using standard C++. This CppConcurrency::CThreadPool class is based on the thread pool implementation in the Advanced Thread Management Chapter in the book Concurrency in Action by Anthony Williams. The code also draws inspiration from https://github.com/dabbertorres/ThreadPool, https://github.com/f-squirrel/thread_pool & http://roar11.com/2016/01/a-platform-independent-thread-pool-using-c14/.
The thread pool is implemented in the CPPCThreadPool.h header file and CPPCThreadPoolTLS.cpp source file in just over 600 lines of code. It demonstrates a lot of C++ features such as: std::thread, std::thread::hardware_concurrency, std::unique_ptr, std::make_unique, std::shared_ptr, std::make_shared, std::move, r-value references, std::atomic, std::mutex, std::condition_variable, std::vector, std::queue, std::dequeue, thread local storage, std::unique_lock, std::lock_guard, std::this_thread::yield, std::for_each, std::generate_n, std::back_inserter, std::future, std::bind, std::invoke_result_t & std::packaged_task.
The thread pool implements optional per thread queues and task stealing, both unbounded and bounded synchronized queues and submitting tasks to a specific thread in the thread pool.
The thread pool implements waitable tasks using std::future and std::packaged_task.
The thread pool also supports optionally pumping the Windows message queue in the worker threads when compiled for Windows, custom worker thread initialization and cleanup and changing the number of threads in the thread pool dynamically.
A complete suite of unit tests are included in the demo application to test the thread pool classes.
Unicode enabled and all code compiles cleanly at warning level 4.
The code is /analyze clean and has been compiled using Clang-Tidy.
Please note that unlike W3MFC, the HTTPServerWrappers classes does not provide prebuilt ISAPI or CGI functionality. For this you will need to build your own functionality on top of the HTTPServerWrappers classes.
The sample application included in the download includes examples on handling a simple GET request example from in-memory, a GET directory system listing example, a GET example which returns a response from a file on the file system, a POST request which simply echoes back the received form request parameters, Basic authentication, NTLM authentication. Negotiate (i.e. Kerberos / NTLM) authentication, cookie authentication and Digest (RFC 7616) authentication.

Usage

To use the thread pool classes, simply #include "CPPCThreadPool.h" in the module you want and instantiate a CThreadPool instance and uses its various methods. You also need to add "CPPCThreadPoolTLS.cpp" source file to your project.
The HTTPServer class framework uses the Windows HTTP Server APIs built into Windows. Because this web server is implemented in HTTP.sys, a kernel component of Windows, it is a shared resource amongst all running applications. To allow multiple applications to share this resource, you first need to reserve the URL which you want your web server application to use. This allows multiple applications to operate as web servers at the same time on your computer. This reservation process can be done programmatically using the HttpSetServiceConfiguration API or using the Windows command line utility netsh. An example netsh command line would be:

netsh http add urlacl url=http://+:80/MyUri user=DOMAIN\user

This would setup a reservation for a web server listening on port 80 over HTTP and responding to any requests which include /MyUri in its HTTP request. The "user" part of the command line is used to limit what specific Windows accounts can actually open the HTTP request queue associated with this URL reservation. The application which houses your web server must be running under this account to allow it to open the request queue successfully. To list all the current URL reservations setup on your computer you would use:

netsh http show urlacl

Normally this reservation process would be done at installation time of your Windows application. Please see https://docs.microsoft.com/en-us/windows/win32/http/routing-incoming-requests and the netsh documentation for further details on the reservation process.
To use the web server framework classes simply #include "HTTPServerWrappers.h" in the module you want and implement a class derived from HTTPServer::CServer and override its HandleRequest method to customize the HTTP responses your web server should return.
Once you have your reservation made, you should then be able to start your web server by passing the string "http://+:80/MyUri" as one of the values to the HTTPServer::CServer::Start method. You can provide multiple URLs to the Start method if you want to handle multiple URLs from your application. The sample application included in the download passes the command line parameters it receives to this method and waits for a keypress to shutdown the application.
Note that the code has been developed using Visual Studio 2019 and requires C++ 17 compilation mode and probably will not compile on earlier versions of Visual Studio.
The thread pool code has been developed in standard C++ 17 and should be compilable on non-Windows platforms although this has not been explicitly tested.

Copyright

You are allowed to include the source code in any product (commercial, shareware, freeware or otherwise) when your product is released in binary form.
You are allowed to modify the source code in any way you want except you cannot modify the copyright details at the top of each module.
If you want to distribute source code with your application, then you are only allowed to distribute versions released by the author. This is to maintain a single distribution point for the source code.

Class Framework Reference

The framework consists of the following classes:

HTTPServer::CAutoInit
HTTPServer::CSession
HTTPServer::CURLGroup
HTTPServer::CRequestQueue
HTTPServer::CServer
CppConcurrency::CFunctionWrapper
CppConcurrency::CThreadPool

CAutoInit

This class provides a simple RAII wrapper for the SDK functions HttpInitialize and HttpTerminate. This class is implemented in the HTTPServer namespace. All applications which use the HTTP Server APIs need to call HttpInitialize on startup and HttpTerminate on shutdown.

Functions this class provides include:

CAutoInit

Init

~CAutoInit

CAutoInit::CAutoInit

CAutoInit();

Remarks

Standard class constructor

CAutoInit::~CAutoInit

~CAutoInit();

Remarks

Standard class destructor. Internally this will call the HttpTerminate SDK API.

CAutoInit::Init

ULONG Init(ULONG nFlags = HTTP_INITIALIZE_SERVER);

Remarks

This method encapsulates the HttpInitialize SDK API.

CSession

This class provides a RAII wrapper for the SDK HTTP_SERVER_SESSION_ID typedef. This class is implemented in the HTTPServer namespace. The session represents a logical connection to the HTTP Server APIs from your application.

Functions this class provides include:

CSession

~CSession

Create

Close

SetProperty

QueryProperty

operator HTTP_SERVER_SESSION_ID

CSession::CSession

CSession();

Remarks

Standard class constructor.

CSession::~CSession

~CSession();

Remarks

Standard class destructor. Internally this will call the Close method if the session object is currently valid.

CSession::Create

ULONG Create();

Remarks

This method encapsulates the HttpCreateServerSession SDK API.

CSession::Close

ULONG Close();

Remarks

This method encapsulates the HttpCloseServerSession SDK API.

CSession::SetProperty

ULONG SetProperty(HTTP_SERVER_PROPERTY Property, PVOID PropertyInformation, ULONG PropertyInformationLength);

Remarks

This method encapsulates the HttpSetServerSessionProperty SDK API.

CSession::QueryProperty

ULONG QueryProperty(HTTP_SERVER_PROPERTY Property, PVOID PropertyInformation, ULONG PropertyInformationLength, PULONG ReturnLength);

Remarks

This method encapsulates the HttpSetServerSessionProperty SDK API.

CSession::operator HTTP_SERVER_SESSION_ID

operator HTTP_SERVER_SESSION_ID();

Remarks

This method provided access to the underlying HTTP_SERVER_SESSION_ID value which the CSession class encapsulates.

CURLGroup

This class provides a RAII wrapper for the SDK HTTP_URL_GROUP_ID typedef. This class is implemented in the HTTPServer namespace. A URL Group represents a collection of URLs in the HTTP Server APIs.

Functions this class provides include:

CURLGroup

~CURLGroup

Create

Close

AddUrl

RemoveUrl

SetProperty

QueryProperty

operator HTTP_URL_GROUP_ID

CURLGroup::CURLGroup

CURLGroup();

Remarks

Standard class constructor.

CURLGroup::~CURLGroup

~CURLGroup();

Remarks

Standard class destructor. Internally this will call the Close method if the URL Group object is currently valid.

CURLGroup::Create

ULONG Create(const CSession& session);

Remarks

This method encapsulates the HttpCreateUrlGroup SDK API.

CURLGroup::Close

ULONG Close();

Remarks

This method encapsulates the HttpCloseUrlGroup SDK API.

CURLGroup::AddUrl

ULONG AddUrl(PCWSTR pFullyQualifiedUrl, HTTP_URL_CONTEXT UrlContext = 0);

Remarks

This method encapsulates the HttpAddUrlToUrlGroup SDK API.

CURLGroup::RemoveUrl

ULONG RemoveUrl(PCWSTR pFullyQualifiedUrl, ULONG Flags);

Remarks

This method encapsulates the HttpRemoveUrlFromUrlGroup SDK API.

CURLGroup::SetProperty

ULONG SetProperty(HTTP_SERVER_PROPERTY Property, PVOID PropertyInformation, ULONG PropertyInformationLength);

Remarks

This method encapsulates the HttpSetUrlGroupProperty SDK API.

CURLGroup::QueryProperty

ULONG QueryProperty(HTTP_SERVER_PROPERTY Property, PVOID PropertyInformation, ULONG PropertyInformationLength, PULONG ReturnLength);

Remarks

This method encapsulates the HttpQueryUrlGroupProperty SDK API.

CURLGroup::operator HTTP_URL_GROUP_ID

operator HTTP_URL_GROUP_ID();

Remarks

This method provided access to the underlying HTTP_URL_GROUP_ID value which the CURLGroup class encapsulates.

CRequestQueue

This class provides a RAII wrapper for the SDK HTTP request queue handle. This class is implemented in the HTTPServer namespace. A request queue is the queue structure which client applications used to read HTTP requests from and deliver HTTP responses to.

Functions this class provides include:

CRequestQueue

~CRequestQueue

Create

Close

SetProperty

QueryProperty

WaitForDemandStart

Shutdown

ReceiveClientCertificate

ReceiveRequest

ReceiveRequestEntityBody

SendResponse

SendEntityBody

DeclarePush

WatForDisconnect

WaitForDisconnectEx

CancelRequest

FlushResponseCache

AddFragmentToCache

ReadFragmentFromCache

operator HANDLE

CRequestQueue::CURLGroup

CRequestQueue();

Remarks

Standard class constructor.

CRequestQueue::~CRequestQueue

~CRequestQueue();

Remarks

Standard class destructor. Internally this will call the Close method if the request queue object is currently valid.

CRequestQueue::Create

ULONG Create(PCWSTR Name = nullptr, PSECURITY_ATTRIBUTES SecurityAttributes = nullptr, ULONG Flags = 0);

Remarks

This method encapsulates the HttpCreateRequestQueue SDK API.

CRequestQueue::Close

ULONG Close();

Remarks

This method encapsulates the HttpCloseRequestQueue SDK API.

CRequestQueue::SetProperty

ULONG SetProperty(HTTP_SERVER_PROPERTY Property, PVOID PropertyInformation, ULONG PropertyInformationLength);

Remarks

This method encapsulates the HttpSetRequestQueueProperty SDK API.

CRequestQueue::QueryProperty

ULONG QueryProperty(HTTP_SERVER_PROPERTY Property, PVOID PropertyInformation, ULONG PropertyInformationLength, PULONG ReturnLength);

Remarks

This method encapsulates the HttpQueryRequestQueueProperty SDK API.

CRequestQueue::WaitForDemandStart

ULONG WaitForDemandStart(LPOVERLAPPED Overlapped);

Remarks

This method encapsulates the HttpWaitForDemandStart SDK API.

CRequestQueue::Shutdown

ULONG Shutdown();

Remarks

This method encapsulates the HttpShutdownRequestQueue SDK API.

CRequestQueue::ReceiveClientCertificate

ULONG ReceiveClientCertificate(HTTP_CONNECTION_ID ConnectionId, ULONG Flags, PHTTP_SSL_CLIENT_CERT_INFO SslClientCertInfo, ULONG SslClientCertInfoSize, PULONG BytesReceived, LPOVERLAPPED Overlapped);

Remarks

This method encapsulates the HttpReceiveClientCertificate SDK API.

CRequestQueue::ReceiveRequest

ULONG ReceiveRequest(HTTP_REQUEST_ID RequestId, ULONG Flags, PHTTP_REQUEST RequestBuffer, ULONG RequestBufferLength, PULONG BytesReturned, LPOVERLAPPED Overlapped);

Remarks

This method encapsulates the HttpReceiveHttpRequest SDK API.

CRequestQueue::ReceiveRequestEntityBody

ULONG ReceiveRequestEntityBody(HTTP_REQUEST_ID RequestId, ULONG Flags, PVOID EntityBuffer, ULONG EntityBufferLength, PULONG BytesReturned, LPOVERLAPPED Overlapped);

Remarks

This method encapsulates the HttpReceiveRequestEntityBody SDK API.

CRequestQueue::SendResponse

ULONG SendResponse(HTTP_REQUEST_ID RequestId, ULONG Flags, PHTTP_RESPONSE HttpResponse, PHTTP_CACHE_POLICY CachePolicy, PULONG BytesSent, LPOVERLAPPED Overlapped, PHTTP_LOG_DATA LogData);

Remarks

This method encapsulates the HttpSendHttpResponse SDK API.

CRequestQueue::SendEntityBody

ULONG SendEntityBody(HTTP_REQUEST_ID RequestId, ULONG Flags, USHORT EntityChunkCount, PHTTP_DATA_CHUNK EntityChunks, PULONG BytesSent, LPOVERLAPPED Overlapped, PHTTP_LOG_DATA LogData);

Remarks

This method encapsulates the HttpSendResponseEntityBody SDK API.

CRequestQueue::DeclarePush

ULONG DeclarePush(HTTP_REQUEST_ID RequestId, HTTP_VERB Verb, PCWSTR Path, PCSTR Query, PHTTP_REQUEST_HEADERS Headers);

Remarks

This method encapsulates the HttpDeclarePush SDK API.

CRequestQueue::WaitForDisconnect

ULONG WaitForDisconnect(HTTP_CONNECTION_ID ConnectionId, LPOVERLAPPED Overlapped);

Remarks

This method encapsulates the HttpWaitForDisconnect SDK API.

CRequestQueue::WaitForDisconnectEx

ULONG WaitForDisconnectEx(HTTP_CONNECTION_ID ConnectionId, LPOVERLAPPED Overlapped);

Remarks

This method encapsulates the HttpWaitForDisconnectEx SDK API.

CRequestQueue::CancelRequest

ULONG CancelRequest(HTTP_REQUEST_ID RequestId, LPOVERLAPPED Overlapped);

Remarks

This method encapsulates the HttpCancelHttpRequest SDK API.

CRequestQueue::FlushResponseCache

ULONG FlushResponseCache(PCWSTR UrlPrefix, ULONG Flags, LPOVERLAPPED Overlapped);

Remarks

This method encapsulates the HttpFlushResponseCache SDK API.

CRequestQueue::AddFragmentToCache

ULONG AddFragmentToCache(PCWSTR UrlPrefix, PHTTP_DATA_CHUNK DataChunk, PHTTP_CACHE_POLICY CachePolicy, LPOVERLAPPED Overlapped);

Remarks

This method encapsulates the HttpAddFragmentToCache SDK API.

CRequestQueue::ReadFragmentFromCache

ULONG ReadFragmentFromCache(PCWSTR UrlPrefix, PHTTP_BYTE_RANGE ByteRange, PVOID Buffer, ULONG BufferLength, PULONG BytesRead, LPOVERLAPPED Overlapped);

Remarks

This method encapsulates the HttpReadFragmentFromCache SDK API.

CRequesQueue::operator HANDLE

operator HANDLE();

Remarks

This method provided access to the underlying HANDLE value which the CRequestQueue class encapsulates.

CServer

This class provides the main class which client applications use to implement the HTTP server functionality. This class is implemented in the HTTPServer namespace.

Functions this class provides include:

CServer

~CServer

Start

Stop

ReceiveRequestThread

ProcessRequest

HandleRequest

InitializeHTTPResponse

AddKnownHeader

SendResponse

A number of other methods are provided in the CServer class. They are EqualsSplit, IsInQuotedString, HeaderTokenize, ParseFormVariables, DecodeUrlEncodedFormValue, UnquoteHeaderValue, ParseCookieFromCookieHeader, ParseBasicAuthorizationHeader, ParseAuthorizationHeader, ParseNegotiateAuthorizationHeader, ParseNTLMAuthorizationHeader, DetermineDigestAlgorithm, GenerateRandom, Hash, MD5, GenerateDigestNonce, GenerateDigestHA1, GenerateDigestHA2, GenerateDigestResponse, ParseDigestAuthorizationHeader, ParseWeekDay, ParseMonth, ParseDateHeader & GenerateDateHeader. All these methods support the various examples in the demo HTTP server included in the download. These methods may be useful for implementing your HTTP server.

CServer::CServer

CServer(size_t nThreadCount = 0, bool bPermitTaskStealing = true, bool bPaused = false, bool bPumpWindowsMessages = false);

Remarks

Standard class constructor.

Parameters

nThreadCount The number of threads to create in the thread pool. If you provide the value 0, then the value return from std::thread::hardware_concurrency is actually used.

bPermitTaskStealing Should worker threads in the thread pool by allowed to steal tasks from other worker threads.

bPaused Should the worker threads by created in an initially "paused" state.

bPumpWindowsMessages Should the worker threads pump windows messages.

CServer::~CServer

~CServer();

Remarks

Standard class destructor. Internally this will call the Stop method.

CServer::Start

HRESULT Start(const std::vector<std::wstring>& URLs);

Remarks

This method actually starts the web server waiting for HTTP requests. Note that internally this method will create a worker thread which calls ReceiveRequestThread to wait for HTTP requests and dispatch them to the thread pool.

Return Value

A standard HRESULT value.

Parameters

URLs The array of urls in HTTP Server UrlPrefix format to listen on

CServer::Stop

HRESULT Stop();

Remarks

Stops the web server. This is the corollary method to the Start method.

Return Value

A standard HRESULT value.

CServer::ReceiveRequestThread

virtual void ReceiveRequestThread();

Remarks

This method is started up as a worker thread as part of the Start method. This thread reads HTTP requests from the HTTP Server response queue and dispatches these requests to the ProcessRequest method in the thread pool for processing.

CServer::ProcessRequest

virtual void ProcessRequest(std::shared_ptr<std::vector<BYTE>> request);

Remarks

This method is the callback method used to handle HTTP requests in the thread pool. The default implementation converts the "request" parameter to a HTTP_REQUEST pointer and calls the HandleRequest method.

CServer::HandleRequest

virtual void HandleRequest(PHTTP_REQUEST pRequest);

Remarks

This method is the main virtual function which client application code can override to handle HTTP requests. The default implementation in CServer returns a simple GET static response for all GET requests and a 503 response for all other requests.

CServer::InitializeHTTPResponse

static void InitializeHTTPResponse(HTTP_RESPONSE& response, USHORT nStatus, PCSTR pszReason);

Remarks

This helper method sets the StatusCode, pReason and ReasonLength member variables of the "response" parameter. These three fields will need to be set for most HTTP responses from your web server.

Parameters

response The response structure to update.

nStatus The HTTP status code to set into "response" e.g. 200, 404 or 503.

pszReason The Reason text to set into "response" e.g. "OK", "File Not Found" or "Not Implemented".

CServer::AddKnownHeader

static void AddKnownHeader(HTTP_RESPONSE& response, int nHeaderId, PCSTR pszValue);

Remarks

This helper method adds a "Known" HTTP header into the "KnownHeaders" member variable of the "response" parameter. These three fields will need to be set for most HTTP responses from your web server.

Parameters

response The response structure to update.

nStatus The header identifier to update. Values to use for this parameter are taken from the SDK HTTP_HEADER_ID enum. An example would be HttpHeaderContentLength.

pszValue The actual text to associate with the header.

CServer::SendResponse

static void SendResponse(HTTP_REQUEST_ID RequestID, USHORT nStatusCode, PCSTR pReason, PCSTR pContentType, const void* pEntity, ULONG nEntityLength);

static void SendResponse(HTTP_RESPONSE& response, HTTP_REQUEST_ID RequestID, USHORT nStatusCode, PCSTR pReason, PCSTR pContentType, const void* pEntity, ULONG nEntityLength);

Remarks

This helper method returns a HTTP response using just the supplied function parameters.

Parameters

response The response structure to use or the response.

RequestID The ID for the request which this response corresponds to.

nStatusCode The HTTP status code to send e.g. 200, 404 or 503.

pReason The Reason text to set into "response" e.g. "OK", "File Not Found" or "Not Implemented".

pContentType The HTTP content-type header to send.

pEntity The body of the HTTP response to send.

nEntityLength The length of "pEntity" in bytes.

CFunctionWrapper

This class is used internally by the thread pool class to allow std::packaged_task which is used by the thread pool queues to handle move-only types. This class is implemented in the CppConcurrency namespace. This is based on the function_wrapper class from the Advanced Thread Management Chapter in the book Concurrency in Action by Anthony Williams.

CThreadPool

This class provides the thread pool functionality used by the CServer class. It provides a generic thread pool implementation in pure C++ 17 code. It implements optional per thread queues, task stealing, unbounded and bounded synchronized queues, pumping the Windows message queue in the worker threads, custom worker thread initialization and cleanup, dynamic thread count resizing, "pausing" the thread pool and submitting tasks to a specific thread in the thread pool. This class is implemented in the CppConcurrency namespace.

Functions this class provides include:

CThreadPool

~CThreadPool

WorkerThread

InitInstanceThread

ExitInstanceThread

size

pumpWindowsMessages

get_thread

queueSize

threadQueueSize

threadsBusy

paused

pause

clear

stop

start

resize

submit

blocked_submit

WaitForInitInstanceThreads

CThreadPool::CThreadPool

CThreadPool(size_t threadCount = 0, bool permitTaskStealing = true, bool paused = false, bool pumpWindowsMessages = false);

Remarks

Standard class constructor.

Parameters

threadCount The number of threads to create in the thread pool. If you provide the value 0, then the value return from std::thread::hardware_concurrency is actually used.

permitTaskStealing Should worker threads in the thread pool by allowed to steal tasks from other worker threads.

paused Should the worker threads by created in an initially "paused" state.

pumpWindowsMessages Should the worker threads pump windows messages. Note this parameter is only available when compiled on Windows.

CThreadPool::~CThreadPool

~CThreadPool();

Remarks

Standard class destructor. Internally this will call the Stop method.

CThreadPool::WorkerThread

virtual void WorkerThread(size_t threadIndex);

Remarks

This method is the actual worker thread created by the thread pool. Internally this method waits for tasks on the local queue for this thread, the global queue, or a task is available to be stolen from another thread in the thread pool. It then calls the task before looping around to wait for more tasks. It calls InitInstanceThread as part of its startup and ExitInstanceThread prior to finishing. The method is marked virtual to allow it to be customized by derived classes if required.

Parameters

threadIndex The index of this thread in the thread pool. This is used to work our which local queue this worker thread should be using.

CThreadPool::InitInstanceThread

virtual bool InitInstanceThread(size_t threadIndex);

Remarks

This method is called during the startup of the worker thread. You can override this method in your derived class to implement custom worker thread initialization.

Return Value

Returning false from this method will cause the worker thread to fail startup. The default implementation in this class simply returns true.

Parameters

threadIndex The index of this thread in the thread pool.

CThreadPool::ExitInstanceThread

virtual void InitInstanceThread(size_t threadIndex);

Remarks

This method is called during the termination of the worker thread. You can override this method in your derived class to implement custom worker thread cleanup. The default implementation in this class does nothing.

Parameters

threadIndex The index of this thread in the thread pool.

CThreadPool::size

size_t size() const;

Return Value

Returns how many threads are in the thread pool.

CThreadPool::pumpWindowsMessages

bool pumpWindowsMessages() const;

Remarks

This method is only available when compiled on Windows.

Return Value

Returns true if the worker threads will be pumping windows messages otherwise false.

CServer::get_thread

std::thread& get_thread(size_t threadIndex) const;

Parameters

threadIndex The index of the thread in the thread pool.

Return Value

Provides access to a specific thread in the thread pool.

CThreadPool:queueSize

size_t queueSize() const;

Return Value

Returns how many items are on the main thread pool queue.

CThreadPool:threadQueueSize

size_t threadQueueSize(size_t threadIndex) const;

Parameters

threadIndex The index of the thread in the thread pool.

Return Value

Returns how many items are on a specific thread's local queue.

CThreadPool:threadsBusy

size_t threadsBusy() const;

Return Value

Returns how many threads are busy executing tasks in the thread pool.

CThreadPool::paused

bool paused() const;

Return Value

Returns true if the thread pool is currently "paused" or false otherwise. When a thread pool is paused no tasks will be processed by its worker threads even though task submission can continue.

CThreadPool::pause

void pause(bool pause);

Remarks

Sets the "pause" state of the thread pool. When a thread pool is "paused" no tasks will be processed by its worker threads even though task submission can continue.

Parameters

pause true to "pause" the thread pool and false to "unpause" the thread pool.

CThreadPool::clear

void clear();

Remarks

Clears down the main thread pool queue and all threads local queues. Note this does not affect the count of threads in the thread pool or any currently running tasks.

CThreadPool::stop

void stop();

Remarks

Shuts down the threadpool. This will undo all the work which the constructor and start method did. Called in the destructor if you do not explicitly call it yourself.

CThreadPool::start

void stop();

Remarks

Starts the threadpool.

CThreadPool::resize

void resize(size_t threadCount);

Remarks

Changes the number of threads in the thread pool. Note this method should only be called on the same thread on which the CThreadPool instance was created.

Parameters

threadCount The number of threads you want in the thread pool.

CThreadPool::submit

template<typename Func, typename... Args>
auto submit(Func&& f, Args&&... args) -> std::future<typename std::invoke_result_t<Func, Args...>>

template<typename Func, typename... Args>
auto submit(size_t threadIndex, Func&& f, Args&&... args) -> std::future<typename std::invoke_result_t<Func, Args...>>

Remarks

Submit a task to be processed in the thread pool. The override of submit which takes a "threadIndex" allows a task to be sent to a specific thread in the thread pool. These methods implement an unbounded queue size. This means that if you submit tasks quicker than they are processed in the thread pool, the memory usage will grow unbounded. If you want to implement a bounded queue then you can use blocked_submit methods.

Parameters

f The first variable argument to the thing / callable you want to execute in the thread pool.

args The remaining arguments to the thing / callable you want to execute in the thread pool.

threadIndex The thread index of the specific thread on which you want the task executed.

Return Value

A std::future wrapper for the callable which you can use to wait on a task to be processed.

CThreadPool::blocked_submit

template<typename Func, typename... Args>
auto blocked_submit(size_t maxQueuSize, Func&& f, Args&&... args) -> std::future<typename std::invoke_result_t<Func, Args...>>

template<typename Func, typename... Args>
auto blocked_submit(size_t maxQueueSize, size_t threadIndex, Func&& f, Args&&... args) -> std::future<typename std::invoke_result_t<Func, Args...>>

Remarks

Submit a task to be processed in the thread pool. If the queue size in the thread pool is already "maxQueueSize", then this method will block until the queue size reduces. The override of submit which takes a "threadIndex" allows a task to be sent to a specific thread in the thread pool. These methods allow you to implement a bounded queue size instead of the unbounded queue which would result if you used the submit methods.

Parameters

maxQueueSize The maximum items which can be put on the queue before blocking will occur.

f The first variable argument to the thing / callable you want to execute in the thread pool.

args The remaining arguments to the thing / callable you want to execute in the thread pool.

threadIndex The thread index of the specific thread on which you want the task executed.

Return Value

A std::future wrapper for the callable which you can use to wait on a task to be processed.

CThreadPool::WaitForInitInstanceThreads

bool WaitForInitInstanceThreads() const;

Remarks

Waits for the all threads in the thread pool to have called InitInstanceThread. This allows client code to check the initialization status of threads in the thread pool and act upon that result.

Return Value

true if all threads returned true from their InitInstanceThread method, otherwise false.

History

v1.12 (18 May 2023)

Updated modules to indicate that it needs to be compiled using /std:c++17. Thanks to Martin Richter for reporting this issue.

v1.11 (21 March 2023)

Optimized code to emplace_back call in resize method
Updated copyright details.
The thread pool now does not start by default when you call the CThreadPool constructor. Instead now client code is expected to call a new "Start" method. This breaking change was implemented to allow various virtual functions in the CThreadPool framework to work correctly as calling virtual functions is of course not supported from C++ constructors.

v1.10 (13 February 2022)

Updated the code to use C++ uniform initialization for all variable declarations.

v1.09 (23 January 2022)

Updated copyright details.
Fixed more static code analysis warnings in Visual Studio 2022.

v1.08 (29 June 2021)

Fixed a bug in CServer::SendResponse where an entity chunk would be added to the response even when the "nEntityLength" length parameter was 0. Thanks to David Conalty for reporting this issue.

v1.07 (16 April 2021)

CServer::Stop now shuts down the thread pool before it closes the request queue. This reordering of operations can avoid asserts from happening in the thread pool when the request queue has been closed.

v1.06 (15 April 2021)

Added new CPPCThreadPoolTLS.cpp source file to the CPPCThreadPool framework. This is required to avoid linker errors where the two thread_local member variables declared in CPPCThreadPool.h (CThreadPool::_LocalQueue & CThreadPool::_ThreadIndex) can be defined in multiple compilation units if the CPPCThreadPool.h header is included by your source code multiple times.
Reworked CServer class to be template based. This allows the CppConcurrency::CThreadPool instance to be customized at runtime.
Fixed a bug in the ParseFormVariables methods where the entity body would not be parsed correctly if "request.EntityChunkCount is > 1".

v1.05 (22 January 2021)

Updated copyright details.
Reimplemented HandleFileRequest method in the sample app with a new CServer::SendFileResponse method which provides new resuable functionality to return the full contents of a specific file in a HTTP response.

v1.04 (27 December 2020)

Added a new CServer::ParseDateHeader method to aid decoding HTTP If-Modified-Since headers.
Updated the sample HTTP server to support handling If-Modified-Since headers for the sample file request. These are known as Conditional get requests in the HTTP RFC.

v1.03 (23 December 2020)

Updated the sample app's cookie authentication example to use SHA256 hashing instead of MD5. In addition the password hashing now uses 16 bytes of salt to increase the cryptographic robustness.
Added support for new HttpDelegateRequestEx API available in latest Windows 10 SDK.

v1.02 (22 December 2020)

Added new CServer::ParseFormVariables methods to aid parsing application/x-www-form-urlencoded encoded form variables.
Added new CServer::DecodeUrlEncodedFormValue methods to aid decoding application/x-www-form-urlencoded encoded form variables.
Optimized the code in the sample HTTP server to minimize the time a lock is taken on the session cache in various locations.
Removed the use of the explicit ATL namespace in the sample HTTP server so that the MFC CString classes could be used if so desired.
Updated the included sample HTTP server to implement a fully worked cookie authentication example.

v1.01 (21 December 2020)

Fixed a bug in CThreadPool::OtherQueuesAreEmpty where the return value was being calculated incorrectly. This bug was causing the threads in the thread pool to do busy waits instead of waiting correctly on the "_TasksAvailable" condition variable.
Fixed an issue in the CThreadPool constructor where a lock was not taken prior to modifying the _Dones array.
Fixed an issue in CThreadPool::pause where a lock was not taken prior to modifying the _Paused variable.
Fixed an issue in CThreadPool::resize where a lock was not taken prior to modifying the _Dones array.
Added a new override of the CServer::SendResponse method which allows an already initialized HTTP_RESPONSE structure to be provided as a parameter.
Provided a new CServer::EqualsSplit method to aid parsing HTTP header values.
Provided a new CServer::IsInQuotedString method to aid parsing HTTP header values.
Provided a new CServer::HeaderTokenize method to aid parsing HTTP header values.
Provided a new CServer::UnquoteHeaderValue method to aid parsing HTTP header values.
Provided a new CServer::ParseCookieFromCookieHeader method to aid parsing HTTP cookies.
Provided a new CServer::ParseBasicAuthorizationHeader method to aid parsing Basic authentication headers.
Provided a new CServer::ParseAuthorizationHeader method to aid parsing NTLM and Negotiate authentication headers.
Provided a new CServer::ParseNegotiateAuthorizationHeader method to aid parsing Negotiate authentication headers.
Provided a new CServer::ParseNTLMAuthorizationHeader method to aid parsing NTLM authentication headers.
Provided a new CServer::DetermineDigestAlgorithm to aid parsing Digest authentication headers.
Provided a new CServer::GenerateRandom method to aid generating random data for Digest authentication headers.
Provided a new CServer::Hash method to aid generating cryptographic hashes data for Digest authentication headers.
Provided new CServer::MD5 methods to aid generating MD5 hashes data for Digest authentication headers.
Provided a new CServer::GenerateDigestNonce method to aid generating cryptographic nonces for Digest authentication headers.
Provided a new CServer::GenerateDigestHA1 method to aid validating Digest authentication headers.
Provided a new CServer::GenerateDigestHA2 method to aid validating Digest authentication headers.
Provided a new CServer::GenerateDigestResponse method to aid validating Digest authentication headers.
Provided a new CServer::ParseDigestAuthorizationHeader method to aid parsing Digest authentication headers.
Provided a new CCredHandle RAII class in CCredHandle.h to encapsulate an SDK CredHandle handle value.
Provided a new CSecHandle RAII class in CSecHandle.h to encapsulate an SDK SecHandle handle value.
Updated the existing basic authentication code in the included sample HTTP server to log important data to the console.
Updated the included sample HTTP server to implement a fully worked NTLM authentication example.
Updated the included sample HTTP server to implement a fully worked Negotiate (i.e. NTLM / Kerberbos) authentication example.
Updated the included sample HTTP server to implement a fully worked Digest (RFC 7616) authentication example. Please note that the sample code only supports the digest authentication logic supported by the most common web browsers (i.e. Internet Explorer, Firefox, Chrome and Edge). What this means is that only MD5 and MD5-sess is supported and features such as auth-int, SHA-256, SHA-256-sess, SHA-512-256, SHA-512-256-sess, username*, stale & userhash are not implemented.

v1.0 (8 November 2020)

Initial public release.

Contacting the Author

PJ Naughter
Email: pjna@naughter.com
Web: http://www.naughter.com
18 May 2023