CFLOCK  
 
 

The CFLOCK tag single-threads access to the CFML constructs in its body. Single-threaded access implies that the body of the tag can be executed by at most one request at a time. A request executing inside a CFLOCK tag has an "exclusive lock" on the tag. No other requests are allowed to start executing inside the tag while a request has an exclusive lock. ColdFusion issues exclusive locks on a first-come first-serve basis.

 
 
  Syntax  
 
<CFLOCK NAME="lockname" 
    TIMEOUT="timeout in seconds "
    THROWONTIMEOUT="Yes/No"> 
    <!--- CFML to be synchronized ---> 
</CFLOCK>

NAME

Optional. Specifies the name of the lock. Only one request will be able to execute inside a CFLOCK tag with a given name. Therefore, providing the NAME attribute allows for synchronizing access to the same resources from different parts of an application. Lock names are global to a ColdFusion server. They are shared between applications and user sessions, but not across clustered servers. If the NAME attribute is not provided, ColdFusion creates an anonymous lock every time CFLOCK is used in a page.

TIMEOUT

Required. Specifies the maximum amount of time in seconds to wait to obtain an exclusive lock. If an exclusive lock can obtained within the specified period, execution will continue inside the body of the tag. Otherwise, the behavior depends on the value of the THROWONTIMEOUT attribute.

THROWONTIMEOUT

Optional. Yes or No. Specifies how timeout conditions should be handled. If the value is Yes an exception will be generated to provide notification of the timeout. If the value is No execution continues past the </CFLOCK> tag. Default is Yes.

 
 
  Usage  
 

ColdFusion Server is a multi-threaded web application server that can process multiple page requests at any given time. Use CFLOCK to guarantee that multiple concurrently executing requests do not manipulate shared data structures, files, or CFXs in an inconsistent manner. Note the following:

  • Using CFLOCK around CFML constructs that modify shared data ensures that the modifications occur one after the other and not all at the same time.
  • As a general rule, you should use the CFLOCK tag to perform updates to variables in the Application, Server, and Session scopes.
  • Using CFLOCK around file manipulation constructs can guarantee that file updates do not fail due to files being open for writing by other applications or ColdFusion tags.
  • Using CFLOCK around CFX invocations can guarantee that CFXs that are not implemented in a thread-safe manner can be safely invoked by ColdFusion. This usually only applies to CFXs developed in C++ using the CFAPI. Any C++ CFX that maintains and manipulates shared (global) data structures will have to be made thread-safe to safely work with ColdFusion. However, writing thread-safe C++ CFXs requires advanced knowledge. A CFML custom tag wrapper can be used around the CFX to make its invocation thread-safe.

Note: CFLOCK uses a kernel level synchronization object that is released automatically upon timeout and/or abnormal termination of the thread that owns it. Therefore, ColdFusion will never deadlock while processing a CFLOCK tag. However, very large timeouts can block request threads for long periods of time and thus radically decrease throughput. Always use the minimum timeout value allowed.





 
 
BackUp LevelNext
 
 

allaire     AllaireDoc@allaire.com
    Copyright © 1998, Allaire Corporation. All rights reserved.