Chapter 2: Thread Pool

 

1. windows provides a thread pool mechanism (supporting the I/O port) to simplify thread creation, destruction, and daily management. this thread pool function allows us to do the following:

● Call a function Asynchronously

● Call a function at intervals

● Call a function when the kernel object is triggered

● Call a function when the asynchronous I/O request is complete

2. Call a function Asynchronously

Void ntapi simplecallback (

Ptp_callback_instance pinstance,

Pvoid pvcontext );

Bool trysubmitthreadpoolcallback (

Ptp_simple_callback pfncallback,

Pvoid pvcontext, // parameters of the simplecallback Function

Ptp_callback_environ pcbe );

Function: adds a work item to the queue of the thread pool by calling postqueuedcompletionstatus. If the call is successful, true is returned. When trysubmitthreadpoolcallback is called, the pfncallback parameter is used to indicate the function that we wrote that conforms to the simplecallback prototype.

Every time trysubmitthreadpoolcallback is called, The system allocates a work item internally in our name. if you plan to submit a large number of work items, it may be better to consider performance and memory usage, create a work item once, and submit it multiple times.

Create a work item:

Ptp_work createthreadpoolwork (

Ptp_work_callback pfnworkhandler, // The function pointer (callback function) format is as follows:

Void callback workcallback (

Ptp_callback_instance instance,

Pvoid context,

Ptp_work)

Pvoid pvcontext, // function parameter

Ptp_callback_environ pcbe );

Function: create a structure in user mode to save its three parameters, and return a pointer to the modified structure.

When we want to submit a request to the thread pool, we can call the submitthreadpoolwork function:

Void submitthreadpoolwork (ptp_work pwork );

This assumes that the request is successfully added to the queue (that is, the callback function is called through the thread in the thread pool ).

If we want the thread to cancel a submitted work item, or the thread needs to suspend itself to wait for the work item to be processed, we can call the following function:

Void waitforthreadpoolworkcallbacks (

Ptp_work pwork, // the return value of the previous function

Bool bcancelpendingcallbacks); // flag bit

Function function: bcancelpendingcallback: The function attempts to cancel a specified work item. if the work item is being processed at this time, the function will wait for the processing to complete and return. if not, the function will mark it as canceled and return immediately.

If false is passed, the function suspends the calling thread until the processing of the specified work item is completed, in addition, the thread that processes this work item in the thread pool has been recycled and is ready to process the next work item.

If the ptp_work object commits multiple work items and the bcancelpendingcallback parameter value is false, the function waits for the thread pool to process all submitted work items. if it is true, the function will only wait for the currently running work item to complete.

If you do not need a work item, you can call closethreadpoolwork.

Void closethreadpoolwork (ptp_work pwk );

3. Call a function at intervals

Ptp_timer createthreadpooltimer (

Ptp_timer_callback pfntimercallback, // The callback function format is as follows:

Void callback_instance timeoutcallback (

Ptp_callback_instance pinstance,

Pvoid pvcontext,

Ptp_timer ptimer); // passed by create...

Pvoid pvcontext,

Ptp_callback_environ pcbe );

Registration Timer:

Void setthreadpooltimer (

Ptp_timer ptimer,

Pfiletime pftduetime, // The callback time of the first call. If it is a negative value, it indicates the interval.-1 indicates the start time.

DWORD msperiod, // The interval at which the callback function is called (0 indicates that only one call is triggered)

DWORD mswindowlength); // Add a random mswindowlength value to the current set departure time.

Function annotation:

If you want to redesign the timer start time and interval time, we can set a new value for the next three numbers. If you pass pftduetime to null, the timer will be paused instead of destroyed.

Check whether the timer has been set:

Bool isthreadpooltimerset (ptp_timer );

Other functions include waitforthreadpoolcallbacks to wait for completion. closethreadpooltimer is used to release the timer memory.

4. Call a function when the kernel object is triggered.

Create a function:

Ptp_wait createthreadpoolwait (

Ptp_wait_callback pfnwaitcallback,

Pvoid pvcontext,

Ptp_callback_environ pcbe );

The pfnwaitcallback format is as follows:

Void callback waitcallback (

Ptp_callback_instance pinstance,

Pvoid context,

Ptp_wait wait, // The reason for the callback function (also known as the status)

Tp_wait_result waitresult)

Bind the kernel object to the thread pool:

Void setthreadpoolwait (

Ptp_wait pwaititem, // create the returned value

Handle hobject, // Kernel Object

Pfiletime pfntimeout); // wait time.

Pfntimeout: indicates the maximum amount of time the thread pool should spend waiting for the kernel object to be triggered. 0 indicates that you do not need to wait, and assign a value to indicate the relative time. A positive value indicates the absolute time. null indicates an infinite duration.

When you wait using this function, make sure that the same handle is not registered multiple times.

The value of waitcallback is as follows:

Waitresult Value	Explanation
Wait_object_0	If the kernel object sent to setthreadpoolwait is triggered before timeout, our callback function will receive this value.
Wait_timeout	If the kernel object sent to setthreadpoolwait is not triggered before timeout, we will receive this value
Wait_abandoned_0	If a mutex is sent to the setthreadpoolwait kernel object and the mutex is discarded, we will receive this value.

Once a thread in the thread pool calls our callback function, the corresponding wait item will not enter inactive status. (that is, it cannot be called again unless setthreadpoolwait is called again ). if we pass null to this waiting item to remove it from the thread pool.

5. Call a function when the asynchronous I/O request is complete.

Create an I/O object for the thread pool:

Ptp_io createthreadpoolio (

Handle hdevice, // pass the file_flag_overlapped flag through createfile

Ptp_win32_io_callback pfniocallback, // callback function

Pvoid pvcontext, // Parameter

Ptp_callback_environ pcbe );

The callback function is as follows:

Void callback overlappedcompletionroutine (

Ptp_callback_instance pinstance,

Pvoid pvcontext,

Pvoid poverlapped,

Ulong ioresult, // operation result (no_error upon success)

Ulong_ptr numberofbytestransferred, // number of bytes passed in

Ptp_io PIO); // pointer to the I/O entry in the thread pool.

Associate files/devices embedded in the I/O entry with the I/O Completion Ports in the thread pool:

Void startthreadpoolio (ptp_io PIO );

Note: This function must be called before readfile and writefile.

Stop calling our callback function:

Void cancelthreadpoolio (ptp_io PIO );

We can also let another thread wait for a pending I/O request to be completed:

Void waitforthreadpooliocallbacks (

Ptp_io PIO,

Bool bcancelpendingcallbacks); // if it is true, our callback function will not be called when the request is completed (if it has not been called ).

6. Terminate the callback function

The thread pool provides a convenient method to describe some operations that should be executed after the callback function of women returns. the callback function calls the following functions using the opaque pinstance parameter (type: ptp_callback_instance) passed to it:

Void leavecriticalsectionwhencallbackreturns (

Ptp_callback_instance PCI, pcritical_section PCs)

Void releasemutexwhencallbcakreturns (ptp_callback_instance PCI, handle MUT );

Void releasesemaphorewhencallbackreturns (ptp_callback_instance PCI, handle SEM, DWORD crel );

Void seteventwhencallbackreturns (ptp_callback_instance PCI, handle EVT );

Void freelibrarywhencallbackreturns (ptp_callback_instance PCI, hmodule mod );

When these functions are returned by the callback function, the thread pool automatically calls the corresponding function so that it enters the trigger state. and input the specified structure. we cannot require the thread pool to trigger an event and mutex after processing our work items. The final called termination function will overwrite the previously called termination function.

Two other termination functions:

Bool callbcakmayrunlong (ptp_callback_instance PCI); // It is mainly used to notify the thread pool that the callback function runs for a long time. If the function returns true, other threads are available.

Void disassociatecurrentthreadfromcallback (ptp_callback_instance PCI); // tells the thread pool that the job has been done logically.

If we want to customize the thread pool, we can call the following function to create a thread pool:

Ptp_pool createthreadpool (pvoid reserved); // reserved is reserved and null

Set the maximum and minimum number of threads in the thread pool:

Bool setthreadpoolminimum (ptp_bool pthreadpool, DWORD cthrdmin); //> = 1

Bool setthreadpoolmaximum (ptp_bool pthreadpool, DWORD cthrdmost); // <= 500

Initialize the callback environment (including some additional settings or configurations that can be applied to work items) function:

Typedef struct _ tp_callback_environ {

Ulong version;

_ Tp_pool * pool;

_ Tp_cleanup_group * cleanupgroup;

Pvoid cleanupgroupcancelcallback;

Pvoid racedll;

_ Activation_context * activationcontext;

Pvoid finalizationcallback;

Ulong U;

} Tp_callback_environ, * ptp_callback_environ;

Although these fields are defined, we should regard them as opaque.

A series of functions related to this structure:

Initialization structure:

Inline void initializethreadpoolenvironment (

Ptp_callback_environ pcbe); // set version to 1 and other fields to 0

Logout structure:

Void destroythreadpoolenvironment (

Ptp_callback_environ pcbe); // to add a work item to the thread pool queue, the callback environment must indicate which thread pool should process the work item .:

Void setthreadpoolcallbackpool (ptp_callback_environ pcbe,

Ptp_pool pthreadpool );

If we do not call it, the system will use the default thread pool to process it.

Tell the callback environment that the work item usually takes a long time to process. This will make the thread pool faster to create a thread.

Void setthreadpoolcallbackrunslong (ptp_callback_environ pcbe );

If the DLL corresponding to the thread pool is always in the memory before the thread pool is stopped:

Void setthreadpoolcallbacklibrary (ptp_callback_environ pcbe );

7. Cleanup group: non-default thread pool cleanup.

◆ Create a cleaning group:

Ptp_cleanup_group createthreadpoolcleanupgroup ();

◆ Bind the thread pool to the cleanup group:

Void setthreadpoolcallbackcleanupgroup (

Ptp_callback_environ pcbe,

Ptp_cleanup_group ptpcg,

Ptp_cleanup_group_callback pfng); // point to the address of a callback function. If the cleanup group is canceled, this function will be called. If pfng is not null, it should be in the following format:

Void callback cleanupgroupcancelcallback (

Pvoid pvobjectcontext,

Pvoid pvcleanupcontext );

◆ The application wants to destroy the thread pool:

Void closethreadpoolcleanupgroupmembers (

Ptp_cleanup_group ptpcg,

Bool bcancelpendingcallbacks,

Pvoid pvcleanupcontext );

Function usage:

If bcancelpendingcallbacks is true, all submitted work items that have not been processed are directly canceled. The function will return after all currently running work items are completed.

If bcancelpendingcallbacks is true and pfng is the address of the cleanupgroupcallback function, a callback function is called every time the function is canceled. The pvcleanupcontext parameter contains the context of the cancellation item.

If bcancelpendingcallbacks is passed to false, the thread pool takes time to process all the remaining items before the function returns. At this time, the callback function will not be called.

Release resources occupied by the cleanup group:

Void winapi closethreadpoolcleanupgroup (ptp_cleanup_groupptpcg );