PStat v1.25

Welcome to PStat, A freeware generalized framework for executing a lengthy operation in a thread using MFC. Feedback is provided by a progress dialog which can optionally be cancelled. The sample application included with PStat allows you to calculate the 1,000,000th prime number both with and without PStat. Try using the "without PStat" option from the test program and tab to another program, when you tab back you will notice that it's window is not redrawn because it is not responding to any window messages. Now try the same with PStat, Notice the difference!

When executed with PStat, while your function is being executed a progress dialog will be displayed as:

If you want to allow the user to cancel the operation during your function then the progress dialog can be displayed with a cancel button as:

Features

• Simple single function to call to get your code to run in the context of another thread.
• All the code is fully UNICODE compliant.
• Compiles cleanly at warning level 4.
• Time remaining static is automatically calculated.
• A simple test app is included.

Usage

To use PStat in your applications, simply include PStat.cpp in your project and include "PStat.h" in whichever module wants to access it. You should also copy the dialog resources IDD_PSTAT_PROGRESS and IDD_PSTAT_PROGRESS_WITH_CANCEL in addition to the string resources IDS_PSTAT_TIMELEFT_IN_MINUTES and IDS_PSTAT_TIMELEFT_IN_SECONDS into your client application. The code requires at a minimum VC 2010 and will not compile with earlier versions of Visual Studio.

History

v1.0 (27 March 1997)

• Initially created

v1.1 (18 February 1998)

• Fixed a bug where the worker thread was trying to close a dialog before it was created. A CEvent member of CProgressThreadDlg now protects this. Also removed the usual appwizard comments from the demo program.

v1.2 (8 November 1998)

• Added an option to confirm cancel by means of a message box.
• General tidy up of the code.
• Inclusion of VC 5 workspace files now as standard.
• All code now compiles cleanly at warning level 4.
• Code now supports UNICODE and build configurations are now provided.
• HTML help file now provided.

v1.21 (28 March 2000)

• Changed dialog resources which PStat uses to use the prefix ID._PSTAT_...
• Update documentation about its usage.

v1.22 (31 March 2000)

• Fixed a race condition which existing in the worker thread. The issue was that the dialog could be closed before the CSingleLock destructor was called in the worker thread which resulted in an access violation.

v1.23 (3 February 2003)

• Re-implemented a busy loop using a CEvent in ProgressDialogWorkerThread.
• Implemented synchronous closure of the worker thread
• Updated copyright details.

v1.24 (23 July 2007)

• Updated copyright details.
• Optimized CProgressThreadDlg constructor code.
• CProgressThreadInfo is now no longer derived from CObject as it was not really required.
• Code now uses newer C++ style casts instead of C style casts.
• Addition of a CPROGRESSTHREADDLG_EXT_CLASS preprocessor macro to make the code easier to use in an extension dll.
• Restructured code to avoid need for internal CProgressThreadInfo class.
• Made the Cancel button's ID on the IDD_PSTAT_PROGRESS_WITH_CANCEL "IDCANCEL".
• Code now internally thread protects the "m_bCancelled" and "m_bOkToClose" member variables.
• FUNCTION_WITH_PROGRESS function is now declared as PSTAT_FUNCTION and returns a void. It is also now scoped in the CProgressThreadDlg class.
• Updated sample app to clean compile on VC2005.
• Updated the documentation to use the same style as the web site.

v1.25 (21 January 2017)

• Updated copyright details.
• Updated the code to compile cleanly on VC 2010 - 2015.
• Removed the VC6 style classwizard comments from the code.
• Replaced NULL throughout the codebase with nullptr
• Moved all the configuration values used by the CProgressThreadDlg class into a new CProgressThreadSettings class.
• Added SAL annotations to all the code
• Refactored all the setup code in CProgressThreadDlg::OnInitDialog into various virtual methods.
• The progress control is now marked as paused when the confirm cancel messagebox is displayed.
• Updated the sample app's application icon

API Reference

PStat is principally made up of the "CProgressThreadSettings" and "CProgressThreadDlg" classes in the pstat.h header file. You construct a CProgressThreadDlg as you would any other CDialog derived instance except that its constructor takes all the parameters required (including the function to execute) as follows:

CProgressThreadDlg dlg(FUNCTION_WITH_PROGRESS* pfnFunction, const CProgressThreadSettings& settings, CWnd* pWndParent = NULL);

Parameters

pfnFunction Your actual function to call to get your function to work in a separate thread with a progress dialog being displayed while it is executing. pfnFunction should have the following definition:

typedef void (FUNCTION_WITH_PROGRESS)(void* pData, CProgressThreadDlg* pProgressDlg);

settings an instance of the CProgressThreadSettings class which controls the behaviour of the dialog.

pWndParent The window which the progress dialog will use as its parent.

Remarks

Once you have constructed the dialog, simple call DoModal as per normal. In your "pfnFunction", you get a pointer to this dialog which you can call "HasBeenCancelled" to determine if the user requested the operation to be cancelled and you can call "ReportProgress" method to update the UI as your function progresses. To see a concrete example of how your pfnFunction should be coded, have a look at the CalculatePrimeNumbers in pstattestDlg.cpp. As your function will be executed in the context of another MFC thread, you will need to be aware of the usual synchronisation and access issues which come with multi-threaded MFC applications.

Contacting the Author

PJ Naughter
Email: pjna@naughter.com
Web: http://www.naughter.com
21 January 2017