c-treeDB API for C++ - Developers Guide

Locking

The most significant difference between coding applications for single-user environments and multi-user environments (including local area networks) has to do with performing record updates (rewrites) and record deletions.

The basic problem is that to perform a record update or deletion in a multi-user system, you must own a record lock on the record of interest. Locks should be acquired when the user reads the record in preparation for updates, and the programmer should not relinquish the lock until the update is completed. However, one must be careful to ensure that locks are held for the shortest time possible or the performance of the application will be adversely affected.

Two types of locks can be applied to a record:

• A READ lock (also called a "shared" lock) on a record allows an unlimited number of other READ locks on that record (from other threads, etc), but prevents WRITE locks.
• A WRITE lock (also called an "exclusive" lock) prevents any other locks (of either type) on that record.

The c-treeDB API provides two methods of acquiring these record locks – session-wide record locking (discussed in Starting Session-Wide Locking below) and manual record locking (discussed in the Working with Records / Record Locking section). Session-wide locking is the preferred method, because it is safer:

• With session-wide record locking, you turn on automatic locking, and then any subsequent record reads, writes, or deletions will be automatically locked with the specified lock type.
• With manual record locking, you read a record and then lock it "by hand", by calling a "Lock Record" function, which leaves a window of opportunity for another thread to modify or delete the record after you read it and before you lock it. That is why session-wide locking is the preferred method of acquiring record locks.

In This Section Starting locks Lock modes Freeing locks Freeing locks associated with a table