CFML Reference
ColdFusion Tags

cflock

Description

Provides two types of locks to ensure the integrity of shared data:

• Exclusive lock
• Read-only lock

An exclusive lock 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 can start executing inside the tag while a request has an exclusive lock. ColdFusion issues exclusive locks on a first-come, first-served basis.

A read-only lock allows multiple requests to access the CFML constructs inside its body concurrently. Therefore, read-only locks should be used only when the shared data is read only and not modified. If another request already has an exclusive lock on the shared data, the request waits for the exclusive lock to be released.

Category

Web application framework tags

Syntax

<cflock timeout = "timeout in seconds "

  scope = "Application" or "Server" or "Session"

  name = "lockname" 

  throwOnTimeout = "Yes" or "No"

  type = "readOnly/Exclusive "> 

  <!--- CFML to be synchronized ---> 

</cflock> 

See also

cfapplication, cfassociate, cfauthenticate, cfmodule

Attributes

Attribute	Description
timeout	Required. Specifies the maximum amount of time, in seconds, to wait to obtain a lock. If a lock can be obtained within the specified period, execution continues inside the body of the tag. Otherwise, the behavior depends on the value of the throwOnTimeout attribute.
scope	Optional. Specifies the scope as one of the following: Application, Server, or Session. This attribute is mutually exclusive with the name attribute.
name	Optional. Specifies the name of the lock. Only one request can execute inside a cflock tag with a given name. Therefore, providing the name attribute allows for synchronizing access to 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. This attribute is mutually exclusive with the scope attribute. Therefore, do not specify the scope attribute and the name attribute in a tag. The value of name cannot be an empty string.
throwOnTimeout	Optional. Yes or No. Specifies how timeout conditions are handled. If the value is Yes, an exception is generated to provide notification of the timeout. If the value is No, execution continues past the </cflock> tag. Default is Yes.
type	Optional. readOnly or Exclusive. Specifies the type of lock: read-only or exclusive. Default is Exclusive. A read-only lock allows more than one request to read shared data. An exclusive lock allows only one request to read or write to shared data.

Usage

ColdFusion Server is a multi-threaded web application server that can process multiple page requests at a time. Use cflock to guarantee that concurrently executing requests do not manipulate shared data structures, files, or CFXs inconsistently.

Note the following:

• Using cflock around CFML constructs that modify shared data ensures that the modifications occur sequentially, not concurrently.
• 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. A C++ CFX that maintains and manipulates shared (global) data structures must 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.

Scope

When you display, set, or update variables in a shared scope, use the scope attribute to identify the scope as Server, Application or Session.

In the ColdFusion Administrator, the Locking page, under the Server section, lets you set characteristics of the locking schema according to scope. The following table shows which features are available for Server, Application, and Session scope.

Feature	Availability:	Server	Application	Session
No automatic checking or locking		Yes	Yes	Yes
Full checking		Yes	Yes	Yes
Automatic read locking		Yes	Yes	Yes
Single Threaded Sessions				Yes

Each feature that you select has tradeoffs:

• No automatic checking or locking. No reads or writes are locked or checked for correct protection. Select this only after you have run with full checking and know that there are no errors to handle, and that all locking is handled programmatically. This feature provides the fastest performance.
• Full checking. All unlocked accesses are detected. Select this when you are in debug mode. This feature slows performance.
• Automatic read locking. All reads are locked. Unlocked writes cause an error. This feature slows down performance considerably.
• Single-threaded sessions: The request must finish before another request for the same session is processed. This feature may have an effect on performance depending on the request pattern. For example, the total response time may increase if an application has multiple frames that can be refreshed at once, thus causing multiple requests to queue and wait to be processed.

For more information, see Advanced ColdFusion Administration.

If you create a lock with the name attribute, not with the scope attribute, and enable full lock checking in the ColdFusion Administrator, ColdFusion returns an error.

• If the named lock is in the application scope, do not specify full checking for the application scope.
• If the lock is in the session scope, do not specify full lock checking for the session scope.
• If the lock is in the server scope, do not specify full lock checking for the server scope.

Deadlocks

The cflock tag uses kernel level synchronization objects that are released automatically upon timeout and/or abnormal termination of the thread that owns them. Therefore, ColdFusion never deadlocks for an infinite period of time while processing a cflock tag. However, very large timeouts can block request threads for long periods of time and radically decrease throughput. Always use the minimum timeout value allowed.

Another cause of blocked request threads is inconsistent nesting of cflock tags and inconsistent naming of locks. If you nest locks, you and everyone accessing the locked variables must consistently nest cflock tags in the same order. If everyone accessing locked variables does not adhere to these conventions, a deadlock can occur. A deadlock is a state in which no request can execute the locked section of the page. All requests to the protected section of the page are blocked until there is a timeout. The following tables show two scenarios that cause deadlocks.

Deadlock Scenario  with Two Users
User 1	User 2
Locks the session scope.	Locks the application scope.
Deadlock: Tries to lock application scope, but it is already locked by User 2.	Deadlock: Tries to lock the session scope, but it is already locked by User 1.

The following deadlock scenario could take place if you tried to nest a write lock after a read lock:

Deadlock Scenario With One User
User 1
Locks the session scope with a read lock.
Attempts to lock the session scope with an exclusive lock.
Deadlock: Attempts to lock the session scope with an exclusive lock, but cannot because the scope is already locked for reading.

The following code shows this scenario:

<cflock timeout = "60" scope = "SESSION" type = "readOnly">

  ...............

  <cflock timeout = "60" scope = "SESSION" type = "Exclusive">

  .........

  </cflock>

</cflock>

Once a deadlock occurs, neither user can break the deadlock, because the execution of their requests is blocked until the deadlock can be resolved by a lock timeout.

To avoid a deadlock, you and all who nest locks should do so in a well-specified order and name the locks consistently. If you must lock access to the server, application, and session scopes, you must do so in the following order.

1. Lock the session scope. In the cflock tag, indicate the scope by specifying "SESSION" as the value of the scope attribute.
2. Lock the application scope. In the cflock tag, indicate scope by specifying "Application" as the value of the scope attribute.
3. Lock the server scope. In the cflock tag, indicate the scope by specifying "server" as the value of the scope attribute.
4. Unlock the server scope.
5. Unlock the application scope.
6. Unlock the session scope.

For more information on cflock, see Developing ColdFusion Applications.

Example

<!------------------------------------------------------------- 

  This example shows how cflock can be used to guarantee the

  consistency of data updates to variables in the Application, 

  Server, and Session scopes.

  You should copy the following code into an Application.cfm

  file in the snippets directory. 

--------------------------------------------------------------->

  <html>

  <head>

    <title>Define Session and Application Variables</title>

  </head>

  

  <BASEFONT face = "Arial, Helvetica" size = 2>

  <body bgcolor = "#FFFFD5">

  

  <H3>cfapplication Example</H3>

  

  <P>cfapplication defines scoping for a ColdFusion application and 

  enables or disables the storing of application and/or session

  variables. This tag is placed in a special file called

  Application.cfm that is run before any other CF template in a

  directory where the Application.cfm file appears.</P>

  

  <cfapplication name = "ETurtle" 

sessionTimeout = #CreateTimeSpan(0,0, 0, 60)# 

sessionManagement = "Yes">



<!--------------------------------------------------------------------- 

  Initialize the session and application variables that will be 

  used by E-Turtleneck. Use the session scope for the session 

  variables. 

----------------------------------------------------------------------> 

  <cflock scope = "Session" timeout = "30" type = "Exclusive">

    <cfif NOT IsDefined("session.size")>

      <cfset session.size = "">

    </cfif>

    <cfif NOT IsDefined("session.color")>

      <cfset session.color = "">

    </cfif>

  </cflock>



<!--------------------------------------------------------------------- 

  Use the application lock for the application variable. This

  variable keeps track of the total number of turtlenecks sold. The

  application lock should have the same name as specified in the 

  cfapplication tag. 

---------------------------------------------------------------------->

  <cflock scope = "Application" Timeout = "30" type = "Exclusive">

    <cfif NOT IsDefined("application.number")>

      <cfset application.number = 1>

    </cfif>

  </cflock>

  <cflock scope = "Application" timeout = "30" type = "readOnly">

    <cfoutput>

    E-Turtleneck is proud to say that we have sold

    #application.number# turtlenecks to date.

    </cfoutput>

  </cflock>

<!---------------------------------------------------------------------

  End of Application.cfm 

---------------------------------------------------------------------->   

<head>

<title>

cflock Example

</title>

</head>



<BASEFONT face = "Arial, Helvetica" size = 2>

<body bgcolor = "#FFFFD5">



<H3>cflock Example</H3>



<cfif IsDefined("form.submit")>

  <cfoutput>

    Thank you for shopping E-Turtleneck. Today you have

    chosen a turtleneck in size <b>#form.size#</b> and in the color

    <b>#form.color#</b>. 

  </cfoutput>

  

  <!----------------------------------------------------------------- 

   Lock session variables to assign form values to them. 

  -------------------------------------------------------------------> 

  <cflock scope = "Session" timeout = "30" type = "Exclusive">

    <cfparam name = session.size Default = #form.size#>

    <cfparam name = session.color Default = #form.color#>

  </cflock>

  <!------------------------------------------------------------------ 

  Lock application variable application.number to find the total number 

  of turtlenecks sold. 

  -------------------------------------------------------------------> 

  <cflock scope = "Application" timeout = "30" type = "Exclusive">

    <cfset application.number = application.number + 1>

  </cflock>

  

<cfelse><!--- Show the form only if it has not been submitted. --->



<form action = "cflock.cfm" method = "POST">

<P>Congratulations! You have just selected the longest wearing, most

comfortable turtleneck in the world. Please indicate the color

and size that you wish to buy.</P> 

<table cellspacing = "2" cellpadding = "2" border = "0">

<tr>

  <td>Select a color.</td>

  <td><select type = "Text" name = "color">

    <option>red

    <option>white

    <option>blue

    <option>turquoise

    <option>black

    <option>forest green

    </select>

  </td>

</tr>

<tr>

  <td>Select a size.</td>

  <td><select type = "Text" name = "size" >

    <option>XXsmall

    <option>Xsmall

    <option>small

    <option>medium

    <option>large

    <option>Xlarge

    </select>

  </td>

</tr>

<tr>

  <td>Press Submit when you are finished making your selection.</td>

  <td><input type = "Submit" name = "submit" value = "Submit"> 

  </td>

</tr>

</table>

</form>

</cfif>

</html>

Copyright © 2001, Macromedia Inc. All rights reserved.

---