|
|
|
ctdbLock
Turn the automatic session-wide record locking mechanism on or off.
Declaration
CTDBRET ctdbLock(CTHANDLE Handle, CTLOCK_MODE mode)
Description
ctdbLock adjusts the current session-wide record lock mode used by the lock manager. Session-wide record locking is one of the two methods provided by the c-treeDB API to lock records. This method (session-wide locking) is the recommended method of locking records, because this method automatically locks the record as it is read from the table file, as opposed to manually locking the record AFTER it has been read, which leaves a window of opportunity for another thread to modify or delete the record after you read it and before you locked it. This function is used to turn the session-wide locking system on and off, suspend and un-suspend it, etc. This function is NOT used to manipulate the lock status of individual records.
After a call to ctdbLock with a mode other than CTLOCK_FREE or CTLOCK_SUSPEND, all operations involving file reads will be automatically locked. For example, all records read (ctdbFirstRecord, ctdbNextRecord, ctdbLastRecord, ctdbFindRecord, etc.) after a call to ctdbLock, will be automatically locked as they are read in from the table file on disk.
To manually lock only the current record using the other record locking mechanism provided by the c-treeDB API API, use ctdbLockRecord.
Note: Calling ctdbLock() does not actually lock any files or records. Instead, it sets an internal flag to indicate that all new record reads will automatically lock the records with the given lock mode.
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").
To turn off session-wide record locking and release the locks on some records, call ctdbUnlock(), or call ctdbLock() with the mode set to CTLOCK_FREE. There are various subtlties about how this works and which locks get released and which do not. For the details, please see the writeup for the ctdbUnlock() function. For more details about how session-wide locking is used, see the section titled Locking.
Note: Mixing ctdbLockRecord() and ctdbLock() may result in DLOK_ERR (42) returns when an automatic lock is attempted on a manually locked record, or vice versa. DLOK_ERR (42) simply means a lock could not be obtained. Check sysiocod for the system-level error to determine why the record could not be locked. In the example above, a locked record cannot be re-locked.
Returns
ctdbLock() returns CTDBRET_OK on success, or c-treeDB API C API error code on failure. Related common errors to are:
See Also
ctdbCommit(), ctdbAbort(), ctdbIsLockActive(), ctdbUnlock(), ctdbGetLockMode(), ctdbLockRecord(), ctdbSetKeepLock(), ctdbUnlockTable(), Session-Wide Lock Modes, Locking
