User Guide

cflock 271
Attributes
Note: Limit the scope of code that updates shared data structures, files, and CFXs. Exclusive locks
are required to ensure the integrity of updates, but read-only locks are faster. In a performance-
sensitive application, substitute read-only locks for exclusive locks where possible; for example, when
reading shared data.
Usage
ColdFusion MX is a multithreaded server; it can process multiple page requests at a time. Use the
cflock tag for these purposes:
• To ensure that modifications to shared data and objects made in concurrently executing
requests occur sequentially.
• Around file manipulation constructs, to ensure that file updates do not fail because files are
open for writing by other applications or tags.
• Around CFX invocations, to ensure that ColdFusion can safely invoke CFXs that are not
implemented in a thread-safe manner. (This applies only to CFXs developed in C++.)
Attribute Req/Opt Default Description
timeout Required Maximum length of time, in seconds, to wait to obtain a
lock. If lock is obtained, tag execution continues.
Otherwise, behavior depends on
throwOnTimeout attribute
value. If you set
timout="0", the timeout is determined by
the "Timeout Requests after x" setting in the ColdFusion
MX Administrator Settings page, if that setting is enabled.
However, if the setting is not enabled, and you set
timeout="0", ColdFusion can wait indefinitely to obtain the
lock.
scope Optional Lock scope. Mutually exclusive with the name attribute.
Lock name. Only one request in the specified scope can
execute the code within this tag (or within any other
cflock
tag with the same lock scope) at a time.
• Application
• Server
• Session
name Optional Lock name. Mutually exclusive with the
scope attribute.
Only one request can execute the code within a
cflock tag
with a given name at a time. Cannot be an empty string.
Permits synchronizing access to resources from different
parts of an application. Lock names are global to a
ColdFusion server. They are shared among applications
and user sessions, but not clustered servers.
throwOnTimeout Optional yes How timeout conditions are handled:
• yes: exception is generated for the timeout.
• no: execution continues past this tag.
type Optional Exclusive • readOnly: lets more than one request read shared data.
• exclusive: lets one request read or write shared data.