Older Newer
Wed, 18 Jun 2008 11:27:56 . . . . afh [add anchor links]

Changes by last author:

= waitForThread =

== Syntax ==

:bool waitForThread(int hThread, int ms, int userinput)

== Arguments ==


:: Specifies the handle of the thread for which we wish to await completion, or 0 to wait for the completion of all current worker threads.


:: Specifies the maximum time in milliseconds that we are willing to wait, or 0 to return immediately after checking for completion of the thread(s), or (INFINITE)? (0xFFFFFFFF) if we are willing to wait forever.


:: Set this value to 0 to discard all mouse and keyboard messages while waiting for the thread(s) to complete, or 1 to continue processing all messages while waiting.

== Return ==

:Returns true if all specified threads have completed, or false if we timed out while waiting.

== Description ==

:Use this function to wait for the completion of one or all worker threads that were created by calling triggerThread. To wait for one particular thread, set the first parameter to the value of the thread handle that was returned by the call to triggerThread. To wait for all current worker threads to complete, set the hThread parameter to 0.



:The second parameter ms specifies how long to wait for the thread(s) to complete, in millisecond units. Specify 0 to return immediately after checking for completion of the thread(s), or (INFINITE)? to wait indefinitely.



:While waiting for the thread(s) to complete, waitForThread runs a message pump loop to process other messages in the meantime. If the userinput parameter is 1, the message loop will process all messages, including user input messages from the keyboard and mouse. If processing such user input messages interferes in an undesired way while the worker thread(s) are running, set this parameter to 0 to ignore and discard all such user input messages. For example, if the worker threads are processing the current image, then it would be undesirable to allow mouse or keyboard input to trigger the preview's zoom control, or to drag and resize the dialog window. In general, it is recommended to set this parameter to 0 unless you have specific requirements to do otherwise.

== Example ==

:See the triggerThread example.

== Also see ==

:System Functions, Multithreading Functions, countProcessors, triggerThread, isThreadActive, getThreadRetVal, terminateThread, (INFINITE)?

== Comments ==

*The current implementation of waitForThread recognizes only a parameter of 0 to wait for all threads; you cannot specify a thread handle to wait for a specific thread.

*Everyone can add his or her comments here about his or her experiences with this function. Tips for using it are welcome, too.