ColdFusion MX: Explanation of Request Timeout and threadWaitTimeout settings

This TechNote explains what the Request timeout and threadWaitTimeout settings are and how they work. Note: Screenshots are from CFMX 6.1 Administrator but information also applies to CFMX 7.

What is it?

The Request Timeout setting is located in the Server Settings section of the ColdFusion Administrator. It is the checkbox with "Timeout Requests after (seconds)" next to it. The Request Timeout setting times out running requests that take longer than the designated seconds set. The default setting is that it is unchecked and set to 30 seconds.

Recommendation:

Macromedia recommends always having the request timeout enabled with a setting of 30 seconds. By doing this, the performance of the whole server will not be sacrificed for a few valid long running pages. Set a reasonable timeout setting in the ColdFusion Administrator and then override this setting in the code for the specific long running pages. To override the ColdFusion Administrator timeout setting, either use therequestTimeout attribute of the cfsetting tag or, if you have a page with cfquery orcfhttp, use the timeout attribute of those tags. For database queries, the cfquery timeout will only work if the database you working with supports passing a timeout parameter. Check the database documentation to determine if this functionality is supported.

Example:

Migration note from ColdFusion 5 to ColdFusion MX:

Passing the RequestTimeout parameter in the URL is deprecated in ColdFusion MX. You need to use cfsetting in conjunction with this for it to work. For example,<cfsetting requestTimeout = #URL.RequestTimeout#>.

Tag exceptions:

There are certain tags that will not "obey" a timeout, whether it's set in the ColdFusion Administrator or in code on the CFM page. These tags are cfstoredproc,cfcontent, cfftp, cfexecute and cfobject. Also, CFX tags fall into the category of not obeying the ColdFusion timeout setting. While these tags are executing, ColdFusion must wait until the action completes before it can check for a Request Timeout. Therefore, if ColdFusion never receives a response from either the database or the objectcfobject is calling, a hung thread occurs and only restarting the ColdFusion service will clear this out.

Example:

A page runs long due to a cfobject call. The timeout will be thrown after the page is finished processing as long as ColdFusion receives a response, otherwise the thread will hang. However, if the page ran long due to a cfloop, the page would throw a timeout error at 30 seconds (or the value specified in the ColdFusion Administrator) and page processing would stop.

threadWaitTimeout Setting

What is it?

The threadWaitTimeout setting is located in the jrun.xml file under the ProxyService section (see example below). The location of the jrun.xml file on a Server Configuration install is cf_root\CFusionMX\runtime\servers\default\SERVER-INF and on a J2EE Configuration install isjrun_root\JRun4\servers\cfusion\SERVER-INF. ThethreadWaitTimeout setting is the timeout setting for queued threads. Queued threads refers to threads waiting to become running requests.

Recommendation:

The default setting in ColdFusion MX is 300 seconds and in ColdFusion MX 6.1 it is 20 seconds. This change in behavior has been logged as Macromedia issue 55053 since it can cause queued threads to prematurely timeout, causing JRun Closed connection errors. See TechNote 19351 for more information on this error. The recommended setting for threadWaitTimeout is to set it at least equal to the Request Timeout setting in the ColdFusion Administrator but no greater than 300 seconds.

Example:

10 requests come in to ColdFusion at the same time and Simultaneous Requests are set in the ColdFusion Administrator to 5. Threads 1 through 5 are the running requests, threads 6 through 10 are the queued threads. The threadWaitTimeout setting determines how long queued threads will wait for space in the active request pool to become available before timing out.

Timeout Scenarios

The following scenarios help demonstrate how the Request Timeout and threadWaitTimeout settings work under four common conditions.

Scenario 1

A page called doSomething.cfm contains a cfloop and other code. It takes 45 seconds for the page to execute. There is low load on the box with less than 5 running requests when it's called. What happens to this page?

Answer: The doSomething.cfm page times out after 30 seconds and the error below shows up in the Application.log file. It errors because the page takes 45 seconds to execute which is greater than the Request Timeout setting of 30 seconds.

Note: Increasing the timeout is not the remedy for fixing a page that times out. It's important to estabalish the underlying cause of why the page is running long. For instance, queries should take no longer than 300ms to run. Ideally, they should run 10-100ms for the web environment. If you have queries that are taking longer to run, optimize them with the help of your database administrator. Use gettickcount() around sections of the page's code to determine what part of the code is taking the longest. See the performance-related TechNotes listed below for further information on improving page performance. If the page is running long for a valid reason, then use cfsetting to increase the timeout for that specific page.

Scenario 2

A page called doSomething.cfm contains a cfquery with a timeout attribute set to 120. It takes 80 seconds to execute the page. There is low load on the box with less than 5 running requests when its called. What happens to this page?

Answer: The doSomething.cfm page executes successfully and does NOT timeout because the ColdFusion Administrator timeout has been overridden in thecfquery tag. Note: The database vendor must support atimeout attribute for this attribute to work in thecfquery tag. Most of the enterprise databases such as Oracle, Microsoft SQL Server and Sybase support this feature but check the database documentation to verify.

Scenario 3

A page called doSomething.cfm contains a cfquery with a timeout attribute set to 120. It takes 80 seconds to execute the page. There is heavy load on the box with greater than 5 simultaneous requests when the page is called. This page request is queued and the average wait time is 30 seconds for queued requests. What happens to this page?

Answer: The request for doSomething.cfm times out before it even makes it into the running request queue because the threadWaitTimeout value of 20 seconds is less than the average wait of 30 seconds in this case.

Along with JRun Closed Connection errors users might see in the browser, there will be errors in the default-err.log that look like the following:

Note: There are other reasons besides threadWaitTimeout being too low that can cause JRun Closed Connection errors. See the TechNote mentioned below about how to troubleshoot this type of error.

Scenario 4

There is heavy load on the box with greater than 5 simultaneous requests when doSomething.cfm is called. The average wait time for queued requests is 30 seconds. doSomething.cfm typically takes 25 seconds to execute. What happens to this page?

Answer: The doSomething.cfm page executes successfully because the thread only waits 30 seconds as a queued request and the threadWaitTimeout is set to 300. Once the request moves to the running request queue, the timer starts again so a page that takes 25 seconds to run will not timeout because the Request Timeout is set to 30 seconds.

Additional Information

• ColdFusion MX 6.1 (Server Configuration): Troubleshooting 'jrun closed connection' errors
• ColdFusion MX 6.1: 'Request timed out waiting for an available thread to run' error
• ColdFusion Performance Tuning
• ColdFusion MX: Tips for performance and scalability