FairCom DB API for C

Record Locking

A manual record lock can be acquired by performing the following actions:

1. Read a record from disk and set up a record handle that points at that record by calling ctdbFirstRecord(), ctdbLastRecord(), ctdbNextRecord(), ctdbPrevRecord(), ctdbSeekRecord(), ctdbFindRecord(), or ctdbFindTarget() functions.
2. Lock the record by calling ctdbLockRecord()

Note that using this manual record locking method is not the safest approach, because a record lock can not be applied until after the record is read from disk. This means there is a window of opportunity for the record to be modified or deleted by another thread before the record is locked. Fortunately, the FairCom DB API API provides a safer locking mechanism than manual locking: session-wide locking. This locking mechanism automatically locks records as they are read from disk, thereby removing the afore-mentioned window of opportunity, resulting in improved data security. Session-wide record locking is discussed further in Data Integrity.

Release a record lock by calling ctdbUnlockRecord() or by calling ctdbLockRecord() with CTLOCK_FREE mode. Note that, in certain situations, calling these functions might not immediately release the lock. See ctdbUnlockRecord() for more details.

In This Section Check if a record is locked Demoting record locks

Check if a record is locked

Call ctdbGetRecordLock() to retrieve the current lock mode acquired for the current record. If the record is not locked, ctdbGetRecordLock() returns CTLOCK_FREE. If the current record is locked, ctdbGetRecordLock() returns the record lock mode.

/* check if record is locked */

if ctdbGetRecordLock(hRecord) != CTLOCK_FREE)

printf("The record is locked\n");

The following record modes are returned by ctdbGetRecordLock():

Lock mode	Explanation
CTLOCK_FREE	The record is not locked
CTLOCK_READ	The record has a read lock
CTLOCK_WRITE	The record has a write lock

Demoting record locks

If a record has acquired a write lock (also called an "exclusive" lock), it is possible to change or demote the write lock to a read lock (also called a "shared lock"), if the record has not been updated. Use ctdbLockRecord() to demote a record from a write lock to a read lock.

/* demote a write lock to a read lock */

if (ctdbGetRecordLock(hRecord) == CTLOCK_WRITE)

if (ctdbLockRecord(hRecord, CTLOCK_READ) != CTDBRET_OK)

printf("Record lock demote failed\n");