<CFLOCK TIMEOUT="timeout in seconds " SCOPE="Application" or "Server" or "Session" NAME="lockname" THROWONTIMEOUT="Yes/No" TYPE= "ReadOnly/Exclusive "> <!--- CFML to be synchronized ---> </CFLOCK>
The CFLOCK tag provides two types of locks to ensure the integrity of shared data:
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 are allowed to 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 only be used when the shared data will only be read and not modified. If another request already has an exclusive lock on the shared data, the request will wait for the exclusive lock to be released before it can obtain it.
Required. Specifies the maximum amount of time in seconds to wait to obtain an lock. If a lock can be 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.
Optional. Specifies the scope as one of the following: Application, Server, or Session. This attribute is mutually exclusive with the NAME attribute. See the Scope section for valuable information.
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. This attribute is mutually exclusive with the SCOPE attribute. Therefore, do not specify the SCOPE attribute and the NAME attribute in the same tag. Note that the value of NAME cannot be an empty string.
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.
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. See the following Note.
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:
Within the ColdFusion Administrator, the Locking page, under the Server section, allows you to set different characteristics of the locking schema according to scope.The following table shows which features are available for Server, Application, and Session scope.
Features | 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.
For an analysis of best practices with respect to locking, please refer to Administering ColdFusion Server.
See CFML Language Reference for information about deadlocks.