Adobe 38043740 - ColdFusion Standard - Mac Development Manual page 341

DEVELOPING COLDFUSION 9 APPLICATIONS
Developing CFML Applications
Using the thread status
The Thread scope metadata variable lets the page, or any other thread started by the page, determine the status
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
Value Meaning
NOT_STARTED The thread has been queued but is not processing yet.
RUNNNG The thread is running normally.
TERMINATED The thread stopped running as a result of one of the following actions:
•
•
•
COMPLETED The thread ended normally.
WAITING The thread has run a
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 tag, in the Thread scope
cfoutput
contents of this variable by accessing the threadName
• 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
a attribute; to use a
filename
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
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
Instead, use either of the following techniques:
1 Use tags or
cftry/cfcatch
thread.
variable can have the following values:
status
A cfthread tag with a terminate
An error occurred in the thread that caused it to terminate.
A ColdFusion administrator stopped the thread from the Server Monitor.
cfthread tag with
output
.output
tag, use a
cfpresentation
tag or the
cferror
CFScript statements in the
try/catch
Last updated 1/20/2012
action stopped the thread.
action="join" , and one or more of the threads being joined have
metadata variable. The page-level code can display the
variable.
or
cfdocument cfreport
attribute.
directory
application event handler for thread errors.
onError
body to handle the errors inside the
cfthread
tags in a thread, specify
variable and handle
Error
336