PStat v1.2 - Threading Framework

Download source files - 20 Kb

Introduction

Features

History

Usage

API Reference

Contacting the Author

Welcome to pstat, a freeware generalized framework for executing a lengthy operation in a thread. Feedback is provided by a progress dialog which can optionally be cancelled. Included is a simple dialog based application which shows how to use it. The program demonstrates the difference threading can make by showing the difference 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 white meaning that it is not responding to any window messages. Now try the same with pstat. Notice the difference.

The sample application included with PStat allows you to calculate the 100,000th prime number both with and without pstat. When executed without pstat you will notice that the sample application becomes totally hung and fails to respond to window messages. With pstat you have no such problems.

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.

History

v1.0 (27th March 1997)

• Initially created.

v1.1 (18th 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 (8th 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.

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.

API Reference

PStat is made up of the single function as follows:

ExecuteFunctionWithProgressDialog

BOOL ExecuteFunctionWithProgressDialog(FUNCTION_WITH_PROGRESS* pfnFunction, const CString& sProgressTitle, void* pData = NULL, DWORD dwFlags = 0, const CString& sConfirmPrompt = _T(""), int nPriority = THREAD_PRIORITY_NORMAL, CWnd* pWndParent = NULL);

Return Value:
TRUE if the function was successfully executed otherwise FALSE i.e. the dialog was cancelled or some other error occurred.

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 ULONG (FUNCTION_WITH_PROGRESS)(void* pData, CProgressThreadDlg* pProgressDlg);
• sProgressTitle -- The title that should appear on the progress dialog while your function is executing.
• pData -- Any user defined data that your function will be called with. Similar to the way threads give you a single LPVOID parameter.
• dwFlags -- Bitwise compliment of flags to customize how the function will be executed. Currently only PSTAT_CANCEL and PSTAT_CONFIRMCANCEL are available which will display a cancel button on the progress dialog. PSTAT_CANCEL will allow the operation to be cancelled while PSTAT_CONFIRMCANCEL will prompt when a request for cancel is made by means of a message box.
• sConfirmPrompt -- Message text to display in confirm cancel message if PSTAT_CONFIRMCANCEL flag is used.
• nPriority -- The thread priority of the thread pfnFunction will execute at. See Win32 help for further details if unclear.
• pWndParent -- The window which the progress dialog will use as its parent.

Remarks:
To see 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: pjn@indigo.ie
Web: http://www.naughter.com
8th November 1998