FogBugz Plugin API > Database-level Locking
The CLockApi class allows plugin developers to manage database table locks. CPluginApi.Lock an always-accessible instance of the CLockApi class.
When you need to synchronize access to a table, you use a database-level lock. You can't use a .NET lock, because your FogBugz instance might be running on more than one server (such as On Demand or if you run multiple webservers against the same, separate database server).
In Project Backlog, We couldn't write a single query to update the iBacklog field while making the changes cascade to the other cases' iBacklogs, so we had to use more than one SQL query. However, due to the interrelated nature of the queries, it would be very, very bad if the update didn't happen atomically. If 2 people tried to update the backlog at once, calculations would be run on stale data, and the backlog order column would become inconsistent and permanently incorrect as future updates would increment or decrement them without knowing they were wrong. To prevent this, we take a lock -- this is a cooperative method of ensuring other ProjectBacklog instances don't mess with the data while we're working on it.
In general, always use a lock when you have more than one query and the later queries depend on data from the earlier queries, and always release the lock as soon as possible (NEVER forget to release a lock!)
A lock is named, and plugin locks are automatically named P23_XYZ internally, where P23 is your plugin prefix. This way, if you ask for lock XYZ, you will get your plugin's lock P23_XYZ, and you can't interfere with other plugins/FogBugz-core locks.