Definition
ColdFusion locking, implemented with the CFML tag
Why Locking Exists
ColdFusion is multi-threaded: multiple requests, Scheduled tasks, CFTHREADs, WebSocket events, and gateway events can execute at the same time. Without coordination, two requests might:
- Update the same structure in Application scope and overwrite each other.
- Increment a counter in Session scope and lose counts because increments are not atomic.
- Initialize the same singleton twice during a traffic spike.
Locks ensure mutual exclusion or controlled shared read access, preventing data corruption and intermittent bugs that are hard to reproduce.
How cflock Works
Lock Types: exclusive vs. read-only
- exclusive: Only one thread may enter the locked section at a time. Use for writes/updates or any multi-statement logic that must be atomic.
- readonly: Multiple threads can enter simultaneously, but none can enter if an exclusive lock of the same name/scope is held. Use for safe, concurrent reads.
Key idea: Locks serialize access based on a shared identity (the lock name or scope). A read-only lock allows many concurrent readers; an exclusive lock blocks both readers and writers.
Name vs. Scope: what are you locking?
CFLOCK identifies the thing being locked either by a custom name or by a scope:
- name=”string”: A logical lock key shared across the server. Use when you need a specific, cross-scope lock (e.g., “InventoryCacheLock”).
- scope=”Application|Session|Server”: ColdFusion derives an internal lock name from the scope. This is often safer and more precise:
- scope=”Session”: Locks only this user’s session data (per-session lock).
- scope=”Application”: Locks the application’s shared memory, across all users of that application.
- scope=”Server”: Locks across the entire CF instance (all applications on that server).
Use either name or scope, not both. Choosing the right granularity prevents unnecessary contention.
Timeouts and Error handling
- timeout (seconds): Maximum time to wait for the lock. If it can’t be acquired in time and throwOnTimeout is true (default), ColdFusion throws a lock timeout exception.
- throwOnTimeout=”false”: Instead of throwing, proceed after the timeout. You can then handle a partial failure path gracefully.
Tip: Timeouts protect you from indefinite waiting during deadlocks or long-running sections. Keep timeouts reasonable based on your workload.
Nested locks and deadlocks
- You can nest locks, but be cautious. Acquiring multiple locks in different orders across code paths can cause deadlocks.
- Best practice: If you must nest, always acquire locks in the same global order (e.g., Server → Application → Session). Keep critical sections short.
Syntax and Core Patterns
Tag-based Syntax
Example: protect a session update with an exclusive lock.
- scope=”Session” narrows lock to this user’s session.
- exclusive because we are writing.
Script-based syntax
lock scope=”application” type=”readonly” timeout=2 {
// Safe concurrent reads of application state
price = application.catalog[itemId].price;
}
lock name=”InventoryCacheLock” type=”exclusive” timeout=10 throwOnTimeout=true {
// Update shared cache/map atomically
application.inventory[itemId] = newQty;
}
Pattern: Application initialization (double-checked)
Goal: Initialize a singleton once, even under bursty traffic.
if (!structKeyExists(application, “mailer”)) {
lock scope=”application” type=”exclusive” timeout=5 {
if (!structKeyExists(application, “mailer”)) {
application.mailer = createObject(“component”, “lib.Mailer”).init();
}
}
}
- The outer check avoids locking for normal requests.
- The inner check prevents duplicate initialization if several threads reached the lock simultaneously.
Pattern: Safe counters and aggregates
For reading the counter:
Real-World Use Case: Caching with Refresh-on-Expire
Scenario: A product catalog is cached in Application scope to avoid hitting the database on every request. When the cache expires, multiple concurrent requests might all try to refresh it from the DB, spiking load.
Step-by-step:
- Read cache under a readonly lock to get current metadata (timestamp, version).
- If expired, attempt an exclusive lock on the same scope/name.
- Inside the exclusive lock, check again (double-check) because another thread may have refreshed it already.
- If still expired, refresh from DB, then write back.
- Release exclusive lock; subsequent readers see fresh data.
This pattern prevents thundering herd refreshes and keeps read Performance high.
Use Cases You Should Consider
- Protecting shared structures in Application or Server scopes (caches, registries, feature flags).
- Multi-statement updates to Session data (Shopping carts, preferences).
- Singleton/service initialization and lazy loading.
- Coordinating cfthread producers/consumers with a shared queue.
- Serializing writes to files or logs (if multiple requests write to the same file).
- Guarding computed values that depend on current and previous state.
Best practices
- Keep locked sections small and fast. Do not do network calls, heavy queries, or file I/O inside a lock if you can avoid it.
- Use readonly locks for reads; reserve exclusive locks for writes.
- Prefer scope-based locks when guarding scope data; they provide the right granularity (per session, per app, per server).
- Choose clear, unique names for name-based locks to avoid unintentional cross-feature contention.
- Set timeouts thoughtfully and handle timeouts with fallbacks or retries where appropriate.
- Avoid nested locks; when unavoidable, lock in a consistent order across the codebase.
- Validate that any third-party code you call inside a lock is quick and does not attempt to acquire conflicting locks.
- Document your Locking strategy to help future maintainers reason about concurrency.
Common pitfalls
- Forgetting to lock multi-step operations on shared scopes, leading to Race conditions (e.g., check-then-set bugs).
- Using a single, broad lock name for unrelated Features, causing unnecessary contention.
- Placing heavy operations inside locks, leading to lock timeouts and poor throughput.
- Assuming database transactions replace application-level locking. DB transactions protect tables, not your memory-resident CF Data structures.
- Believing cluster-wide safety: CFLOCK coordinates threads within the same CF instance. It is not a distributed lock. In a clustered environment, use a shared/distributed locking mechanism (e.g., Redis, database advisory locks) for cross-node coordination.
Performance Considerations and Alternatives
- Lock contention reduces concurrency. Use finer-grained locks (per-key, per-session) instead of global ones.
- Consider immutable data patterns: swap references to new structures rather than mutating in place; this reduces the need for exclusive locks.
- Use read-mostly patterns: serve reads under readonly locks and batch writes.
- For inter-node coordination in clusters, use distributed locks or design the system to avoid shared mutable state at the application layer.
- Some CF servers/frameworks provide caching with built-in concurrency controls; use those when available to avoid reinventing locking.
Key Points
- CFLOCK provides Thread safety by coordinating access to Shared resources.
- Choose exclusive for writes, readonly for concurrent reads.
- Use scope-based locks (Session, Application, Server) for appropriate granularity.
- Keep critical sections short; set timeouts and handle throwOnTimeout.
- Plan for clusters: CFLOCK is instance-local, not cluster-wide.
Syntax Quick reference
- Tag:
-
… -
…
-
- Script:
- lock scope=”application” type=”exclusive” timeout=5 { … }
- lock name=”MyLock” type=”readonly” timeout=2 throwOnTimeout=false { … }
FAQ
What happens if a CFLOCK times out?
If the lock cannot be acquired within the specified timeout and throwOnTimeout is true, ColdFusion throws a lock timeout exception. If throwOnTimeout is false, the code after the lock statement runs without acquiring the lock, so you must handle that case to avoid inconsistent state.
Do I need CFLOCK for single-variable reads or writes?
A single assignment is not guaranteed to be atomic across threads for complex structures. Simple reads of immutable values are typically safe, but multi-statement logic or mutations of structures (arrays, structs) should be protected. When in doubt, lock.
Is CFLOCK cluster-aware?
No. CFLOCK coordinates threads within a single ColdFusion instance. For multi-server clusters, use distributed coordination (database locks, Redis, Hazelcast, etc.) if you must protect Shared resources across nodes.
Are Session variables automatically locked by ColdFusion?
ColdFusion does not automatically lock your multi-statement operations. Even if using J2EE sessions, you still need CFLOCK when you perform multiple related reads/writes that must be atomic.
Can I nest locks?
Yes, but it’s risky. Always acquire locks in a consistent order and keep critical sections short to avoid deadlocks and timeouts.
