Adobe 38043740 Developing Applications - Page 341

DEVELOPING COLDFUSION 9 APPLICATIONS 336 Developing CFML Applications Using the thread status The Thread scope status metadata variable lets the page, or any other thread started by the page, determine the status of any thread. The page processing code can then take a necessary action, for example, if the thread has terminated abnormally or has hung. The status variable can have the following values: Value NOT_STARTED RUNNNG TERMINATED COMPLETED WAITING Meaning The thread has been queued but is not processing yet. The thread is running normally. The thread stopped running as a result of one of the following actions: • A cfthread tag with a terminate action stopped the thread. • An error occurred in the thread that caused it to terminate. • A ColdFusion administrator stopped the thread from the Server Monitor. The thread ended normally. The thread has run a cfthread tag with action="join", and one or more of the threads being joined have not yet completed. Applications can check the thread status to manage processing. For example, an application that requires results from a thread specifies a time-out when it joins the thread; in this case, it can check for the COMPLETED status to ensure that the thread has completed processing and the join did not just result from a time-out. Similarly, an application can check the status value of threads that might not start or might not complete normally, and terminate it if necessary. The example in "Ending a thread" on page 330 checks thread status and terminates any threads with RUNNING or NOT_STARTED status. Handling thread output To prevent conflicts, only the page thread displays output. Therefore, named threads have the following limitations: • ColdFusion places all output that you generate inside a thread, such as HTML and plain text, or the generated output of a cfoutput tag, in the Thread scope output metadata variable. The page-level code can display the contents of this variable by accessing the threadName.output variable. • All tags and tag actions that directly send output to the client (instead of generating page text such as HTML output), do not work inside the thread. For example, to use the cfdocument or cfreport tags in a thread, specify a filename attribute; to use a cfpresentation tag, use a directory attribute. Handling ColdFusion thread errors If an error occurs in a thread, page-level processing is not affected, and ColdFusion does not generate an error message. If you do not handle the error by using a try/catch block in the thread code, the thread with the error terminates and the page-level code or other threads can get the error information from the thread metadata Error variable and handle the error appropriately. You cannot use page- or application-based error handling techniques to manage errors that occur during thread execution. For that reason, you cannot use the cferror tag or the onError application event handler for thread errors. Instead, use either of the following techniques: 1 Use cftry/cfcatch tags or try/catch CFScript statements in the cfthread body to handle the errors inside the thread. Last updated 1/20/2012