# Using CFLOCK for Exclusive Locking

The CFLOCK tag provides a means of implementing exclusive locking in ColdFusion applications. The reasons you use CFLOCK include :

- Protecting sections of code that manipulate shared data, such as session, application, and server variables.
- Ensuring that file updates do not fail because files are open for writing by other applications or ColdFusion tags.

Note | Use anonymous locks to protect a portion of a template, for example a non-thread safe CFX. Use named locks to prevent parallel access to data.

### How CFLOCK works

The CFLOCK tag can single-thread access to the CFML constructs in its body, so that the body of the tag can be executed by at most one request at a time. By default, 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.

However, ColdFusion offers provisions for allowing read-only access to locked code. The CFLOCK tag offers two modes of locking:

- Exclusive locks allow only one request to process the locked code.
- Read-only locks allow multiple requests to execute concurrently, provided that no exclusive locks are executing.

Note | Unless you specify the TYPE attribute, the default lock is exclusive. You should minimize the use of exclusive locks. If you have performance- sensitive code inside CFLOCK tags, consider adding the TYPE="ReadOnly" attribute to CFLOCK tags that do not update shared data.

## Using CFLOCK

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.
- 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 time-out and/or abnormal termination of the thread that owns it. Therefore, ColdFusion will never deadlock for an infinite period of time while processing a CFLOCK tag. However, very large time- outs can block request threads for long periods of time and thus radically decrease throughput. Always use the minimum time-out value allowed.

## Avoiding deadlocks

Be sure to nest CFLOCK tags consistently. A potential cause of blocked request threads is inconsistent nesting of CFLOCK tags and inconsistent naming of locks. If you are nesting locks, you and everyone accessing the locked variables must consistently nest CFLOCK tags in the same order and use the same lock name for each scope. 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. Thus, all requests to the protected section of the page are blocked until there is a time-out. The following table shows one scenario that would cause a deadlock.

Deadlock Scenario
User 1 | User 2
--- | ---
Locks the session scope. | Locks the application scope.
Deadlock: Tries to lock application scope, but application scope is already locked by User 2. | Deadlock: Tries to lock session, but session is already locked by User 1.

Once a deadlock occurs neither of the users can do anything to break the deadlock, because the execution of their requests is blocked until the deadlock can be resolved by a lock time-out.

In addition, if you nest locks of different types, you can cause a deadlock. An example of this is nesting an exclusive lock inside a read lock of the same scope, or of the same name.

In order to avoid a deadlock, you and all who need to nest locks should do so in a well-specified order and name the locks consistently. In particular, if you need to 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, specify thescope as "session."
2. Lock the application scope. In the CFLOCK tag, specify the scope as "application."
3. Lock the server scope. In the CFLOCK tag, specify the scope as "server."
4. Unlock the server scope.
5. Unlock the application scope.
6. Unlock the session scope.

Note | You can skip any pair of lock/unlock steps in the list above if you don't need to lock a particular scope. For example, you can take out Steps 3 and 4 if you don't need to lock the server scope.