FairCom DB API for C

ctdbLockRecord

Lock the current record using the manual record locking system.

Declaration

CTDBRET ctdbLockRecord(CTHANDLE Handle, CTLOCK_MODE Mode)

Description

ctdbLockRecord() manually locks the current record with the specified record lock mode.

This function can also be used to demote a WRITE lock currently held by a record (as long as that record has not been modified) by specifying one of the READ lock modes.

This function can also be used to release a lock currently held by a record by specifying the CTLOCK_FREE lock mode. Doing this is equivalent to calling ctdbUnlockRecord(), and since certain exceptions apply to record unlocking, the documentation for ctdbUnlockRecord() should be consulted. A list of the available record lock modes is in Record Lock Modes.

When using ctdbLockRecord() to demote or release a record lock, it does not matter if the record lock was originally acquired manually (by calling ctdbLockRecord()) or acquired automatically (via the session-wide record locking mechanism).

Handle [in] the record handle.

Mode [in] the new locking mode for the record.

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

Note that if the specified lock (READ or WRITE) cannot be obtained (because another client application or thread already has a conflicting lock on that record, for example), then the record read will either block (the "_BLOCK" locking modes), or fail with an error (the locking modes that do not end with the word "_BLOCK").

Usage Note:

Although the current record is locked after calling ctdbLockRecord(), the buffered record data could have been modified by another user before the ctdbLockRecord() call was made. Call ctdbReadRecord() to re-read the locked record to avoid this potential for stale data.

In most cases it is more efficient to use the other record locking mechanism provided by the FairCom DB API API (session-wide record locking), which is not subject to this problem. With session-wide record locking, you first call ctdbLock() to turn on session-wide record locking, and then, each time you make a call that reads, writes, or deletes a record, the record is automatically locked before it is read from disk / written to disk. See the ctdbLock() function for more details.

Note: Manual record locking should NOT be used in situations where a given table is open / active more than once at the same time, in the same session, using two different table handles, because unexpected locking / unlocking behavior can result. For more details, in client/server situations, see FairCom Server enhanced locking control for files opened multiple times in the same connection. If you need to have the same table open more than once at the same time, please use session-wide record locking (see ctdbLock()).

Returns

ctdbLockRecord() returns CTDBRET_OK on success, or FairCom DB API C API error code on failure. If there is no current record, ctdbLockRecord() returns CTDBRET_NOTACTIVE (4012).